Skip to main content
Every API runs as a job. You can get the rows in one request with ?wait=true, or start the job and poll for it. Use wait=true by default and poll when you expect a run to take minutes.

One request: ?wait=true

  • 60-second ceiling. If the job hasn’t finished, you get { "job_id": "...", "status": "running" }. Nothing is lost: the job keeps running, so poll it with that job_id. Lower the ceiling with &wait_timeout=15.
  • First 100 rows inline. Bigger results come back with "truncated": true. Fetch the rest from GET /v1/jobs/{job_id}/results or download them.
  • Failures come back at once as status: "failed" with error, error_code and retryable, still with HTTP 200. See Jobs and results.

Start and poll

For long runs, drop wait and poll.
1

Start the job

2

Poll for results every 2 seconds

While the job runs you get { "status": "running", "row_count": 0 }. That is normal, not an error. Stop polling on any end state: completed, failed, cancelled or rejected_balance.
Polling has its own, much larger rate limit and never uses up your allowance for starting runs.

A helper you can copy

It runs with wait=true and only falls back to polling when the job is still going or the result was truncated.
Running thousands of jobs? Keep wait=true and run a bounded pool of 20 to 50 requests in flight, rather than firing everything and polling each job.

Inputs

Send inputs under params. Each API’s page lists the keys it accepts, which are required, their types and allowed values. Any other key is rejected with 422 invalid_params, so don’t copy extra keys from a sample. Most APIs take a row limit such as maxResults, maxItems or maxReviews. Set it to cap how many rows, and how much money, a run uses. To see an API’s full schema, including every allowed value:

Retrying safely: Idempotency-Key

If a POST .../run times out or the connection drops, you can’t tell whether the run started. Send an Idempotency-Key header with a unique value per run, and the same value when you retry.
  • A retry with the same key within 24 hours returns the original job with header X-Idempotent-Replay: true. No new run, no new charge.
  • The same key with a different API or different params returns 422 idempotency_key_reused.
  • A request that was rejected (402, or 422 for bad params) booked nothing, so you can fix it and retry with the same key.

Request IDs

Every response carries an X-Request-ID header; on errors the same value is in error.request_id. Quote it when you contact support. You can send your own X-Request-ID (8 to 64 letters, digits, ., _ or -) and we’ll use it.