Skip to main content
One agent run is many requests. A planning call, a few tool-use turns, a summariser — each is its own request, and on their own they tell you nothing about the run that made them. Send the same run id on each of them and Mesh API reports the run as one unit: every hop in order, and one spend figure for the whole thing. It is a request header, not a body field, so you set it once where you build your client and every request in the run carries it — no change at the call sites.

Set the header

A run id is yours to mint — a UUID, your own job id, a timestamped slug. Mesh API never generates one for you: a request with no header is simply not part of a run.

Confirm it was accepted

An accepted run id comes back on the response as X-Mesh-Run-Id. That echo is the signal to read — a dropped id is simply absent. Browsers can read it too: the header is exposed through CORS.
An unusable run id is ignored, never refused. A value that breaks any limit below — too long, a / in it, or something shaped like an API key — is dropped, and the request is served exactly as it would have been with no header at all. You get your completion; it is just not filed under a run.This is deliberate: a run id is an observability dimension, and a typo in one should not turn a working request into a failed one. It also means a silent typo is possible, so check the echoed header once when you wire a run id up, rather than assuming the trace will be there later.
Send the header once per request. Two X-Mesh-Run-Id headers on one request is never a refusal, but which value gets filed is not something we can promise: the first is read, and a proxy in between may fold repeated headers into a single comma-joined value before we ever see them. The echoed X-Mesh-Run-Id is always what was actually recorded.

Read the run back

GET /v1/usage/runs/{run_id} returns the run as one object: every hop, oldest first, and the totals.
Each hop is a usage event, the same object POST /v1/usage/events returns, so a hop’s request_id resolves to the full per-request record.
total_charged_usd is charges, not a token price. Attempts that were retried and requests that failed charged nothing and so add nothing to it, and on a run served on your own provider credential (BYOK) it is the platform fee rather than the model’s price.
A run id with none of your requests behind it returns 404 — including one another account happens to be using, since you are only ever shown your own requests.

Scope

So a run whose hops were made with several keys reads whole with an admin key, and key by key with each rsk_ key. Either needs the usage:read scope. The dashboard’s own views are org-scoped. Unlike GET /v1/usage/requests/{request_id}, a trace has no 90-day window of its own: it resolves for as long as its usage rows are kept. There is no backfill, though — a request served before you started sending the header carries no run id and no later call can add one.

Filter usage events by run

run_id is also a filter on the per-request history, which is the way to page through a long run or to combine it with any other filter:
Remember that this reader collapses retries unless you ask for them — "is_retry_attempt": [true, false] — where a trace shows every attempt by default. The Usage API has the full filter list and that warning in full. POST /v1/usage/rejections takes the same run_id, which is where the run’s refused requests are (see below).

Choosing a run id

Every other printable character is fine, % included. Why / is out. A trace is read back from GET /v1/usage/runs/{run_id}, where the id is one path segment, so an id with a slash in it could be accepted and then never looked up again. Percent-encoding does not rescue it, because the path is decoded before the id is matched: agent%2Frun-42 and agent/run-42 both miss the route. Rather than file an id we could not show you, we drop it. Why . and .. are reserved. Each is a path segment before it is an id: GET /v1/usage/runs/. finds nothing, and GET /v1/usage/runs/.. resolves to a different URL altogether. Only those two whole ids are reserved — any other id containing dots is fine, including v1.2.3, .hidden, a..b and .... Run ids are not unique across accounts, so you are free to use a sequence of your own without coordinating with anyone.

What a trace does not cover

  • served_rows is rows, not requests. One request that fans out internally writes more than one serving row — each /v1/chat/compare leg, an auto-routed classifier call, a memory or RAG lookup. Those rows carry the run id, and their charge is part of the run’s spend.
  • Requests refused before reaching a model — over a rate limit, a spend cap, an unknown model — charge nothing and write no usage row, so they are not in the trace. They are in POST /v1/usage/rejections, which takes the same run_id over its own ~90-day window. An older trace reads fine and reports no refused hops because none can be resolved, not because there were none.
  • Work that settles after the request that asked for it carries no run id: /v1/batches, every video submit (/v1/video/generations, /v1/video/edits, /v1/video/t2v, /v1/video/i2v, /v1/video/v2v), a /v1/responses request with background: true, and the /v1/files RAG embedding rows. They are billed when the job completes, by which time the run that submitted them is over, so their usage row records no run id and their charge is not in the run’s total.
  • The WebSocket surfaces — /v1/realtime and the audio sockets — take no run id. It is read off an HTTP request’s headers, which a socket’s per-message frames do not have.
  • No request or response bodies. The trace is metadata. Each hop carries its own request_id, so GET /v1/usage/requests/{request_id} resolves bodies under your key’s own body-logging policy.
  • The CSV export (GET /v1/usage/events/export) has no run_id column or filter yet.
  • GET /v1/analytics/usage/summary cannot group or filter by run: the run id is a raw-tier dimension, like end_user_id, and the aggregated cube does not carry it.