Skip to main content
Every run is a job with a 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 one stop_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: true if money left your wallet.
  • usd_charged: the exact amount. A run that stopped partway is charged only for what it delivered.
  • billing_status: settled, or settling if the charge hasn’t landed yet. While settling, charged and usd_charged are null, so fetch the job again shortly.
If your wallet runs out mid-run, you still get the rows collected so far, with a 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.