Set the header
- curl
- Python (OpenAI SDK)
- Node.js (OpenAI SDK)
Confirm it was accepted
An accepted run id comes back on the response asX-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.
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.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:
"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_rowsis rows, not requests. One request that fans out internally writes more than one serving row — each/v1/chat/compareleg, 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 samerun_idover 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/responsesrequest withbackground: true, and the/v1/filesRAG 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/realtimeand 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, soGET /v1/usage/requests/{request_id}resolves bodies under your key’s own body-logging policy. - The CSV export (
GET /v1/usage/events/export) has norun_idcolumn or filter yet. GET /v1/analytics/usage/summarycannot group or filter by run: the run id is a raw-tier dimension, likeend_user_id, and the aggregated cube does not carry it.