Skip to main content
Agent finds the pages for you. If you already know the pages, use Extract. It answers at once with an id, and you read the answer with GET /v1/agent/{id}. It needs an API key. See the Quickstart.
The start call is free and returns id, url, threadId and threadTurn (1 for a first question). Poll GET /v1/agent/{id} every few seconds while status is processing:
transactionModes is missing: the agent did not find it in one round, so the field is left out.

Run fields

Request fields

Cap what a run spends

Every step is checked against what is left before it runs, so a run never goes over maxCredits, and what it spent before it stopped is charged. A run that cannot answer inside the cap ends with status: "failed", stopReason: "credit_limit_reached" and what it found in partial. If the cap cannot cover the first step, steps is empty and the run is free. For price, see Pricing.

Follow up in a thread

Send threadId with a new prompt to POST /v1/agent. The run sees your earlier question and answer. urls, schema, effort, mode, location and safe carry over unless you send new ones. A follow-up is a new run with its own id, the same threadId and the next threadTurn. With "mode": "chat", a follow-up the earlier answer cannot support reads the pages again. GET /v1/agent/threads/{threadId} returns every turn, oldest first, with inputs, times and costUsd. Add includeData=true for each finished run’s data. A thread status is running or idle. A run’s status there is processing, succeeded, failed, cancelled or credit_limit_reached.

Manage runs

Every read takes maxTextLength, a query parameter that cuts each text value in the response to that many characters.

Limits and errors

Codes are on Errors.
  • Runs, threads, traces and snapshots are kept for 24 hours. After that, 404 notFound. You can read only your own.
  • 400 invalidRequest: strictConstrainToURLs with no urls and no thread that has them, or zeroDataRetention with threadId.