/scrapers/*/*
POST/scrapers/*/*
Runs one API of a predefined scraper from the loaded scraper bundle: POST /scrapers/{scraper}/{api}, where {scraper} is the scraper name (an organisation slug such as zillow — never a hostname) and {api} is one of its APIs, both as listed by GET /scrapers.
The body is the API's input ({ url?, params? }). A scraper that runs and reports a typed scrape error (blocked, not-found, invalid-input, upstream-changed, upstream-error) still returns HTTP 200 with ok:false. HTTP 4xx/5xx is reserved for host-level failures (unknown scraper/api, bundle unavailable, overloaded, job timeout, worker crash, job drained by a bundle hot swap, invalid result). Every ok:true result has been validated against the API's declared output schema.
Request
Query Parameters
Possible values: [datacenter, residential]
Possible values: [0, 1, false, true]
Possible values: [0, 1, false, true]
Body
- Schema
- Example (auto)
Target URL when the API is URL-addressed (e.g. a listing page). Validated
by the scraper: an off-domain or off-pattern URL yields an
invalid-input scrape error.
params object
API-specific parameters (e.g. { "zpid": "12345" }). Values must be
strings, numbers or booleans. Validated by the scraper.
{
"url": "string",
"params": {}
}
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 429
- 500
- 503
Schema
- Fields
- Example (auto)
true when the scraper ran and produced data. false when it reported a
typed scrape error (HTTP 200) or when the host could not run it (HTTP
4xx/5xx).
API-specific JSON payload when ok is true; null otherwise. Always
conforms to the API's declared output schema (see GET /scrapers).
error objectrequired
Error detail when ok is false; null otherwise. Two disjoint code
namespaces: scraper-level (blocked, not-found, invalid-input,
upstream-changed, upstream-error) always arrive with HTTP 200;
host-level (bundle-unavailable, unknown-scraper, unknown-api,
input-not-cloneable, overloaded, job-timeout, worker-crashed,
job-drained, invalid-result) arrive with the matching HTTP status.
Machine-readable code — see the two namespaces above. Identical across
enterprise and cloud; only message wording differs.
Possible values: [blocked, bundle-unavailable, input-not-cloneable, invalid-input, invalid-result, job-drained, job-timeout, not-found, overloaded, unknown-api, unknown-scraper, upstream-changed, upstream-error, worker-crashed]
Human-readable explanation. Host-level messages carry a
(requestId: …) suffix.
Whether a retry (new proxy/session, or simply later) is plausibly useful.
Upstream HTTP status when a scraper failure came from a response; null otherwise.
details objectrequired
Structured detail from the scraper (e.g. the selector that missed); null otherwise.
Structured detail from the scraper (e.g. the selector that missed); null otherwise.
{
"ok": true,
"error": {
"code": "blocked",
"message": "string",
"retryable": true,
"status": 0,
"details": {}
}
}
The request contains errors or didn't properly encode content.
The request is missing, or contains bad, authorization credentials.
The request targets a destination that is not allowed.
Resource couldn't be found.
The request took has taken too long to process.
Too many requests are currently being processed.
An internal error occurred when handling the request.
Service is unavailable.