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

# listRunTokenUsage

> Gateway RPC for listing persisted per-attempt token usage for a run.

* Method: `listRunTokenUsage`
* Scope: `run:read`
* Transports: HTTP RPC, WebSocket RPC
* Request: `{ runId }`
* Response: `{ runId, events: RunTokenUsageEvent[] }`

Each event is one persisted `TokenUsageReported` attempt event, ordered by event sequence: `{ nodeId, iteration, attempt, model, agent, inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens, timestampMs }`. The engine emits one per agent attempt, including failed attempts when the provider error carries usage, so summing `events` gives the run's total spend and grouping by `nodeId` gives per-node spend.

`model` is the resolved provider model id and `agent` is the agent id or adapter name that ran the attempt. A run with no persisted usage yields an empty `events` array.

Errors are versioned as `v1` and include `InvalidRequest`, `Unauthorized`, `Forbidden`, `RunNotFound`, and `Internal`.