Where your Claude API bill comes from
An API bill is the sum of the token counts that every response reports, so reading those counters shows where the money went before you cut anything from a prompt.
- Each response reports fresh input, output, cache writes and cache reads, and a nested field splits the cache writes by cache lifetime.
- Put the parts of a request that stay the same first and anything that changes after the cache breakpoint, because the cache only matches an identical prefix.
- A cached system prompt is billed at a tenth of the base input price, so trimming it saves little next to a request that has to write the cache again.
When I hit the weekly cap on Claude Max (Anthropic's $200-a-month subscription plan) two weeks in a row, the subscription cut me off, which is the story behind the lead post on usage limits, where I also explain how caching works in general. The pay-as-you-go API meters the same kind of work in dollars, so instead of stopping you it keeps billing. Extra-usage credits (pay-as-you-go credits a subscriber can turn on to keep working past the cap) are metered in dollars too, and the one time I turned them on they came to about $100 in twenty minutes.
This post is about reading that meter on the API, so that you can take any expensive request, look at the counters it returned, and tell whether the money went to fresh input, output or writing the cache. The prices and mechanics here were recorded from Anthropic's documentation on 2026-08-25, with the request syntax re-checked on 2026-11-12, and since prices change, check the current pages before you budget against them.
Every response reports four token counters
The API bills per token (a small chunk of text that the model reads or writes), and the cost of a request is the sum of each kind of token times its price. Every response includes a usage object with four counters:1
input_tokens: input that was neither read from nor written to the cacheoutput_tokens: everything the model generated, including extended thinking (the reasoning the model writes before its answer), which is billed as output and counts toward output rate limits2cache_creation_input_tokens: input written to the cache by this requestcache_read_input_tokens: input read from the cache by this request
The usage object also has a nested cache_creation object that splits cache writes into ephemeral_5m_input_tokens and ephemeral_1h_input_tokens, one for each of the two cache lifetimes described below, and since the two are priced differently, code that rebuilds costs should read those sub-fields.1 Record the counters on every request the way you would keep an audit log, so that when the bill jumps you can rebuild each line and see which kind of token grew:
u = response.usage
log({ "input": u.input_tokens, "output": u.output_tokens,
"cache_write": u.cache_creation_input_tokens,
"cache_read": u.cache_read_input_tokens })
Two other details matter when you plan capacity. Cache reads don't count toward the input-tokens-per-minute rate limit (ITPM, the cap on how much input you can send per minute) on current models, so caching raises how much you can send as well as lowering what you pay.1 Work that isn't time-sensitive, such as a nightly summary job, can go through the Batch API (a queue for requests that don't need an immediate answer), which is 50% off.2
How caching changes the price of input
Prompt caching lets the API keep the processed opening of a request, so that later requests starting with the same content can reuse it instead of paying for it in full again. On the API, you choose what gets cached. You put a cache_control marker, written { "type": "ephemeral" }, on a content block, which acts as a breakpoint (the point where the cached part ends), and the prefix up to and including that block becomes cacheable. The prefix is the opening of the request, assembled in the order tools, system prompt, messages.3 The first request writes the prefix to the cache at a premium, and later requests that start with the identical prefix read it at a small fraction of the base price, as the figure shows.3
A cached system prompt is billed at the read price on every request after the first, so trimming it saves little next to a request that has to write the whole prefix again.
- Request 1 · WRITEwrite price
- Requests 2…N · READread price each
- Gap or change · MISScache no longer matches
- Next request · REWRITEfull write price again
Any change before the breakpoint invalidates the cache from that point on, which is why the order of a request matters: put the parts that stay the same first, place the breakpoint after the last of them, and put anything that changes after it.3
Two ways an API request misses the cache
A cache miss means the request has to write the prefix to the cache again at the write price.3 Two causes come from how API requests are timed and built.
The gap between requests. The cache has a time to live (TTL, how long a cached prefix stays available), and on the API the default is five minutes. If more time than that passes between requests that share a prefix, the next one pays for a full write, so a background job that runs in bursts with quiet gaps pays for a new write after each gap. The timer runs from the start of the request, so a response that streams for four minutes leaves only about a minute of the window.3
Changing content above the breakpoint. A value that differs on every request, such as a request ID or a timestamp, gives each request a different prefix, so each one pays the write price and nothing is read back. A user's name splits the cache by user, and a date costs one rewrite each day it changes. Editing a live system prompt causes one round of misses, since every active conversation misses on its next request.
What to change in your requests
- Mark one breakpoint after the last stable block. Following the order in the figure above, the relevant parts of a request body look like this:
{
"tools": [
{ "name": "lookup_order", "description": "Look up an order by number (stable)", "input_schema": { "type": "object" } }
],
"system": [
{ "type": "text", "text": "You are a support assistant. (stable instructions)" },
{
"type": "text",
"text": "(product manual, stable)",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [
{ "role": "user", "content": "(earlier turns, then the new question)" }
]
}
- Match the cache tier to your traffic. If requests that share a prefix arrive further apart than the default lifetime, ask for the one-hour tier on that breakpoint.3 The one-hour write costs 2× instead of 1.25×, an extra 0.75× paid once, so it comes out ahead the first time it saves a five-minute rewrite.
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
- Trim what enters the history. Cap tool results before you append them to the conversation, and ask the model only for the fields you need.
- Defer a large tool catalog. One measurement put a five-server MCP setup (Model Context Protocol, a standard way to connect tool servers to a model) at about 55,000 tokens of tool definitions before any user input.4 On the API, every tool definition loads into the model's context on every request unless you mark it
defer_loading: trueand include Anthropic's tool search tool, which lets the model search the catalog and load only the tools it needs.5
Where to start when the bill jumps
Read the usage counters on the requests that cost the most before you cut anything from a prompt, because they show whether the money went to cache writes, fresh input or output, and each of those has a different fix. The patterns below follow from the prices above rather than from the documentation, so treat them as a rough guide:
- Cache reads far above cache writes: caching is working, and the remaining cost is context size or output.
- Large cache writes after quiet periods: the cache is expiring between requests.
- Cache writes close to the whole input on every request: something in the prefix changes each time.
- Both cache counters at zero: no breakpoint is set.
If the spend you are tracing comes from Claude Code rather than your own API calls, AgentWrangler, a local dashboard that reads Claude Code's session logs to show where the tokens went, is now public on GitHub and npm, with the details in the launch post.
Footnotes
-
Anthropic, Prompt caching and API rate limits documentation: the four
usagecounters, the nestedcache_creationsub-fieldsephemeral_5m_input_tokensandephemeral_1h_input_tokens, and cache-read tokens not counting toward input-tokens-per-minute limits on current models. platform.claude.com/docs/en/docs/build-with-claude/prompt-caching. First-party. ↩ ↩2 ↩3 -
Anthropic, models overview: "Batch API requests are 50% off"; extended thinking is billed as output tokens and counts toward output rate limits. platform.claude.com/docs/en/docs/about-claude/models/overview. First-party. ↩ ↩2
-
Anthropic, Prompt caching documentation: cache write 1.25× (5-minute) or 2× (1-hour) and cache read 0.1× of base input; a 5-minute default lifetime measured from the start of the request; exact-prefix matching, where any change invalidates the cache. The
cache_controlbreakpoint, the tools, system, messages prefix order and the"ttl": "1h"syntax were re-checked on 2026-11-12. platform.claude.com/docs/en/build-with-claude/prompt-caching. First-party. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 -
startdebugging.net (May 2026): a typical five-server MCP setup measured at roughly 55,000 tokens of tool definitions loaded before any user input. Community/practitioner. ↩
-
Anthropic, Tool search tool documentation, checked 2026-11-12: tools without
defer_loadingload into context immediately, deferred tools load only when the model finds them through search, and every definition is still sent in thetoolsarray on each request. platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool. First-party. ↩