Usage Object

The `usage` object is your unvarnished truth about what you actually paid for in an AI interaction. Forget the marketing fluff or the "tokens per word" estimates. This is the raw, granular JSON data returned by the API, typically nested within the response, that tells you precisely how many input tokens were processed and how many output tokens were generated. For sophisticated models like Anthropic's Claude, this object goes deeper, differentiating between various types of input: cache reads, short-term cache writes, long-term cache writes, and genuinely uncached input. It also quantifies the output tokens, which include not just the visible text but also the invisible reasoning tokens the model used to arrive at its answer. Think of it as the itemized receipt for every single turn your AI agent takes, providing the ground truth for your bill. It is the only reliable source for understanding where your money actually goes, not where you *think* it goes. When you see `input_tokens` and `output_tokens` in this object, understand that these numbers are the basis for the actual dollar amount you are charged, often multiplied by different rates depending on their type. For instance, a cache read token might cost 0.1x the base input rate, while an output token could be 5x the base input rate. The `usage` object is the definitive record of these quantities, making it indispensable for any serious cost analysis or optimization effort. It is the cold, hard data that exposes the true economics of your AI agent workflow.

The `usage` object is not an estimate. It is not a fuzzy guess based on character counts or word length. It is the precise, API-reported token count that directly translates to your invoice. It is also not a simple measure of what you *see* on your screen. For example, Anthropic's extended thinking documentation confirms that you are billed for a substantial number of reasoning tokens that never make it into the visible output. So, while the `usage` object accurately reports `output_tokens`, a significant portion of those tokens might be invisible to you, representing the model's internal processing rather than its final, user-facing response. It is not a proxy for model "intelligence" or "verbosity" in the way most people assume. A higher `output_tokens` count does not necessarily mean a "better" or "more verbose" visible answer; it often means more internal reasoning or a different tokenization strategy. Crucially, it is not a direct reflection of "how much the model wrote" in terms of visible characters. Our data showed 2.7 visible characters per billed output token on Claude Opus 5, against roughly 4.0 characters per token for plain English. This means about a third of what you paid for as output never reached your screen. The `usage` object simply reports the billable units, regardless of their ultimate display status. It does not tell you *why* the model consumed those tokens, only *that* it did. It is a ledger, not a narrative.

Let's look at the data from our instrumented workstation, tracking 157,670 deduplicated Claude Code API responses between 26 April and 26 July 2026. The `usage` object for each of those responses provided the granular detail that allowed us to build an accurate cost model. For instance, a typical `usage` object from Anthropic's API might look something like this, though the exact structure can vary:

{ "input_tokens": 12345, "output_tokens": 678, "token_counts_by_type": { "cache_read": 11000, "cache_write_5min": 1000, "cache_write_1hr": 0, "uncached_input": 345, "output": 678 } }

In our corpus, when we aggregated and priced these `usage` objects, we found that visible output accounted for only 12.1% of the Opus 4.8 spend. The `token_counts_by_type` within the `usage` object revealed that cache reads made up 48% of the bill, cache writes 39%, and genuinely uncached input was a rounding error at under 1%. This was not raw token counts; this was the *cost* derived from applying Anthropic's rates: cache reads at 0.1x the base input rate, 5-minute cache writes at 1.25x, 1-hour cache writes at 2x, and output at 5x. The `usage` object, by providing these distinct token counts, allowed us to see that the cheapest per-token line item, cache reads, became the biggest line on the invoice because of sheer volume. Without the granular data from the `usage` object, distinguishing between these cost drivers would be impossible. It's the difference between seeing a total on a credit card statement and seeing every single line item from a grocery receipt. The `usage` object is that receipt, detailing every token transaction.

You should absolutely use the `usage` object to instrument your own AI agent workflows. Log it on every single API response, not just a sample, and deduplicate by response ID before aggregation. This is the only way to get ground truth data for your specific workload. Use it to split your input tokens into their four distinct buckets: cache read, 5-minute write, 1-hour write, and uncached. Then, multiply each bucket by its specific rate, as provided by the API vendor, rather than just tallying raw token counts. This will reveal the true cost drivers, like how cache reads, despite being cheap per token, can dominate your bill due to volume. Compare visible characters against billed output tokens to understand how much invisible reasoning you are funding. Use the `usage` object to compare model economics. For instance, our analysis showed Claude Opus 5 and Opus 4.8 share an identical price card, but the `usage` object data revealed Opus 5 writes 50% more output tokens. However, because output is only 12.1% of the bill, the overall cost difference was only about 5%. This level of insight is only possible with `usage` object data. You should also use it to identify cost-saving opportunities, such as detecting when idle time past the cache TTL (five minutes for Anthropic) leads to expensive cache rewrites instead of cheap reads.

Do not use the `usage` object to make assumptions about cost without applying the correct rate multipliers. Raw token counts are misleading because a cache read token is 50 times cheaper than an output token. Do not use it as a justification to ask for "shorter answers" from the model; our data showed this targets only 12% of the bill while degrading the quality of the output. Do not rely on generalized ratios or industry benchmarks without verifying them against your own `usage` data. Every workload is unique, and what's true for one workstation or one type of task might not be true for yours. For example, Anthropic's internal estimates of $13 per developer per active day and $150 to $250 per month are useful, but your `usage` objects will tell you your actual numbers. Do not ignore the `usage` object and simply trust the total bill; that's how you end up paying for things you don't understand or optimize. Two afternoons of instrumenting your own `usage` objects will tell you more than every pricing blog on the internet, including this one.

The `usage` object is the ground truth for AI billing, detailing every token transaction to reveal your actual costs.