Apify

Run any of the 17,000+ Actors on Apify Store and retrieve structured results via the REST API.

Full OpenAPI spec: openapi.json

Authentication

All requests need the APIFY_TOKEN env var. Use it as a Bearer token:

CODEBLOCK0

Base URL: INLINECODE1

Core workflow

1. Find the right Actor

Search the Apify Store by keyword:

CODEBLOCK1

Actors are identified by username~name (tilde) in API paths, e.g. apify~web-scraper.

2. Get Actor README and input schema

Before running an Actor, fetch its default build to get the README (usage docs) and input schema (expected JSON fields):

CODEBLOCK2

INLINECODE4 is a JSON-stringified object — parse it to see required/optional fields, types, defaults, and descriptions. Use this to construct valid input for the run.

You can also get the Actor's per-build OpenAPI spec (no auth required):

CODEBLOCK3

3. Run an Actor (async — recommended for most cases)

Start the Actor and get the run object back immediately:

CODEBLOCK4

Response includes data.id (run ID), data.defaultDatasetId, data.status.

Optional query params: INLINECODE8

• - waitForFinish (0-60): seconds the API waits before returning. Useful to avoid polling for short runs.

4. Poll run status

CODEBLOCK5

Terminal statuses: SUCCEEDED, FAILED, ABORTED, TIMED-OUT.

5. Get results

Dataset items (most common — structured scraped data):

CODEBLOCK6

Or directly from the run (shortcut — same parameters):

CODEBLOCK7

Params: format (json|csv|jsonl|xml|xlsx|rss), fields, omit, limit, offset, clean, desc.

Key-value store record (screenshots, HTML, OUTPUT):

CODEBLOCK8

Run log:

CODEBLOCK9

6. Run Actor synchronously (short-running Actors only)

For Actors that finish within 300 seconds, get dataset items in one call:

CODEBLOCK10

Returns the dataset items array directly (not wrapped in data). Returns 408 if the run exceeds 300s.

Alternative: /run-sync returns the KVS OUTPUT record instead of dataset items.

Quick recipes

Scrape a website

CODEBLOCK11

Google search

CODEBLOCK12

Long-running Actor (async with polling)

CODEBLOCK13

Abort a run

CODEBLOCK14

Paid / rental Actors

Some Actors require a monthly subscription before they can be run. If the API returns a permissions or payment error for an Actor, ask the user to manually subscribe via the Apify Console:

CODEBLOCK15

Replace ACTOR_ID with the Actor's ID (e.g. AhEsMsQyLfHyMLaxz). The user needs to click Start on that page to activate the subscription. Most rental Actors offer a free trial period set by the developer.

You can get the Actor ID from the store search response (data.items[].id) or from GET /v2/acts/username~name (data.id).

Error handling

• - 401: APIFY_TOKEN missing or invalid.
• 404 Actor not found: check username~name format (tilde, not slash). Browse https://apify.com/store.
• 400 run-failed: check GET /v2/logs/RUN_ID for details.
• 402/403 payment required: the Actor likely requires a subscription. See "Paid / rental Actors" above.
• 408 run-timeout-exceeded: sync endpoints have a 300s limit. Use async workflow instead.
• 429 rate-limit-exceeded: retry with exponential backoff (start at 500ms, double each time).

Additional resources

• - API docs (LLM-friendly): https://docs.apify.com/api/v2.md
• OpenAPI spec: openapi.json
• Apify Store (browse Actors): https://apify.com/store