usage object and token-counting documentation read against a peer-reviewed result on reasoning-model economics — not reviewed or endorsed by Anthropic or the paper’s authors. Claims were checked against Anthropic’s documentation and the cited paper as of July 2026.
There are two numbers an enterprise conflates the moment it starts budgeting for agents, and they should be pulled apart before the first invoice, because they diverge by more than anyone plans for.
The first number is the token count. Anthropic reports it precisely after the fact: every response carries a usage object — input_tokens, output_tokens, cache reads, and, when extended thinking is on, the thinking tokens the model spent reasoning before it answered, billed inside output and broken out under output_tokens_details.thinking_tokens [2][3]. That after-the-fact count is the good primitive: it is exact, it is per-request, and it does not round in the vendor’s favor. The count-tokens endpoint extends a weaker promise forward — it returns an estimate of the input size before you send, one that may differ from the billed number by a small amount and can include system-added tokens you are not charged for [1]. If you want to know how many tokens actually crossed the boundary, the response tells you the truth; if you want to know before you send, you get an estimate.
The second number is the cost you can plan around — the figure a finance team puts in a model, a budget owner commits to, a rate card is built on. Everyone assumes the first number delivers the second: count the tokens, multiply by the listed price, forecast the spend. And most summaries of token accounting encourage the assumption, because at the scale of a single request the arithmetic looks airtight.
Those are not the same number, and the gap between them is not noise you can average away. It is structural. That gap is this Dispatch.
The narrow guarantee
State the primitive at its actual altitude. Anthropic’s usage reporting makes one narrow, reliable promise: it tells you, exactly and after the fact, how many tokens of each kind a given request consumed [2]. The count-tokens endpoint extends a weaker promise forward by one step — it returns an estimated input-token count before you spend, explicitly an approximation that may differ from the billed figure [1]. That is the whole guarantee: an exact account after the fact, an estimate before. It is a measurement primitive — a faithful account of tokens consumed — not, and it does not claim to be, a prediction primitive. Nothing in the usage object promises that the next request on the same task will consume the same tokens, or that a model with a lower listed price will produce a lower total cost.
Read only that far and the primitive is doing its job perfectly. The confusion begins one step later, when the exact count is asked to stand in for a cost forecast it was never built to make.
The property the enterprise actually wants
An enterprise deploying agents at scale does not, in the end, need to know the token count of a request that already ran. It needs to know what a workload will cost before it commits to it — to budget it, to price a product on top of it, to tell a board what the margin will be. Call that property cost predictability: the ability to forecast spend from something knowable in advance. It is not measurement. It is the forecast the measurement is assumed to support.
Here is the move. Cost predictability is not something the usage primitive gives you, and it is not something you can recover by counting more carefully. The peer-reviewed economics say so directly. The Price Reversal Phenomenon evaluated eight frontier reasoning models across twelve tasks — nine single-turn, three long-horizon agentic — and found that in 32% of model-pair comparisons (106 of 336), the model with the lower listed price incurred the higher total cost, with the reversal reaching up to 28× [4]. The listed price, in other words, inverts the actual cost in nearly a third of comparisons. The root cause is the very token the usage object counts most honestly: thinking-token consumption varies enormously — on the same query, one model may spend 900% more thinking tokens than another [4]. The count is exact. The cost it implies is not.
And the unpredictability is not merely across models. It is within a single model, on a single query. The same paper found that repeated runs of the same query produced thinking-token variation up to 9.7× — an irreducible noise floor beneath any cost predictor [4]. The measurement primitive tells you, faithfully, what this run cost. It cannot tell you what the next identical run will cost, because the model itself does not spend the same reasoning twice.
Exact measurement, unpredictable cost. Both true at once, and the enterprise needs to hold both.
The stack cost predictability actually lives in
If the usage primitive measures but does not forecast, then cost predictability — to the limited degree it is achievable at all — lives in an assembly the architect has to build, not in a field the API returns. Naming the layers is how a budget survives contact with production.
Per-request cost monitoring, not per-request cost assumption. The paper’s own prescription is transparent per-request cost tracking — observe the realized cost of every call, because you cannot infer it from the price [4]. The usage object is the raw material for exactly this: it is the honest input to a monitoring system, not a substitute for one.
Distributional budgeting, not point estimates. With a 9.7× within-query noise floor, a single-number forecast is a fiction. The defensible artifact is a distribution — expected cost, tail cost, and a provisioned ceiling — because the thing being budgeted is itself a random variable.
Cost-aware selection on realized cost, not listed price. Choosing a model by its rate card is choosing on the signal the paper shows is inverted nearly a third of the time [4]. Selection has to run on measured total cost per outcome, which only the usage-level accounting can supply after the fact.
Attribution to the reasoning, not just the request. Because thinking tokens are the dominant source of variance, the accounting that matters surfaces them — thinking is billed inside output_tokens but reported distinctly under output_tokens_details.thinking_tokens, so the volatile component is visible rather than buried in the output total [3]. Anthropic’s usage object already exposes that breakdown; the assembly is using it, not collapsing it.
Assurance is evidentiary, not predictive
The defensible claim about cost was never going to be we know what this will cost. With an irreducible noise floor, no one can promise that honestly. The defensible claim is narrower and stronger: we measured what every request actually cost, we can show the realized distribution, and our budget is provisioned against the tail rather than the mean. That is an evidentiary posture, and it is the only one the mathematics permits. A team that reports “our agent costs X per request” is asserting a prediction the model’s own variance contradicts. A team that reports “here is the measured cost distribution across N runs, here is the tail, here is our ceiling” is producing evidence. The usage primitive is what makes the second posture possible — not because it forecasts, but because it measures faithfully enough to build the evidence on. Honest measurement is the precondition for honest budgeting, precisely because it refuses to pretend the cost is fixed.
What token accounting does not do
A Dispatch that stopped at the good news would be a vendor explainer. The usage primitive has hard limits, and an architect has to name them out loud.
It does not predict cost. This is the whole point, and it bears stating as a limit rather than an implication: an exact count of a completed request is not a forecast of the next one. The primitive is silent about the future by design, and the paper shows the future is 9.7× noisy on the same input [4].
It does not price the outcome, only the tokens. Two runs that both solve the task can differ by an order of magnitude in thinking tokens; the cheaper-token run is not the better-value run unless it also succeeded. Cost-per-token is not cost-per-outcome, and the usage object counts the former.
It does not make listed price a safe proxy. Nothing Anthropic reports invites this error — the reporting is honest — but the market habit of ranking models by rate card is exactly what the reversal phenomenon punishes [4]. The primitive gives you the truth; the misuse is upstream of it, in the budgeting.
And it is a measurement of what happened, not an account of why the model reasoned as long as it did. The thinking-token count tells you the reasoning was expensive. It does not tell you what the reasoning was, or whether it was necessary — that lives inside the model, and the count observes only its size.
Anthropic’s after-the-fact token accounting is exact, and its exactness is precisely what makes it dangerous to misuse: a number this precise invites the belief that it is also predictive, and it is not.
The billed token count is a faithful measurement; the cost is a random variable with an irreducible floor of variance, because the model does not spend the same reasoning twice — up to 9.7× different on the same query, and inverted against listed price in nearly a third of comparisons across models. An enterprise that budgets by multiplying an exact count by a listed price has built a forecast on a measurement that was never a forecast — and the pre-send estimate the count-tokens endpoint offers is, by its own documentation, only an estimate. The count you can trust and the cost you can predict are two different numbers, and only the first one is in the API.
The exactness of the measurement and the unpredictability of the cost are not in tension; they are the same fact seen from two sides, and an architecture that treats them as one number will be wrong in the direction that hurts — confident, precise, and off by an order of magnitude at the tail. The usage primitive did its job: it told the truth about the tokens. What it leaves standing is the question the enterprise now owns — whether a cost that is fundamentally a distribution can be governed by a budget that is fundamentally a line item, and what has to be built when the honest answer is that it cannot.
