feat: add maxTotalChargeUsd param (#1485)

The `maxTotalChargeUsd` param is missing in API doc. I've searched for
`ACTOR_MAX_PAID_DATASET_ITEMS` and added info about `maxTotalChargeUsd`
to all relevant places.

---------

Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Author: novotnyj

apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml

@@ -462,6 +462,20 @@ post:
         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
     - name: build
       in: query
       description: |

apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml

@@ -209,6 +209,20 @@ post:
         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
     - name: build
       in: query
       description: |

apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs.yaml

@@ -201,6 +201,20 @@ post:
         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
     - name: build
       in: query
       description: |

apify-api/openapi/paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml

@@ -74,6 +74,20 @@ post:
         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
     - name: build
       in: query
       description: |
@@ -462,6 +476,20 @@ get:
         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
     - name: build
       in: query
       description: |

apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml

@@ -80,6 +80,20 @@ post:
         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
     - name: build
       in: query
       description: |
@@ -227,6 +241,20 @@ get:
         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
     - name: build
       in: query
       description: |

apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml

@@ -194,6 +194,20 @@ post:
         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
     - name: build
       in: query
       description: |

sources/platform/actors/development/programming_interface/environment_variables.md

@@ -35,6 +35,7 @@ Here's a table of key system environment variables:
 | `ACTOR_DEFAULT_REQUEST_QUEUE_ID` | Unique identifier for the default request queue associated with the current Actor run. |
 | `ACTOR_INPUT_KEY` | Key of the record in the default key-value store that holds the [Actor input](/platform/actors/running/input-and-output#input).  |
 | `ACTOR_MAX_PAID_DATASET_ITEMS` | For paid-per-result Actors, the user-set limit on returned results. Do not exceed this limit. |
+| `ACTOR_MAX_TOTAL_CHARGE_USD` | For pay-per-event Actors, the user-set limit on run cost. Do not exceed this limit. |
 | `APIFY_HEADLESS` | If **1**, web browsers inside the Actor should run in headless mode (no windowing system available). |
 | `APIFY_IS_AT_HOME` | Contains **1** if the Actor is running on Apify servers. |
 | `ACTOR_MEMORY_MBYTES` | Size of memory allocated for the Actor run, in megabytes. Can be used to optimize memory usage or finetuning of low-level external libraries. |

sources/platform/api_v2/api_v2_reference.apib

@@ -984,7 +984,8 @@ received in the response JSON to the [Get items](#reference/datasets/item-collec
     + token: `soSkq9ekdmfOslopH` (string, optional) - API authentication token. Public actors that are configured to be anonymously runnable do not require the token.
     + timeout: 60 (number, optional) - Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the actor.
     + memory: 256 (number, optional) - Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the actor.
-    + maxItems: 1000 (number, optional) - 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.
+    + maxItems: 1000 (number, optional) - 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.
+    + maxTotalChargeUsd: 5 (number, optional) - Specifies the maximum cost of the Actor run. This 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.
     + build: `0.1.234` (string, optional) - Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the actor (typically `latest`).
     + waitForFinish: 60 (number, optional) - The maximum number of seconds the server waits for the run to finish. By default, it is `0`, the maximum value is `60`. <!-- MAX_ACTOR_JOB_ASYNC_WAIT_SECS -->
                                              If the build finishes in time then the returned run object will have a terminal status (e.g. `SUCCEEDED`),
@@ -1021,7 +1022,8 @@ received in the response JSON to the [Get items](#reference/datasets/item-collec
                                                      in the response. By default, it is `OUTPUT`.
     + timeout: 60 (number, optional) - Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the actor.
     + memory: 256 (number, optional) - Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the actor.
-    + maxItems: 1000 (number, optional) - 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.
+    + maxItems: 1000 (number, optional) - 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.
+    + maxTotalChargeUsd: 5 (number, optional) - Specifies the maximum cost of the Actor run. This 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.
     + build: `0.1.234` (string, optional) - Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the actor (typically `latest`).
     + webhooks: `dGhpcyBpcyBqdXN0IGV4YW1wbGUK...` (string, optional) - Specifies optional webhooks associated with the actor run, which can be used to receive a notification
       e.g. when the actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see
@@ -1139,7 +1141,8 @@ To run the actor asynchronously, use the [Run actor](#reference/actors/run-colle
     + token: `soSkq9ekdmfOslopH` (string, optional) - API authentication token. Public actors that are configured to be anonymously runnable do not require token parameter.
     + timeout: 60 (number, optional) - Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the actor.
     + memory: 256 (number, optional) - Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the actor.
-    + maxItems: 1000 (number, optional) - 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.
+    + maxItems: 1000 (number, optional) - 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.
+    + maxTotalChargeUsd: 5 (number, optional) - Specifies the maximum cost of the Actor run. This 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.
     + build: `0.1.234` (string, optional) - Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the actor (typically `latest`).
     + webhooks: `dGhpcyBpcyBqdXN0IGV4YW1wbGUK...` (string, optional) - Specifies optional webhooks associated with the actor run, which can be used to receive a notification
       e.g. when the actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see
@@ -1751,7 +1754,8 @@ received in the response JSON to the [Get items](#reference/datasets/item-collec
     + token: `soSkq9ekdmfOslopH` (string, optional) - API authentication token.
     + timeout: 60 (number, optional) - Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.
     + memory: 256 (number, optional) - Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the task settings.
-    + maxItems: 1000 (number, optional) - 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.
+    + maxItems: 1000 (number, optional) - 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.
+    + maxTotalChargeUsd: 5 (number, optional) - Specifies the maximum cost of the Actor run. This 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.
     + build: `0.1.234` (string, optional) - Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the task settings (typically `latest`).
     + waitForFinish: 60 (number, optional) - The maximum number of seconds the server waits for the run to finish. By default, it is `0`, the maximum value is `60`. <!-- MAX_ACTOR_JOB_ASYNC_WAIT_SECS -->
       If the build finishes in time then the returned run object will have a terminal status (e.g. `SUCCEEDED`),
@@ -1789,6 +1793,7 @@ received in the response JSON to the [Get items](#reference/datasets/item-collec
     + timeout: 60 (number, optional) - Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.
     + memory: 256 (number, optional) - Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the task settings.
     + maxItems: 1000 (number, optional) - 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.
+    + maxTotalChargeUsd: 5 (number, optional) - 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.
     + build: `0.1.234` (string, optional) - Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the task settings (typically `latest`).
     + outputRecordKey: `OUTPUT` (string, optional) - Key of the record from run's default key-value store to be returned
       in the response. By default, it is `OUTPUT`.
@@ -1897,6 +1902,7 @@ To run the Task asynchronously, use the [Run task asynchronously](#reference/act
     + timeout: 60 (number, optional) - Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.
     + memory: 256 (number, optional) - Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the task settings.
     + maxItems: 1000 (number, optional) - 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.
+    + maxTotalChargeUsd: 5 (number, optional) - 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.
     + build: `0.1.234` (string, optional) - Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the task settings (typically `latest`).
     + webhooks: `dGhpcyBpcyBqdXN0IGV4YW1wbGUK...` (string, optional) - Specifies optional webhooks associated with the actor run, which can be used to receive a notification
       e.g. when the actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see