Charge events in run

POST 
/v2/actor-runs/:runId/charge

Charge for events in the run of your pay per event Actor. The event you are charging for must be one of the configured events in your Actor. If the Actor is not set up as pay per event, or if the event is not configured, the endpoint will return an error. The endpoint must be called from the Actor run itself, with the same API token that the run was started with.

Learn more about pay-per-event pricing

For more details about pay-per-event (PPE) pricing, refer to our PPE documentation.

Request

Path Parameters

runId string required
Actor run ID.

Example: 3KH8gEpp4d8uQSe8T

Header Parameters

idempotency-key string
Always pass a unique idempotency key (any unique string) for each charge to avoid double charging in case of retries or network errors.

Example: 2024-12-09T01:23:45.000Z-random-uuid

Bodyrequired

Define which event, and how many times, you want to charge for.

• eventName string required
  Example: ANALYZE_PAGE
• count integer required
  Example: 1

Status 201

The charge was successful. Note that you still have to make sure in your Actor that the total charge for the run respects the maximum value set by the user, as the API does not check this. Above the limit, the charges reported as successful in API will not be added to your payouts, but you will still bear the associated costs. Use the Apify charge manager or SDK to avoid having to deal with this manually.

Status 400

Bad request - invalid input parameters or request body.

{
  "error": {
    "type": "invalid-input",
    "message": "Invalid input: The request body contains invalid data."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Status 401

Unauthorized - authentication required or invalid token.

{
  "error": {
    "type": "token-not-valid",
    "message": "Authentication token is not valid."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Status 403

Forbidden - insufficient permissions to perform this action.

{
  "error": {
    "type": "permission-denied",
    "message": "You do not have permission to perform this action."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Status 404

Not found - the requested resource does not exist.

{
  "error": {
    "type": "record-not-found",
    "message": "The requested resource was not found."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Status 405

Method not allowed.

{
  "error": {
    "type": "method-not-allowed",
    "message": "This API end-point can only be accessed using the following HTTP methods: OPTIONS,GET"
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Status 413

Payload too large - the request body exceeds the size limit.

{
  "error": {
    "type": "request-too-large",
    "message": "The POST payload is too large (limit: 9437184 bytes, actual length: 10485760 bytes)."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Status 415

Unsupported media type - the Content-Encoding of the request is not supported.

{
  "error": {
    "type": "unsupported-content-encoding",
    "message": "Content-Encoding \"bla\" is not supported."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Status 429

Too many requests - rate limit exceeded.

{
  "error": {
    "type": "rate-limit-exceeded",
    "message": "You have exceeded the rate limit. Please try again later."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)