By Claude prompt caching: the break-even math
Cache writes cost 1.25x and reads 0.1x, so a Claude prefix pays back on its second use. Derive your own break-even, then prove it from the API.
What prompt caching costs before it saves
Prompt caching lets Claude reuse the front of your prompt instead of reading it again on every call, and the whole decision comes down to two multipliers on your model's base input price. As of August 2026, a cache write costs 1.25x base input for the 5 minute lifetime, or 2x for the 1 hour lifetime. A cache read costs 0.1x. Those multipliers hold across the model list, so the break-even below does not move when a per-token price does.
The trade is a surcharge now against a discount later. You pay extra once to store a prefix. Every later request that begins with exactly the same bytes then pays a tenth of the normal input price for that part. A prefix that is never reused inside its lifetime cost you 25 percent extra for nothing.
The break-even, in one line of algebra
Call B the base input cost of the prefix if you sent it uncached. Without caching, N requests cost N times B. With the 5 minute cache, the first request writes the prefix at 1.25B and the other N minus 1 requests read it at 0.1B. Set the two equal and you get 0.9N = 1.15, so N = 1.28. The second request is already cheaper than not caching at all.
Repeat that with the 2x write of the 1 hour cache and you get 0.9N = 1.9, so N = 2.11. The long cache needs two reads before it breaks even, which is why it is not the default choice.
The chart below prices this for a 20,000 token prefix on Claude Opus 5, whose base input rate is $5 per million tokens as of August 2026. Scale every figure by 0.6 for a $3 per million model. The shape of the curve does not change.
The data behind this chart
[
{
"requests": 1,
"uncached_usd": "0.10",
"cached_5m_usd": "0.125",
"cached_1h_usd": "0.20"
},
{
"requests": 2,
"uncached_usd": "0.20",
"cached_5m_usd": "0.135",
"cached_1h_usd": "0.21"
},
{
"requests": 3,
"uncached_usd": "0.30",
"cached_5m_usd": "0.145",
"cached_1h_usd": "0.22"
},
{
"requests": 5,
"uncached_usd": "0.50",
"cached_5m_usd": "0.165",
"cached_1h_usd": "0.24"
},
{
"requests": 10,
"uncached_usd": "1.00",
"cached_5m_usd": "0.215",
"cached_1h_usd": "0.29"
},
{
"requests": 20,
"uncached_usd": "2.00",
"cached_5m_usd": "0.315",
"cached_1h_usd": "0.39"
}
]One request on its own costs $0.10 uncached and $0.125 cached, so caching a one-shot prompt is a pure loss. By the second request the 5 minute cache is at $0.135 against $0.20. The 1 hour cache is still behind at that point, $0.21 against the same $0.20, and it only passes the uncached line on the third request: $0.22 against $0.30. By 20 requests the gap is $2.00 against $0.315.
A cache hit also refreshes the entry, which is why the published price table names that column cache hits and refreshes. A busy endpoint therefore keeps a 5 minute entry alive indefinitely at read prices, and the 1 hour lifetime only earns its 2x write when your traffic has real gaps in it.
What a poor hit rate costs
Real traffic misses. A request that misses the cache but still carries a breakpoint is charged as a write, so the honest way to model this is cost as a function of hit rate. The chart below does that for 1,000 requests, each carrying the same 20,000 token prefix.
The data behind this chart
[
{
"hit_rate_percent": 0,
"cost_5m_usd": "125.00",
"cost_1h_usd": "200.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 25,
"cost_5m_usd": "96.25",
"cost_1h_usd": "152.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 50,
"cost_5m_usd": "67.50",
"cost_1h_usd": "105.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 75,
"cost_5m_usd": "38.75",
"cost_1h_usd": "57.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 90,
"cost_5m_usd": "21.50",
"cost_1h_usd": "29.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 95,
"cost_5m_usd": "15.75",
"cost_1h_usd": "19.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 99,
"cost_5m_usd": "11.15",
"cost_1h_usd": "11.90",
"uncached_usd": "100.00"
}
]At a 0 percent hit rate you pay $125.00 instead of $100.00, and the 1 hour cache doubles the bill to $200.00. Solve 1.25 minus 1.15h = 1 and the 5 minute cache starts saving money at a hit rate of about 22 percent, which is why 25 percent already shows $96.25. The same working on the 2x write gives about 53 percent for the 1 hour cache, so a 50 percent hit rate still costs $105.00, above the uncached line. At 90 percent the two land at $21.50 and $29.00. At 99 percent the short cache reaches $11.15, close to the floor of one tenth the uncached price.
Hit rate is the number to instrument, because it is the only input you control after the prefix size is fixed.
Which prefixes are worth a breakpoint
A request may carry up to four cache breakpoints, so the question is which blocks deserve one. The candidates are blocks that are byte-identical across calls and large enough to matter. The chart below prices four common shapes over 1,000 requests at a 90 percent hit rate on the 5 minute cache.
The data behind this chart
[
{
"label": "System prompt",
"prefix_size_tokens": "2,000",
"uncached_usd": "10.00",
"cached_usd": "2.15",
"saved_usd": "7.85"
},
{
"label": "System plus tools",
"prefix_size_tokens": "8,000",
"uncached_usd": "40.00",
"cached_usd": "8.60",
"saved_usd": "31.40"
},
{
"label": "Policy document",
"prefix_size_tokens": "25,000",
"uncached_usd": "125.00",
"cached_usd": "26.88",
"saved_usd": "98.12"
},
{
"label": "Codebase context",
"prefix_size_tokens": "120,000",
"uncached_usd": "600.00",
"cached_usd": "129.00",
"saved_usd": "471.00"
}
]A bare 2,000 token system prompt saves $7.85 per 1,000 requests against $10.00 uncached. Real money at volume, but it is not what makes caching interesting. Add the tool definitions and you are at 8,000 tokens and $31.40 saved. A 25,000 token policy document that every request asks questions about saves $98.12. The last row is the one that changes architecture: 120,000 tokens of codebase or transcript context costs $600.00 uncached and $129.00 cached, a saving of $471.00.
Savings scale with prefix size and with hit rate, and with nothing else. That changes what is worth putting in a prompt at all: what a million Claude tokens actually costs drops to a tenth of the sticker price for anything you send more than once.
What it looks like on a monthly bill
The chart below takes the 8,000 token prefix from above, a system prompt plus tool definitions, at a 90 percent hit rate, and scales it to monthly request volumes.
The data behind this chart
[
{
"label": "10k requests",
"uncached_usd": "400.00",
"cached_usd": "86.00",
"saved_usd": "314.00"
},
{
"label": "100k requests",
"uncached_usd": "4,000.00",
"cached_usd": "860.00",
"saved_usd": "3,140.00"
},
{
"label": "1M requests",
"uncached_usd": "40,000.00",
"cached_usd": "8,600.00",
"saved_usd": "31,400.00"
}
]At 10,000 requests a month the saving is $314.00, the difference between $400.00 and $86.00. At 100,000 requests it is $3,140.00. At a million requests the uncached input bill is $40,000.00 and caching removes $31,400.00 of it. These are input tokens only. Output is priced separately and caching does nothing for it, which is worth remembering before you promise anyone a 90 percent bill cut. Caching sits alongside the wider habits in keeping an AI agent's bill under control on a VPS.
How to prove the cache is working
Do not trust the design. Read the usage block on the response. Every Messages API (application programming interface) reply reports the cached tokens it wrote, the cached tokens it read, and the fresh tokens it had to process.
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
model="claude-opus-5",
max_tokens=512,
system=[
{
"type": "text",
"text": POLICY_DOCUMENT,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": question}],
)
u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)Run it twice with the same document and a different question. The first call reports a non-zero cache_creation_input_tokens and a zero cache_read_input_tokens. The second call reverses that, because the prefix was found. input_tokens counts only the tokens after the last breakpoint, so on a healthy second call it is small, usually just the new user message.
The same check from the shell, against a request body you have saved to request.json:
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d @request.json | jq '.usage'A healthy second call prints something like this:
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}One line tells you the truth. If cache_read_input_tokens stays at 0 across calls, you are paying the 1.25x write every single time and getting nothing back for it.
For the 1 hour lifetime, the breakpoint carries a time to live (TTL):
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}There is also automatic caching: a single cache_control field at the top level of the request, after which the API manages breakpoints as the conversation grows. It consumes one of your four breakpoint slots. Start there. Move to explicit breakpoints when you need to decide exactly where the boundary sits.
The ordering rule that kills hit rates
The cache matches a prefix byte for byte from the start of the request, and the request is assembled in a fixed order: tools, then system, then messages. A change at any level invalidates that level and everything after it. Edit one tool description and the system prompt and the entire message history are invalidated with it, even though you did not touch them.
That gives one rule with no exceptions. Anything that changes between calls must come after everything that does not.
The usual offender is a timestamp. A line reading Current time: 2026-08-03T14:07:11Z at the top of a system prompt guarantees a 0 percent hit rate, because the prefix hash is different on every call and no earlier entry can ever match it. Move it into the user message, at the end. A session identifier or a per-request nonce breaks things the same way and has the same fix. Retrieved documents that differ per request belong after the cached block too, or they push every stable token behind a boundary that moves.
The second offender is putting the breakpoint on the block that changes. Cache writes happen at the breakpoint, so if that block is different every time, nothing stable is ever stored, and the lookback finds only entries that earlier requests wrote at their own moving breakpoints. Place cache_control on the last block whose content is identical across requests.
The third is a parameter change you did not think of as prompt content. A different model has a different cache. Changing tool choice invalidates from the system level onward. Adding or removing a tool invalidates everything.
The minimum prefix, and the silent no-op
A prefix shorter than the model's minimum is not cached, and nothing tells you. No error, no warning. The request succeeds and both counters read 0. As of August 2026 the published minimums are:
- 512 tokens on Claude Opus 5 and Claude Fable 5
- 1,024 tokens on Claude Sonnet 5 and Claude Opus 4.8
- 4,096 tokens on Claude Haiku 4.5
If both counters read 0 on a request you believe is cached, check the prefix length before anything else. This is also why the cheapest model is not automatically the cheapest for a caching workload. Haiku 4.5 needs a prefix eight times longer than Opus 5 before caching engages at all, so a 2,000 token system prompt caches on one and is silently ignored on the other.
Where Claude Code caches for you, and where it cannot
Claude Code caches its own prefix. The system prompt and the tool definitions sit at the front of every request and do not move, so they are written once and read back for the rest of the session. That is why the per-turn cost of a long session is far below what the context size suggests, and it shows up in the counters described in how Claude Code reports token usage.
Where it cannot help you is an edit near the start of the context. Conversation history is append-only, so ordinary new turns extend a prefix that is already cached. Editing a file that was read early in the session changes content in the middle of that prefix, and every token after the change has to be written again. A long idle gap does the same, because the entry expires and the next turn pays a full write. Neither is a bug. Both are the prefix rule doing exactly what it says.
If you are writing your own client instead, apply the layout from the first request rather than retrofitting it: build the call the way a first Claude API app on a VPS does, with the stable blocks first and the volatile ones last.
Failure modes, and what you will see
Every call is a write. cache_creation_input_tokens is non-zero on every request while cache_read_input_tokens stays 0. Something at or before the breakpoint changes between calls. Print the first 200 characters of your assembled prefix on two consecutive requests and compare them by eye.
Both counters are 0. The prefix is under the model minimum, or the cache_control field never reached the API. Count the prefix tokens first, then log the request body you actually sent.
Reads work, then stop. A run of hits, then a write, then hits again. The gap between requests was longer than the lifetime. Accept the write, or move to the 1 hour TTL once you have checked your hit rate clears 53 percent.
Hit rate falls after a deploy. A tool description was edited or a model was changed. Both invalidate the whole prefix. Expect one expensive round of writes after every deploy that touches the prompt.
The bill went up after you enabled caching. Your hit rate is below the break-even. Under about 22 percent on the 5 minute cache, sending the prefix uncached is cheaper, and under about 53 percent the same is true of the 1 hour cache.
FAQ
How many times must a prompt be reused before caching pays for itself?
Once, on the 5 minute cache. A write costs 1.25x base input and a read costs 0.1x, so N uncached requests cost N while N cached requests cost 1.25 plus 0.1 times N minus 1. The two cross at N = 1.28, so the second request is already ahead. The 1 hour cache writes at 2x and crosses at N = 2.11, so it needs two reads.
Why is cache_read_input_tokens always zero?
Check the prefix length first: below the model minimum, 512 tokens on Claude Opus 5 and 4,096 on Claude Haiku 4.5 as of August 2026, caching is skipped silently and both counters read 0. If the prefix is long enough, look for content that changes between calls sitting at or before the breakpoint, such as a timestamp or a session identifier in the system prompt. If the counters were working and stopped, the gap between requests was longer than the cache lifetime.
Does prompt caching change Claude's answers?
No. The cache stores the processed form of tokens you already sent, and the model sees the same prompt either way. It is a billing and latency feature, not a change in behaviour. This also means you can enable it on a working prompt without re-running your evaluations.
Should I pay for the 1 hour cache?
Only when your traffic has gaps longer than 5 minutes and your hit rate will still clear roughly 53 percent. The 2x write is twice the downside of the 1.25x write when you miss. A 5 minute entry refreshes on every hit, so steady traffic keeps it alive at read prices without ever paying for the longer lifetime.