Skip to main content
POST
Best for a few facts from one page, like a price, a date or a list of names.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

A value you choose for one call. Send the same key with the same method, path and body within 24 hours and the first answer comes back with idempotent-replayed: true, with the same cost headers and no second charge. A call that sends zeroDataRetention and answers with page data is not kept, so a retry runs again. Needs an API key.

Query Parameters

maxTextLength
integer

Cut every text value in the response to this many characters. A value that was cut ends with …, and a page whose text was cut has isTruncated set to true. A screenshot is never cut. Leave it out to get the full text.

Required range: x >= 1

Body

application/json
urls
string[]

The pages to read, up to 25, such as ["https://bun.com/blog/bun-v1.3"]. An address ending in /* reads pages under it, found through the site's sitemap. With more than one, the fields are filled from all of them together. A page that cannot be read is skipped and named in warning, and costs nothing. A page is read up to 50000 characters. With several pages each one gets a smaller share, and all together are read up to 150000 characters. A page that is cut is counted in warning. The call fails only when no page can be read. Leave it out and send a prompt to search the web instead.

Maximum array length: 25
Maximum string length: 2048
schema
object

The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.

prompt
string

What to pull from the pages in plain words, such as the version and the release date, up to 10000 characters. With no urls, the web is searched for the first 400 characters of it.

Required string length: 1 - 10000
systemPrompt
string

Standing instructions for how to fill the fields, such as units or how to write dates, up to 10000 characters. They add to the rules of the extract: a value is still copied from the page and is null when the page does not state it.

Required string length: 1 - 10000

Send true to also search the web for your prompt and read the best pages it finds, up to 3 more. Needs a prompt. The search costs $1 per 1,000 searches. With no urls, the search runs without this.

Send true to also read pages on other sites that the pages link to, up to 5, picking the links whose address mentions your prompt. Each page read costs $1 per 1,000 pages.

agent
object

Accepted so a client that sends an agent model works. The value is not used. An extract reads the pages it is given and checks every value; it does not browse or click, and the answer says so in warning. To navigate a site, use the agent endpoint.

webhook

Where to be told when the extract ends: a plain address, or { url } which gets one JSON POST with the id, the status, the data and costUsd. headers are sent with the call, metadata comes back in it, and events picks completed, failed or both (both by default). The call is signed: read Stophy-Signature (t=,v1=), the HMAC-SHA256 of "." with your webhook secret from webhook.secret. A call that gets no 2xx is sent again, up to 3 times. Every call has an eventId that stays the same when the call is sent again, so you can skip one you already handled.

ignoreSitemap
boolean
default:false

For an address ending in /*: skip the site's sitemaps and find pages by links.

includeSubdomains
boolean
default:true

For an address ending in /*: also read pages on subdomains of the site. Send false to stay on the exact host.

limit
integer

For an address ending in /*: read at most this many pages under it. At most 25 pages are read in all.

Required range: 1 <= x <= 9007199254740991
timeout
integer
default:30000

How long to keep reading the pages, in milliseconds, from 1 second to 5 minutes; 30 seconds by default. A page not read by then is skipped and named in warning, and costs nothing.

Required range: 1000 <= x <= 300000
showSources
boolean
default:false

Send true to get sources: for each field, the pages that state its value.

scrapeOptions
object

How to read each page, the same options as scrape.

zeroDataRetention
boolean
default:false

Send true to keep nothing from this call: pages are read live, the result is held for one hour at most, and nothing is logged. Adds $2 per 1,000 pages.

ignoreInvalidURLs
boolean
default:true

Skip addresses that are not public website URLs. Send false to refuse the call instead.

Response

The data, and what this call cost in dollars.

success
boolean
required
invalidURLs
string[]
required
id
string