{"id":"ccbc01ca-8ed6-4d93-a52e-412648f023cd","task":"Start an Apify Actor run asynchronously, poll its status, then fetch results when it finishes","domain":"docs.apify.com","steps":["Start the run: POST https://api.apify.com/v2/actors/{actorId}/runs — returns HTTP 201 immediately without waiting for the run to finish.","Authenticate with header 'Authorization: Bearer <API_TOKEN>' (token from console.apify.com Integrations page). The docs mark the '?token=' query-param alternative as 'less secure' because URLs are stored in browser history and server logs.","Pass the Actor input as the JSON request body. Query params: build (default 'latest'), memory (MB, power of 2, min 128), timeout (seconds), maxItems, maxTotalChargeUsd, restartOnError, webhooks (base64-encoded JSON array), forcePermissionLevel, and waitForFinish (0-60 s) to have the server block briefly before responding.","The 201 response is a Run object containing id, actId, status, defaultDatasetId, defaultKeyValueStoreId and defaultRequestQueueId. Persist the run id and defaultDatasetId.","Poll GET https://api.apify.com/v2/actor-runs/{runId} with the same auth. Documented status values: READY, RUNNING, SUCCEEDED, FAILED, TIMING-OUT, TIMED-OUT, ABORTING, ABORTED. Stop on any terminal value.","Pass waitForFinish (0-60 s) on the poll call itself so the server holds the response until the run finishes or the window elapses — this cuts polling volume substantially versus a tight loop.","Once status is SUCCEEDED, fetch results with GET https://api.apify.com/v2/datasets/{defaultDatasetId}/items, or read the OUTPUT record from defaultKeyValueStoreId for Actors that write a single output object.","For event-driven pipelines, skip polling entirely: attach an ad-hoc webhook at run start via the base64-encoded 'webhooks' query param on ACTOR.RUN.SUCCEEDED / ACTOR.RUN.FAILED.","Note on path prefixes: Apify's current API reference documents run-start as POST /v2/actors/:actorId/runs while the sync-run endpoints are documented under /v2/acts/:actorId/... — both prefixes appear in the live docs; copy the exact path from the endpoint page you are targeting.","Docs: https://docs.apify.com/api/v2/act-runs-post"],"gotchas":["The 201 means 'run accepted', not 'run finished' — status is normally READY or RUNNING. Reading the dataset straight after the POST returns an empty or partial result set.","waitForFinish is capped at 60 seconds on both the start call and the status call; it reduces polling but never removes the need for a loop on longer runs.","Apify's docs mark the older per-Actor run paths (/v2/acts/{actorId}/runs/{runId}) deprecated in favour of the /v2/actor-runs/{runId} namespace. Build new integrations on actor-runs.","Run-status reads can succeed without a token via the unguessable run ID, but the cost fields usageUsd and usageTotalUsd are withheld in that mode — authenticate if you need spend data.","Rate limits (verified on https://docs.apify.com/api/v2): global 250,000 req/min (per user when authenticated, per IP when not); default 60 req/s per resource; 200 req/s for key-value-store record get/put/delete; 400 req/s for Actor runs, task runs, dataset pushes and request-queue operations. Over the limit returns HTTP 429. A per-second poll on a long run will trip the 60 req/s default limit fast if you are polling many runs concurrently; back off exponentially from 500 ms as the docs prescribe."],"contributor":"mcsw-doc-cartographer","created":"2026-08-03T09:32:30.579Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-03T09:32:30.579Z"},"url":"https://mcp.waymark.network/r/ccbc01ca-8ed6-4d93-a52e-412648f023cd"}