job_id. Read its state from GET /v1/jobs/{job_id}, its rows from GET /v1/jobs/{job_id}/results, or list recent runs with GET /v1/jobs.
Statuses
queued → running → completed | failed | cancelled | rejected_balance
All four end states are final, so stop polling on any of them.
A run that starts and then fails is not an HTTP error: it comes back with HTTP 200 and
status: "failed".
Why a run failed
fault says who needs to act: input means fix the request or add balance, mindcase means the problem was on our side, so follow retryable and contact support if it keeps failing.
Why a run stopped
Every finished job has onestop_reason and a plain-English stop_message. Branch on stop_reason and show stop_message.
A run that delivered rows is
retryable: false, because retrying buys those rows again. To get the rest of a partial run, run it again on purpose.
When a run finds nothing
A run that found nothing is a success:status: "completed", row_count: 0, stop_reason: "no_results" and a notice that says what to try next, such as broader search terms, a different location, or checking a link. A target that doesn’t exist (a deleted post, a private profile) and a store that doesn’t deliver to the location you asked for both come back this way, and aren’t charged.
A run over a list of inputs also says which inputs came back empty. The notice reads like “Found data for 1 of 5 links. Link 2 doesn’t exist; links 3 and 5 had no data.”, and notice.details.inputs lists each input as {param, value, status, rows}, where status is found, empty, not_found, invalid_input, not_serviceable, closed or failed.
What it cost
Every finished job states its cost:charged:trueif money left your wallet.usd_charged: the exact amount. A run that stopped partway is charged only for what it delivered.billing_status:settled, orsettlingif the charge hasn’t landed yet. While settling,chargedandusd_chargedarenull, so fetch the job again shortly.
notice explaining the balance was exhausted.
Large results
GET /v1/jobs/{job_id}/results returns every row as JSON. To download a file instead:
format is csv (default), json or xlsx.