?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 thatjob_id. Lower the ceiling with&wait_timeout=15. - First 100 rows inline. Bigger results come back with
"truncated": true. Fetch the rest fromGET /v1/jobs/{job_id}/resultsor download them. - Failures come back at once as
status: "failed"witherror,error_codeandretryable, still with HTTP 200. See Jobs and results.
Start and poll
For long runs, dropwait and poll.
1
Start the job
2
Poll for results every 2 seconds
{ "status": "running", "row_count": 0 }. That is normal, not an error. Stop polling on any end state: completed, failed, cancelled or rejected_balance.A helper you can copy
It runs withwait=true and only falls back to polling when the job is still going or the result was truncated.
Inputs
Send inputs underparams. 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, or422for bad params) booked nothing, so you can fix it and retry with the same key.
Request IDs
Every response carries anX-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.