fix: Update maxItems and maxTotalChargeUsd desc (#2088)

michael-apify · web-flow · commit dfda9abbd63f · 2025-11-25T23:07:43.000+01:00
> [!NOTE] > Clarifies OpenAPI docs for `maxItems` (pay-per-result charge cap) and `maxTotalChargeUsd` (pay-per-event cost cap) across actor and task run endpoints, including env var references. > > - **OpenAPI (Actors & Actor tasks)** > - Update `maxItems` query param description in `actors/*run-sync*.yaml` and `actor-tasks/*run-sync*.yaml`: > - Clarifies it caps chargeable dataset items for pay-per-result actors, not returned items; references `ACTOR_MAX_PAID_DATASET_ITEMS`. > - Update `maxTotalChargeUsd` query param description in `actors/*runs*.yaml`, `actors/*run-sync*.yaml`, and `actor-tasks/*runs*.yaml`: > - Specifies it's used only for pay-per-event actors and references `ACTOR_MAX_TOTAL_CHARGE_USD`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 99fc4f1. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>
diff --git a/apify-api/openapi/components/parameters/actor-run-options/maxItems.yaml b/apify-api/openapi/components/parameters/actor-run-options/maxItems.yaml
@@ -0,0 +1,15 @@
+name: maxItems
+in: query
+required: false
+description: |
+  Specifies the maximum number of dataset items that will be charged for pay-per-result Actors.
+  This does NOT guarantee that the Actor will return only this many items.
+  It only ensures you won't be charged for more than this number of items.
+  Only works for pay-per-result Actors.
+  Value can be accessed in the actor run using `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
+style: form
+explode: true
+schema:
+  type: number
+  format: double
+  example: 1000
diff --git a/apify-api/openapi/components/parameters/actor-run-options/maxTotalChargeUsd.yaml b/apify-api/openapi/components/parameters/actor-run-options/maxTotalChargeUsd.yaml
@@ -0,0 +1,14 @@
+name: maxTotalChargeUsd
+in: query
+required: false
+description: |
+  Specifies the maximum cost of the run. This parameter is
+  useful for pay-per-event Actors, as it allows you to limit the amount
+  charged to your subscription. You can access the maximum cost in your Actor
+  by using the `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
+style: form
+explode: true
+schema:
+  type: number
+  format: double
+  example: 5
diff --git a/apify-api/openapi/components/schemas/actor-runs/RunOptions.yaml b/apify-api/openapi/components/schemas/actor-runs/RunOptions.yaml
@@ -18,3 +18,9 @@ properties:
   diskMbytes:
     type: number
     example: 2048
+  maxItems:
+    type: number
+    example: 1000
+  maxTotalChargeUsd:
+    type: number
+    example: 5
diff --git a/apify-api/openapi/paths/actor-runs/actor-runs@{runId}@resurrect.yaml b/apify-api/openapi/paths/actor-runs/actor-runs@{runId}@resurrect.yaml
@@ -38,22 +38,8 @@ post:
       schema:
         type: number
       example: 256
-    - name: maxItems
-      in: query
-      required: false
-      schema:
-        type: number
-      example: 1000
-      description: |
-        Optional number of items that the run should return. Used for pay-per-result Actors. The value can only be increased beyond the value specified when the Actor run was started.
-    - name: maxTotalChargeUsd
-      in: query
-      required: false
-      schema:
-        type: number
-      example: 10
-      description: |
-        Optional maximum cost of the run, in USD. Used for pay-per-event Actors. The value can only be increased beyond the value specified when the Actor run was started.
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       required: false
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml
@@ -55,20 +55,8 @@ get:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the task run should return. This is
-        useful for pay-per-result tasks, as it allows you to limit the number of
-        results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    # XXX: do we support maxTotalChargeUsd for task runs?
     - name: build
       in: query
       description: |
@@ -448,34 +436,8 @@ post:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the task run should return. This is
-        useful for pay-per-result tasks, as it allows you to limit the number of
-        results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
-    - name: maxTotalChargeUsd
-      in: query
-      description: |
-        Specifies the maximum cost of the task run. This is
-        useful for pay-per-event tasks, as it allows you to limit the amount
-        charged to your subscription. You can access the
-        maximum cost in your Actor by using the
-        `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 5
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       description: |
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml
@@ -52,20 +52,8 @@ get:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the task run should return. This is
-        useful for pay-per-result tasks, as it allows you to limit the number of
-        results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    # XXX: do we support maxTotalChargeUsd for task runs?
     - name: build
       in: query
       description: |
@@ -195,34 +183,8 @@ post:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the task run should return. This is
-        useful for pay-per-result tasks, as it allows you to limit the number of
-        results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
-    - name: maxTotalChargeUsd
-      in: query
-      description: |
-        Specifies the maximum cost of the task run. This parameter is
-        useful for pay-per-event tasks, as it allows you to limit the amount
-        charged to your subscription. You can access the
-        maximum cost in your Actor by using the
-        `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 5
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       description: |
diff --git a/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs.yaml b/apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs.yaml
@@ -187,34 +187,8 @@ post:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the Actor run should return. This is
-        useful for pay-per-result Actors, as it allows you to limit the number
-        of results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
-    - name: maxTotalChargeUsd
-      in: query
-      description: |
-        Specifies the maximum cost of the Actor run. This parameter is
-        useful for pay-per-event Actors, as it allows you to limit the amount
-        charged to your subscription. You can access the
-        maximum cost in your Actor by using the
-        `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 5
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       description: |
diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml
@@ -60,34 +60,8 @@ post:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the Actor run should return. This is
-        useful for pay-per-result Actors, as it allows you to limit the number
-        of results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
-    - name: maxTotalChargeUsd
-      in: query
-      description: |
-        Specifies the maximum cost of the Actor run. This parameter is
-        useful for pay-per-event Actors, as it allows you to limit the amount
-        charged to your subscription. You can access the
-        maximum cost in your Actor by using the
-        `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 5
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       description: |
@@ -471,34 +445,8 @@ get:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the Actor run should return. This is
-        useful for pay-per-result Actors, as it allows you to limit the number
-        of results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
-    - name: maxTotalChargeUsd
-      in: query
-      description: |
-        Specifies the maximum cost of the Actor run. This parameter is
-        useful for pay-per-event Actors, as it allows you to limit the amount
-        charged to your subscription. You can access the
-        maximum cost in your Actor by using the
-        `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 5
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       description: |
diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml
@@ -66,34 +66,8 @@ post:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the Actor run should return. This is
-        useful for pay-per-result Actors, as it allows you to limit the number
-        of results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
-    - name: maxTotalChargeUsd
-      in: query
-      description: |
-        Specifies the maximum cost of the Actor run. This parameter is
-        useful for pay-per-event Actors, as it allows you to limit the amount
-        charged to your subscription. You can access the
-        maximum cost in your Actor by using the
-        `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 5
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       description: |
@@ -236,34 +210,8 @@ get:
         type: number
         format: double
         example: 256
-    - name: maxItems
-      in: query
-      description: |
-        The maximum number of items that the Actor run should return. This is
-        useful for pay-per-result Actors, as it allows you to limit the number
-        of results that will be charged to your subscription. You can access the
-        maximum number of items in your Actor by using the
-        `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 1000
-    - name: maxTotalChargeUsd
-      in: query
-      description: |
-        Specifies the maximum cost of the Actor run. This parameter is
-        useful for pay-per-event Actors, as it allows you to limit the amount
-        charged to your subscription. You can access the
-        maximum cost in your Actor by using the
-        `ACTOR_MAX_TOTAL_CHARGE_USD` environment variable.
-      style: form
-      explode: true
-      schema:
-        type: number
-        format: double
-        example: 5
+    - $ref: "../../components/parameters/actor-run-options/maxItems.yaml"
+    - $ref: "../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml"
     - name: restartOnError
       in: query
       description: |
diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml
