How to Run an Apify Actor by API in a Production Application

The safest production pattern is asynchronous: validate and store the input, start the Actor, persist the returned run ID, monitor the run to a terminal status, read the default dataset, validate the output contract, and deliver it idempotently to the consumer. Use synchronous execution only when the expected runtime and response size fit the calling system’s timeout budget.

What is the basic Actor API model?

Apify Actors take structured JSON input, execute a task, and produce structured output. According to the current Actors documentation, they can run through Console, API, CLI, schedules, or API clients.

The asynchronous API flow is:

1. POST an Actor run with JSON input.
2. Receive a run object and identifiers.
3. Poll or receive a webhook for terminal status.
4. Read results from the run’s default dataset or linked output.
5. Store delivery state in your application.

The official Run Actor endpoint returns immediately and exposes defaultDatasetId on the run object for typical dataset results.

What should be stored before the API call?

Create a local job record containing:

• an application request ID;
• Actor ID and chosen build/tag;
• validated input JSON and schema version;
• caller, tenant, or workflow owner;
• requested output contract;
• created time and retry count;
• an idempotency or deduplication key defined by your application.

This record exists even if the network fails before a run ID returns.

How should credentials be handled?

Keep the Apify token in secret storage and send it through an authorization header. Do not embed tokens in browser code, logs, public URLs, datasets, source repositories, or webhook query strings.

Apify’s storage documentation warns against sharing URLs containing authentication tokens. Redact input fields and headers before logging.

Synchronous or asynchronous?

Apify’s API tutorial notes that synchronous endpoints can run an Actor and return default dataset items, while asynchronous patterns better fit longer workflows. Review the current run-and-retrieve guide.

How should run statuses be handled?

Treat each documented terminal state explicitly. Persist the latest platform status, status message, timestamps, and usage metadata needed by the application. A successful HTTP request that starts a run is not a successful data job.

On failure:

• retain the run ID and logs link;
• categorize retryable network/platform failures separately from invalid inputs;
• cap retries with backoff;
• avoid creating duplicate downstream deliveries;
• expose a manual replay path.

How should datasets be consumed?

Apify datasets are append-only structured storage. The dataset documentation describes API retrieval, field selection, omission, and export formats including JSON, JSONL, CSV, XML, Excel, HTML, and RSS.

For production:

1. retrieve by defaultDatasetId from the completed run;
2. paginate rather than assuming one response contains everything;
3. validate required fields and types;
4. store source URLs and run metadata;
5. record the last delivered item/page;
6. mark delivery complete only after the consumer confirms it.

What provides idempotency?

Apify run creation and your business delivery are separate concerns. Your application should prevent duplicate requests and duplicate side effects.

Possible application keys include a normalized input hash plus schedule window, an upstream event ID, or a user-supplied request ID. The correct key depends on whether two identical inputs should create one run or intentionally create repeated snapshots.

Which observability signals matter?

Track:

• queue time, run time, and end-to-end delivery time;
• terminal status distribution;
• retry and replay count;
• output row count and required-field coverage;
• cost or charge signals exposed by the current pricing model;
• schema version and drift;
• consumer acknowledgment;
• links to Actor run and dataset for operators.

Do not rely on “API returned 201” as the service-level measure.

What should be tested before launch?

Test valid input, invalid input, empty output, partial/missing fields, long runtime, platform failure, timeout, caller restart, duplicate callback, duplicate delivery, expired credentials, and an Actor schema change.

Start by selecting the right contract in How to Choose an Apify Actor, then apply Scraped Data Quality Validation to the result.