Get Run
Look up one agent run by the id sent on its X-Mesh-Run-Id request header.
An agent run spans many requests. Send the same run id on each of them and this reports them as one unit: every hop in order, oldest first, and one spend figure for the whole run.
total_charged_usd is what the run cost — the sum of what each request charged,
which is what the balance was debited. Attempts that were retried and requests
that failed charged nothing and so add nothing to it, and on a run served by your
own provider credential it is the platform fee rather than the model’s price.
events includes the retried attempts, not only the request that served, so a
model that was tried and failed is visible rather than inferred. attempts
counts every row and served_rows the ones that served, so a long run reports
truncated: true once the trace reaches its cap and the totals still cover all
of it. served_rows is rows, not requests: one request that fans out internally
— a /v1/compare leg, an auto-routed classifier call, a memory or RAG lookup —
writes more than one of them.
Only requests that reached a model are here. One that was refused first — over a
rate limit, a spend cap, an unknown model — charges nothing and writes no usage
row, so it appears in POST /v1/usage/rejections, which takes the same run_id
— over roughly the last 90 days, that endpoint’s own window and not this one’s. It
reads whole monthly collections, so the edge of it is a month boundary, not a day.
A trace is resolvable for as long as its usage rows are kept; unlike
GET /v1/usage/requests/{request_id} it has no shorter window of its own.
Scoping matches POST /v1/usage/events: an API-key caller sees only the run’s
requests made by that key; a JWT caller sees their own org, and a non-privileged
member only their own requests plus the teams they administer; an org admin key
reads its own org. A run id is yours to choose, so two accounts can pick the same
one — you are only ever shown your own requests, and a run id with none of them
is “not found” rather than a confirmation that it exists elsewhere.
Authorizations
Headers
Dated version of the API contract to pin this request to. Omit it and the request is served under 2026-08 — the oldest supported version, so an existing integration is never moved by a release. A malformed or unsupported value is rejected with 400 invalid_api_version rather than falling back silently. The version actually served is echoed as X-Mesh-Version on every response, including errors.
2026-08, 2026-09, 2026-11, 2026-11-12 Response
Successful Response
One agent run: its requests as an ordered trace, and its spend as one figure.