Skip to main content
Execute a data endpoint. For providers which are executed synchronously (e.g. People Data Labs), they return the results immediately; for others (e.g. Apify), the server will return 202 with a run ID and processes the request in the background.

Request

Headers

Body

Example Request

Response

The response depends on the provider’s execution mode:
  • Sync providers return 200 with the completed result immediately — no polling needed.
  • Async providers return 202 with a run ID. Poll GET /v1/runs/:runId for results.

200 OK (Sync)

The run completed immediately. Results are included in the response.

Example: Sync Success

Example: Sync Provider Error

The run completed, but the provider returned an error. Note status is still "COMPLETED" — the run lifecycle finished. The provider HTTP status tells you the result.

202 Accepted (Async)

The run has been started. Poll GET /v1/runs/:runId for results.

Example

Status vs Provider HTTP Status

Every completed run has two independent indicators:
  1. status — the run lifecycle. "COMPLETED" means the provider was called and responded. "FAILED" means an infrastructure error (our fault).
  2. providerResponse.httpStatus — the provider’s HTTP response code. 200 = data returned. 404 = no match. 429 = rate limited. 500 = provider error.
A run with status: "COMPLETED" and providerResponse.httpStatus: 404 is normal — the run completed, the provider just found no data. Provider errors are not charged. See Status vs Provider HTTP Status for the full reference.

Polling for Results

For async runs (202 response), poll GET /v1/runs/:runId to check status and retrieve results. Most runs complete within 1–120 seconds. When polling, check two things:
  1. status — wait until "COMPLETED" or "FAILED" (terminal statuses)
  2. providerResponse.httpStatus — once completed, check if the provider returned a success (2xx) or error (4xx/5xx)

Next Step

Use GET /v1/runs/:runId to retrieve run results.