Poll an asynchronous run
Relays to https://api.apify.com/v2/actor-runs/{runId}, rewriting Authorization to the
secret Apify token; a client-sent token query parameter is discarded. Answers with the run
object — its status, and, once the run is terminal, its final usageTotalUsd.
Ownership-gated: only the account that created the run can read it. A run id belonging
to another account, and one that never existed, answer the same 404, with no upstream call
made on its behalf. The account-wide run list carries no id to gate, so it is not mounted
and 404s as well.
Polling costs nothing on its own. The first poll that observes a terminal status settles the
run’s exact usageTotalUsd plus the gateway’s 5.5% fee, once, against the account that
created it — repeated terminal polls do not charge again.
Authentication
Your per-client bearer token — the API key the gateway issued to you. Present it in
Authorization: Bearer <token> form. A token that is missing, unknown, or revoked draws a
401. Before the call is sent upstream the token is removed (stripped, or swapped for the
upstream’s own credential); it never makes it past the gateway.
Path parameters
The run, from data.id of the create that started it. Only the account that created the run
can name it: another account’s run id, and one that never existed, answer the same 404,
refused locally with no upstream call. A run you do own that Apify has since expired also
answers 404 — that read is authorized and reaches Apify, so what comes back is Apify’s own
answer rather than the local refusal.
Query parameters
Seconds to hold the response open waiting for the run to finish, up to Apify’s own maximum. The call still answers with the run object either way — it just may already be terminal, in which case the run’s exact usage, plus the gateway’s 5.5% fee, settles right there.
Response
Apify’s own run envelope, relayed as it arrived. data.status follows Apify’s run
lifecycle: READY and RUNNING while the run is live, SUCCEEDED, FAILED, TIMED-OUT,
or ABORTED once it is finished, with TIMING-OUT and ABORTING in between.
data.usageTotalUsd is a running total until the run is terminal — which is why nothing is
charged before then. Once terminal, that exact figure plus the gateway’s 5.5% fee is
charged once, to the account that created the run.