Skip to main content
POST
Best for a question that needs several pages, like the pricing tiers of a few products or the CEO and headquarters city of a list of startups. Send prompt, and schema for the fields you want (any JSON Schema), and urls to start from. It answers at once with an id, threadId and threadTurn; ask agent.status for the result. The agent searches, reads pages and checks every value against the page text, in up to 3 rounds. It is charged step by step at the normal price of each search and page, plus $3 per 1,000 pages for each planning or answering step, and stops before maxCredits. A run that cannot finish inside maxCredits fails with stopReason credit_limit_reached and what it found in partial; what it spent is still charged. To ask a follow-up, send the threadId from agent.status.

Price

Each search and page at its normal price, plus $3 per 1,000 pages for each planning or answering step that returns something, up to the limit you set with `maxCredits` ($5 when you leave it out). Starting the run is free. See Pricing.

Authorizations

Authorization
string
header
required

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

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
prompt
string
required

What to find, in plain words, such as the pricing tiers of Pinecone, Qdrant and Weaviate, or the CEO and headquarters city of each of these startups.

Required string length: 1 - 10000
urls
string[]

Pages to start from, up to 20. An address with * in it, such as https://qdrant.tech/blog/*, is expanded from the site's own page list, up to 10 pages. Without urls the agent searches the web.

Required array length: 1 - 20 elements
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.

maxCredits
number
default:2500

The most this run may spend, counted in steps of $0.002. Default 2500, which is $5. Every step is checked against what is left before it runs, so the run never goes over. A run that cannot finish inside it fails with stopReason credit_limit_reached and what it found in partial. What it already spent is charged.

includeSources
boolean
default:true

Send false to leave sources out of the answer. They cost nothing.

model
string
default:stophy

Any model name is accepted. Every name runs the same agent, and the name you send is echoed back.

Required string length: 1 - 100
mode
enum<string>

extract (the default) fills your fields on every turn. chat lets a follow-up that asks for no new data get a short reply in message, for $3 per 1,000 pages, instead of a new run. Needs threadId. A follow-up that omits mode keeps the thread's mode.

Available options:
extract,
chat
effort
enum<string>

How many search-and-read rounds the agent may take: low 1, medium 2, high 3 (the default). A follow-up that omits effort keeps the thread's.

Available options:
low,
medium,
high
location
object

The country every search and page read goes out from, and results are localized to. A follow-up that omits location keeps the thread's.

strictConstrainToURLs
boolean

Send true to read only the pages in urls, with no searching. Needs urls, or a thread that has them.

threadId
string

Ask a follow-up in the same thread: send the threadId an earlier run returned. The run sees the earlier question and answer, and omitted urls, schema, effort, mode and location carry over.

Pattern: ^[A-Za-z0-9_-]{1,100}$
zeroDataRetention
boolean

Send true to keep nothing from this run: the prompt, steps and result are held for one hour at most and nothing is logged. Each page read adds $2 per 1,000 pages. Cannot be sent with threadId.

safe
boolean

Send true to hide explicit results from every web search in the run. Pages in urls and pages the agent opens are not filtered. A follow-up that omits safe keeps the thread's.

auditMetadata
object

Who made the request, kept with the run and read back by agent.status.

webhook

Where to be told about the job: a plain address, or { url } which gets a JSON POST when the job starts, for each finished page, and when the job ends. headers are sent with every call, metadata comes back in every call, and events picks which of started, page, action, completed, failed and cancelled to send (all by default). An agent run sends action for each step it takes, and page too. Every call is signed: read Stophy-Signature (t=,v1=), where v1 is the HMAC-SHA256 of "." with your webhook secret from webhook.secret. A call that gets no 2xx is sent again, up to 3 times. If your address answers slowly, a page event can carry only the page url. Read that page with the status call.

Response

The data, and what this call cost in dollars.

success
boolean
required
threadTurn
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991
creditsUsed
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991
costUsd
number
required
id
string
url
string
status
string
Allowed value: "scraping"
queuePosition
integer
Required range: -9007199254740991 <= x <= 9007199254740991
threadId
string
requestId
string