POST /v1/runs takes a provider, a model (the tool’s id) and the provider’s own
input, exactly as the tool’s input schema names it (Inspect a model).
- cURL
- Async tools (image, video, audio) answer
202 Acceptedwith the queued run, aLocationheader and aRetry-Afterpoll hint. - Sync tools (web search, scrape) answer
200 OKwith the finished run.
Statuses
A run cannot be canceled after it is submitted.
The run object
Getting the result
Webhook (recommended)
Add
webhook.url to the run and get its terminal event, signed.Polling
GET /v1/runs/{id}?wait_seconds=30 waits up to 60 seconds for a final status.Retry-After header. Without one, start at 1 s (search and scrape), 2 s (images) or 5 s
(video and audio), back off by 1.5× up to 30 s, and stop at a final status. Polling has its own rate limit, so it
never uses your create quota.
How long a run stays readable
GET /v1/runs/{id} and GET /v1/runs (and the MCP get_run and list_runs tools) return runs of the last 7 days,
with their input, output and timeline. An older id answers 404 RUN_NOT_FOUND with archived: true; its cost still
counts in your usage and billing. Stored output files are kept 7 days too, so download what you need to keep.