Skip to main content
Every agent run has an id. Use it to read the answer, follow the steps, stop the run, or ask a follow-up. All of these calls are free, and a run is kept for 24 hours.

Read a run

Get an API key in the Quickstart. GET /v1/agent/{id} returns the state of a run.
The response is in Agent. These are its fields.

List runs

GET /v1/agent lists your runs from the last 24 hours, newest first, 20 to a page. Each row has the id, createdAt, status, targetHint and the options the run started with.
This real response is cut to the first run of three.
When more runs follow, next holds the address of the next page. Or send before, a time in unix milliseconds, and read runs made before it. limit is 1 to 20.

Stop a run

DELETE /v1/agent/{id} stops a run that is still working and keeps what it has read. What it spent is charged. The answer has status of cancelled.
A run that already ended cannot be stopped. This real answer came from a run that had finished, with HTTP status 409.

Read the trace

GET /v1/agent/{id}/trace returns every step of a run, in order, as events: when the run started, each step with what it cost, a snapshot of the answer after each round, the final answer, and when the run finished. A page the run could not read is an error.occurred event.
This real response is cut to four of its eight events.
A tool step has a tool_call.started event and a tool_call.finished event, and result.costUsd is what the step cost. stepType is step, snapshot or answer. The outcome of run.finished is succeeded, failed, cancelled or credit_limit_reached.

Read a snapshot

A run takes up to three rounds, and the trace has a snapshot after each: its snapshotId is round-1, round-2 and so on. GET /v1/agent/{id}/snapshots/{snapshotId} returns the answer the run had at that point. Use it to see how the answer grew, or to keep an earlier round.
snapshot is the answer as a JSON string, and snapshotData is the same answer as an object.

Ask a follow-up

Send threadId with a new prompt to ask in the same thread. The run sees your earlier question and answer, and urls, schema, effort, mode, location and safe carry over unless you send new ones. With "mode": "chat", a follow-up that needs no new data gets a short reply in message, for $3 per 1,000 pages, and a follow-up that needs more reads the pages again.
The follow-up is a new run with its own id. It keeps the threadId and has threadTurn of 2.
In this run the first step was chat, which tried to answer from the earlier answer at no cost. The earlier answer did not hold the modes, so the run read the page again and charged $0.004.

Read a thread

GET /v1/agent/threads/{threadId} returns every turn of a thread, oldest first. Add includeData=true to get the data of each finished run.
This real response is cut to the second turn.
The status of a thread is running while a turn works and idle otherwise. A run’s status is processing, succeeded, failed, cancelled or credit_limit_reached.

Options

Limits and errors

  • Runs, threads, traces and snapshots are kept for 24 hours. An unknown run returns 404 notFound. An unknown thread returns 404 notFound with No agent thread with that id. Threads are kept for 24 hours. An unknown snapshot returns 404 notFound with No snapshot with that id for this run.
  • DELETE on a run that already ended returns 409 jobFinished.
  • zeroDataRetention cannot be sent with threadId: a thread keeps what it has said.
  • strictConstrainToURLs with no urls, and no thread that has them, returns 400 invalidRequest.
  • You can read only your own runs.
  • Agent starts a run and sets its cap.
  • Webhooks pushes started, page, action, completed, failed and cancelled events.
  • Extract fills fields from pages you name, in one call.
  • Usage and logs shows what each call cost.