The response envelope

Every scraper call returns the same stable envelope: data plus bookkeeping, with costUsd (exact price) and walletDebitUsd (whole cents actually settled).

GET/api/v1/scrape/{platform}/{action}

The envelope, field by field

Every scraper call returns the same stable envelope. data is the platform's structured payload; everything else is bookkeeping. costUsd is the call's exact price (for a $0.003 scraper it reads 0.003, there is no minimum). walletDebitUsd is what actually left your wallet on this call: fractional costs accrue on a running tab and settle in whole cents, so it reads 0 on most calls and 0.01 as the tab crosses each cent. Summing either field over many calls converges on the same total.

Parameter	Type	Description
`platform`	string	Platform segment you called, e.g. "threads".
`scraper`	string	Internal scraper id the path resolved to.
`input`	object	Echo of the inputs the run used.
`data`	object	The scraped payload, exactly as structured by the platform.
`records`	integer	Result count heuristic (longest array in data). Informational only: billing is per call, never per record.
`costUsd`	number	The call's exact price in USD. 0 on an idempotent replay.
`walletDebitUsd`	number	Whole cents actually settled from the wallet on this call.
`idempotentReplay`	boolean	Present and true when X-Request-Id matched a previous run and its result was replayed free.
`requestId`	string	The run id. Quote it in support tickets.
`elapsedMs`	integer	Server-side duration of the call.

{
  "platform": "threads",
  "scraper": "threads-search-by-keyword",
  "input": { "query": "coffee" },
  "data": { "posts": [ … ] },
  "records": 19,
  "costUsd": 0.003,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 5211
}

Errors skip the envelope and return the engine's status with a JSON body: 400 invalid input, 402 balance or spend cap, 429 rate limited with Retry-After, 502 upstream failure (never billed).

← Previous

Run a scraper

Call history

Need a hand wiring this up? Email [email protected]. A real person reads every message.