For AI agents: a documentation index is available at /llms.txt
Skip to main content

/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

    timeout number
    token string
    allowedDomains string[]
    credentials object
    externalProxyServer string
    integrationId string
    proxy ProxyType

    Possible values: [datacenter, residential]

    proxyCity string
    proxyCountry string
    proxyLocaleMatch string

    Possible values: [0, 1, false, true]

    proxyPreset string
    proxyState string
    proxySticky string

    Possible values: [0, 1, false, true]

Body

    urlstring

    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.

Responses​

Schema
    okbooleanrequired

    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).

    datarequired

    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.

    codestringrequired

    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]

    messagestringrequired

    Human-readable explanation. Host-level messages carry a (requestId: …) suffix.

    retryablebooleanrequired

    Whether a retry (new proxy/session, or simply later) is plausibly useful.

    statusnumberrequired

    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.

    property name*any

    Structured detail from the scraper (e.g. the selector that missed); null otherwise.

Was this page helpful?