Most of an agent’s token spend never appears in the answer you read. It sits in the individual model requests a run makes along the way: each planning turn, tool call, handoff, retry, and nested agent. A run total tells you that usage accumulated. Per-request records and the trace tree tell you where it accumulated and why. This article explains how to read both layers, which token categories to keep apart, and what to do when a usage field is missing.
What a run total can and cannot tell you
The OpenAI Agents SDK aggregates usage across every model call in a run, including the calls that produce tool calls or handoffs. Its documentation puts it this way: “Usage is aggregated across all model calls during the run, including model calls that produce tool calls or handoffs.” That makes the run total the right number for “how much did this task consume” and the wrong number for “which step caused it.”
As an Amazon Associate I earn from qualifying purchases.
Two runs can share a total and have very different shapes. One may be three large planning calls. Another may be forty small tool loops, each one resending the same conversation history. The total cannot distinguish them, so the total is where the investigation starts, not where it ends.
Token categories to keep separate
A single “tokens” column hides the costs you can actually act on. Wherever the provider reports them, keep these categories distinct for every request:
- Uncached input: fresh prompt content, including system instructions, tool definitions, conversation history, and tool results.
- Cached input: input served from a prompt cache. Track it separately so you can see how much of the prompt was reused rather than reprocessed.
- Cache creation (write) tokens: input written into a cache. Anthropic’s Usage API reports this as its own class alongside uncached input, cached input, and output.
- Output tokens: generated content, plus whatever structure the provider counts toward output (see the section on visible answers below).
- Reasoning token details: where the provider reports them. Under the OpenAI Agents guidance, reasoning tokens are billed as output.
Field names differ by endpoint. OpenAI Chat Completions reports prompt_tokens, completion_tokens, and total_tokens. The Responses endpoint reports input_tokens, output_tokens, and total_tokens. Do not map these as equivalent without checking the documentation for the endpoint and model you actually called.
Where the signal lives
Request-level usage records
For each model request, log the provider, model, endpoint, run, session, and request identifiers, timestamp, input and output counts, cache and reasoning details where provided, status, and any retry relationship to an earlier request. Where the provider omits a field, record it as absent. Writing a missing value as zero is the most common way accounting drifts.
In the OpenAI Agents SDK, the Usage object carries the request count, input, output, and total tokens, detail fields such as cached and reasoning tokens, and a request_usage_entries list. That list is the per-request view you need to attribute spend to a specific step.
Free tools Windows power users keep installed
One-click scans. No signup required.
Run and agent-level aggregation
Keep the run or task total, but store the child records that produced it. Aggregation rules are not uniform across frameworks, and the SDK’s own semantics are specific. A resumed nested run started through Agent.as_tool() is aggregated into the active outer run. A resumed top-level checkpoint carries an independent usage snapshot. If you compare nested-agent totals across tools, state which aggregation rule each one applies, because the numbers are not interchangeable.
Conversational sessions add a second subtlety. Each Runner.run() usage value covers only that run. Earlier session messages can be fed back in as input on later runs, so per-turn input can grow even when each turn adds little new content. That growth shows up in the input column, not in the new messages you see in the transcript.
Trace structure and causal context
The trace tree shows what happened and in what order: agent spans, model generations, tool calls, handoffs, and subagent spans. A generation span can show recorded input and output. A tool span can show the tool called, its arguments, and its result when available. Timelines expose ordering, overlap, duration, status, and failures, which is what lets you connect a token spike to a specific cause.
Per OpenAI’s tracing documentation, trace data can be exported as OTLP JSON. Organization-level trace export must be enabled, and the project API key needs appropriate permissions. Check both before building an export pipeline, since a missing permission typically produces an empty export rather than an error you will notice.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Organization-level reports
Anthropic’s Usage API reports organization usage in fixed time intervals, measuring uncached input, cached input, cache creation, and output tokens. You can filter or group by API key, workspace, model, service tier, context window, residency, and speed. It also includes server-tool usage such as web search. This view is built for reconciliation and spend governance across many workloads. It is not a substitute for tracing one agent run.
Why the visible answer misleads
OpenAI documents that reported output counts can include non-visible tokens used for formatting, tool-call structure, and message structure. A short answer can therefore carry more billed output than its length suggests, and a long-looking answer is not automatically the expensive part of a run. Tokenization and output behavior also differ between models. A lower per-token rate does not guarantee a cheaper completed task, because a cheaper model may take more calls or fail more often. Judge cost by what a run accomplished, not by the price per token or the size of the final response.
Null, blank, and late usage
OpenAI’s tracing guide states the rule plainly: “A blank value or null means the count is unknown. It does not mean the agent used zero tokens.” Traces are built after a turn ends, and usage may arrive later, remain unknown, or change. A null is therefore an unresolved state, not a final bill.
Treat it as one. Give each request a usage status of reported, missing, or pending. Do not close the accounting for a run while any of its requests is pending. If your dashboard sums nulls as zero, every run with a late field will be undercounted, and the error will persist unless you backfill it.
Estimates are not reported usage
Anthropic describes its token counting as an estimate that can differ slightly from actual input usage. Its preflight counter does not apply prompt caching logic, and some server tools are unsupported in that count. Use preflight counting to plan context size and set budgets before a request is sent. Use per-request reported usage to account for what was actually consumed. The two answer different questions and should never be merged into one column.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A diagnostic workflow
- Start with the outcome. For a representative task, save the run identifier, the success or failure result, and the latency. Use a set of comparable tasks rather than a single final response string.
- Expand the run into requests. List every model request in order, including retries, handoffs, and nested agent work, and attribute each one to its parent run. Where your system allows, attach a user or workload identifier.
- Separate the token categories for each request, using the categories described above. Record absent fields as absent.
- Look for repeated input. Check whether conversation history, tool definitions, retrieved or tool output, or retried requests re-enter later model calls. This tells you where to look. It does not show that a particular agent has a loop.
- Join usage to the trace. For each expensive request, open its span and check the tool that ran, what it returned, any error, and its duration. Confirm the cause in the trace before changing a prompt or tool.
- Reconcile the three layers. Treat preflight counts as planning, per-request usage as runtime telemetry, and organization reports as the reconciliation view. Check current provider pricing before converting any token count into dollars.
- Compute cost per successful task. Divide total tokens and estimated or reported cost by the number of completed tasks, and read that figure beside quality and latency. A change that cuts tokens while raising the failure rate is a regression, even though the token line goes down.
A worked trace example
OpenAI’s tracing guide includes an illustrative recorded session. It is a teaching example, not a benchmark, and the documentation does not state the year it was recorded. The numbers show the shape of a multi-agent run:
| Agent | Input tokens | Output tokens | Share of session input |
|---|---|---|---|
| Root agent | 126,390 | 1,567 | 50.6% |
| Subagent A | 34,075 | 465 | 13.6% |
| Subagent B | 89,304 | 667 | 35.7% |
| Session total | 249,769 | 2,699 | 100% |
The session total is 252,468 tokens, which equals the input and output of the three agents combined. In this example, input accounts for about 99% of all tokens. The diagnostic question is therefore what was re-sent to each model call, not how much the model generated. The example shows where to look. It does not describe what typical agents consume.
Tooling options compared
Several documented paths exist, and they cover different parts of the accounting. Compare them on the dimensions below rather than choosing one as universally best.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match| Option | Documented view | Compare on |
|---|---|---|
| OpenAI Agents SDK usage object | Run aggregation, per-request entries, session-run semantics, and usage detail fields | Request granularity, nested-agent aggregation rules, provider scope, data retention |
| OpenAI Agents tracing | Sessions, turns, traces, root and subagent usage, tool and generation spans, OTLP JSON export | Trace readiness, handling of null or late usage, export permissions, fit with your workflow |
| Anthropic Usage API | Organization usage by time interval and token class, with filters and groupings, plus server-tool usage | Reconciliation depth, supported dimensions, API access requirements, integration effort |
| LangSmith cost tracking | Automatic LLM cost from token counts and prices for documented integrations; manual costs for other run types | Provider and framework coverage, custom pricing, attribution of non-LLM costs, data handling |
Capabilities, supported fields, and pricing in these products change. Confirm each vendor’s current documentation before you build on it, particularly the export permissions and the list of supported usage dimensions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
