Skip to main content
  • 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.