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.
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.
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.
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.
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: itssnapshotId 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
SendthreadId 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.
id. It keeps the threadId and has threadTurn of 2.
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.
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 returns404 notFoundwithNo agent thread with that id. Threads are kept for 24 hours.An unknown snapshot returns404 notFoundwithNo snapshot with that id for this run. DELETEon a run that already ended returns409 jobFinished.zeroDataRetentioncannot be sent withthreadId: a thread keeps what it has said.strictConstrainToURLswith nourls, and no thread that has them, returns400 invalidRequest.- You can read only your own runs.
Related
- Agent starts a run and sets its cap.
- Webhooks pushes
started,page,action,completed,failedandcancelledevents. - Extract fills fields from pages you name, in one call.
- Usage and logs shows what each call cost.