> ## Documentation Index
> Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Tracing

> Group many requests into one agent run with X-Mesh-Run-Id, then read the whole run back — every hop in order, and one spend figure.

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

> [tab] curl
>
> ```bash theme={null}
> curl https://api.meshapi.ai/v1/chat/completions \
>   -H "Authorization: Bearer rsk_<key>" \
>   -H "X-Mesh-Run-Id: run-2026-11-13-42" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "openai/gpt-4o-mini",
>     "messages": [{ "role": "user", "content": "Plan the next step." }]
>   }'
> ```

> [tab] Python (OpenAI SDK)
>
> ```python theme={null}
> from openai import OpenAI
>
> run_id = "run-2026-11-13-42"
>
> client = OpenAI(
>     api_key="rsk_YOUR_KEY",
>     base_url="https://api.meshapi.ai/v1",
>     default_headers={"X-Mesh-Run-Id": run_id},
> )
>
> # Every request this client makes is a hop in the same run.
> plan = client.chat.completions.create(
>     model="openai/gpt-4o-mini",
>     messages=[{"role": "user", "content": "Plan the next step."}],
> )
> summary = client.chat.completions.create(
>     model="openai/gpt-4o-mini",
>     messages=[{"role": "user", "content": "Summarise what you did."}],
> )
> ```

> [tab] Node.js (OpenAI SDK)
>
> ```typescript theme={null}
> import OpenAI from "openai";
>
> const runId = "run-2026-11-13-42";
>
> const client = new OpenAI({
>   apiKey: "rsk_YOUR_KEY",
>   baseURL: "https://api.meshapi.ai/v1",
>   defaultHeaders: { "X-Mesh-Run-Id": runId },
> });
>
> // Every request this client makes is a hop in the same run.
> const plan = await client.chat.completions.create({
>   model: "openai/gpt-4o-mini",
>   messages: [{ role: "user", content: "Plan the next step." }],
> });
> const summary = await client.chat.completions.create({
>   model: "openai/gpt-4o-mini",
>   messages: [{ role: "user", content: "Summarise what you did." }],
> });
> ```

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.

```bash theme={null}
curl -sS -D - -o /dev/null https://api.meshapi.ai/v1/chat/completions \
  -H "Authorization: Bearer rsk_<key>" \
  -H "X-Mesh-Run-Id: run-2026-11-13-42" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Go."}]}' \
  | grep -i x-mesh-run-id
```

> [!WARNING]
>
> **An unusable run id is ignored, never refused.** A value that breaks any
> [limit below](#choosing-a-run-id) — 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.

> [!NOTE]
>
> **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.

```bash theme={null}
curl https://api.meshapi.ai/v1/usage/runs/run-2026-11-13-42 \
  -H "Authorization: Bearer rsk_<key>"
```

```json theme={null}
{
  "run_id": "run-2026-11-13-42",
  "events": [
    {
      "id": "0190a1c0-0000-7000-8000-00000000e1e1",
      "request_id": "req_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "model": "openai/gpt-4o-mini",
      "provider": "openai",
      "prompt_tokens": 128,
      "completion_tokens": 64,
      "total_tokens": 192,
      "cost_usd": "0.0000480",
      "latency_ms": 812,
      "status": "success",
      "error_code": null,
      "is_retry_attempt": false,
      "run_id": "run-2026-11-13-42",
      "created_at": "2026-11-13T10:15:30+00:00"
    },
    {
      "id": "0190a1c0-0000-7000-8000-00000000e1e2",
      "request_id": "req_01ARZ3NDEKTSV4RRFFQ69G5FB2",
      "model": "openai/gpt-4o-mini",
      "provider": "openai",
      "prompt_tokens": 964,
      "completion_tokens": 212,
      "total_tokens": 1176,
      "cost_usd": "0.0002718",
      "latency_ms": 1403,
      "status": "success",
      "error_code": null,
      "is_retry_attempt": false,
      "run_id": "run-2026-11-13-42",
      "created_at": "2026-11-13T10:15:36+00:00"
    }
  ],
  "attempts": 2,
  "served_rows": 2,
  "truncated": false,
  "total_charged_usd": "0.0003198",
  "total_tokens": 1368,
  "first_at": "2026-11-13T10:15:30+00:00",
  "last_at": "2026-11-13T10:15:36+00:00"
}
```

| Field | What it is |
| - | - |
| `run_id` | The id you sent, echoed back |
| `events` | The run's hops, oldest first. Retried attempts are included, each flagged `is_retry_attempt`, so a model that was tried and failed is visible rather than inferred |
| `attempts` | Every usage row the run wrote |
| `served_rows` | The rows that served, retries excluded — rows, not requests ([see below](#what-a-trace-does-not-cover)) |
| `truncated` | `true` once `events` hits its 500-hop cap. The totals still cover the whole run |
| `total_charged_usd` | What the run cost: the sum of what each request was charged, which is what your balance was debited. A decimal string, never a float |
| `total_tokens` | Tokens over every row, retries included — a volume figure, not a billing one |
| `first_at`, `last_at` | The run's span |

Each hop is a usage event, the same object
[`POST /v1/usage/events`](https://developers.meshapi.ai/docs/reference/usage-api#per-request-history-post-v1-usage-events)
returns, so a hop's `request_id` resolves to the full per-request record.

> [!NOTE]
>
> `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](https://developers.meshapi.ai/docs/capabilities/byok.md)) 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

| Credential | What it reads |
| - | - |
| `rsk_` API key | Only the run's requests made by **that key** |
| `mak_` [admin key](https://developers.meshapi.ai/docs/getting-started/admin-keys.md) | Every hop in the run made by your org, whichever key made it |

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}`](https://developers.meshapi.ai/docs/reference/usage-api#one-request-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:

```bash theme={null}
curl https://api.meshapi.ai/v1/usage/events \
  -H "Authorization: Bearer rsk_<key>" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "<ORG_ID>", "run_id": "run-2026-11-13-42", "limit": 100}'
```

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](https://developers.meshapi.ai/docs/reference/usage-api.md) 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

| Rule | Limit |
| - | - |
| Length | 128 characters |
| Characters | Printable ASCII, except `/` |
| Reserved | `.` and `..` cannot be used as a whole run id |
| Shape | A value shaped like an API key is dropped |
| Headers per request | 1 — send it once |

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`](https://developers.meshapi.ai/docs/capabilities/model-compare)
  leg, an [auto-routed](https://developers.meshapi.ai/docs/capabilities/auto-routing.md) classifier call, a
  [memory](https://developers.meshapi.ai/docs/capabilities/memory.md) or [RAG](https://developers.meshapi.ai/docs/capabilities/rag.md) 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](https://developers.meshapi.ai/docs/reference/usage-api.md#how-far-back-data-goes).
  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`](https://developers.meshapi.ai/docs/capabilities/batch-api), every
  [video submit](https://developers.meshapi.ai/docs/capabilities/video-generation.md) (`/v1/video/generations`,
  `/v1/video/edits`, `/v1/video/t2v`, `/v1/video/i2v`, `/v1/video/v2v`), a
  [`/v1/responses`](https://developers.meshapi.ai/docs/capabilities/responses-api) request with
  `background: true`, and the [`/v1/files`](https://developers.meshapi.ai/docs/capabilities/rag) 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`](https://developers.meshapi.ai/docs/capabilities/realtime-audio)
  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}`](https://developers.meshapi.ai/docs/reference/usage-api#one-request-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`](https://developers.meshapi.ai/docs/reference/analytics-api)** 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.