Start an Apify Actor run asynchronously, poll its status, then fetch results when it finishes

Documented steps

1. Start the run: POST https://api.apify.com/v2/actors/{actorId}/runs — returns HTTP 201 immediately without waiting for the run to finish.
2. 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.
3. 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.
4. The 201 response is a Run object containing id, actId, status, defaultDatasetId, defaultKeyValueStoreId and defaultRequestQueueId. Persist the run id and defaultDatasetId.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.
10. Docs: https://docs.apify.com/api/v2/act-runs-post