Reading a usage block correctly

Why the usage block is the actual source of truth

Every response from the API carries a usage block alongside the content, and it's the authoritative record of what that specific request actually billed for — not an estimate, not a prediction, the real number. Anyone reconciling a bill, debugging a caching setup, or trying to understand why a request cost more than expected should be reading this block directly rather than working from a pre-send estimate or a general sense of what "should" have happened.

The fields that aren't just input and output

Beyond the straightforward input and output token counts, the usage block separately reports cache-related activity: how many tokens were written to a new cache entry on this request, and how many were read from an existing one. These are genuinely separate line items from ordinary input tokens, priced differently, and a usage block where both cache fields read zero on a request you expected to hit a cache is the single clearest signal that your caching setup isn't working the way you think it is — with no error anywhere else to tell you.

Reading a cache write versus a cache read correctly

A cache write on a given request means that request established a new cache entry — it's the more expensive of the two cache-related costs, and seeing it doesn't mean something went wrong, it means this particular request was the first to touch that prefix within the cache's lifetime. A cache read means an existing entry was reused, and it's where caching's actual savings show up. A healthy caching setup, over a run of related requests, should show a small number of writes and a much larger number of reads — a pattern of frequent writes and rare reads suggests the cache isn't living long enough, or the prefix isn't stable enough, to actually be reused.

What thinking tokens look like in the usage block

Where thinking runs as part of a request, the tokens it consumed are reflected in the output count even though they never appear in the visible response text — the usage block doesn't hide this, but it also doesn't always separate it out from the visible answer's own token count in a way that's obvious at a glance. If a request's billed output is noticeably larger than the visible response text would suggest, thinking overhead is the first place to look, especially at higher effort levels where thinking runs longest.

Comparing usage blocks across requests, not just within one

A single usage block tells you about one request; the more useful signal usually comes from comparing usage blocks across a run of related requests to spot a pattern — a cache-hit ratio that's declining over a session, an output token count that's crept up as a prompt evolved, a request that's suddenly billing thinking tokens it wasn't before because an effort level changed somewhere upstream. None of these show up by staring at one usage block in isolation; they show up by tracking the field over time and noticing when it moves.

Building a habit around checking it

The usage block is easy to ignore when a request succeeds and the response looks right — nothing about a normal-looking answer prompts you to go check the numbers behind it. That's exactly the habit worth breaking for anything running at real volume: sample-check usage blocks against your expectations periodically rather than only looking when something's already gone wrong on the invoice. The usage tracker is built for exactly this — paste in usage blocks over time and it turns them into a running read on burn rate and cache-hit ratio, entirely in your browser.