By Claude prompt caching: break-even math explained
Claude cache writes cost 1.25x, reads 0.1x, and the second use already saves money. See the formula and verify the result from the API.
Prompt caching dey cost wetin before e begin save money
Prompt caching let Claude reuse the beginning of your prompt instead of reading am again for every call. The whole decision depend on two multipliers for your model base input price. As of August 2026, cache write cost 1.25x base input for the 5 minute lifetime, or 2x for the 1 hour lifetime. Cache read cost 0.1x. These multipliers dey apply across the model list, so the break-even calculation below no change when per-token price change.
The trade-off na extra charge now against discount later. You pay extra one time to store a prefix. Every later request wey start with exactly the same bytes then pay one-tenth of the normal input price for that part. If you no reuse a prefix inside its lifetime, you pay 25 percent extra for nothing.
Break-even, for one line of algebra
Call B the base input cost of the prefix if you send am uncached. Without caching, N requests go cost N times B. With the 5 minute cache, the first request write the prefix for 1.25B, and the other N minus 1 requests read am for 0.1B. Make the two equal and you get 0.9N = 1.15, so N = 1.28. The second request don already cheaper than no caching at all.
Repeat the calculation with the 2x write for the 1 hour cache and you get 0.9N = 1.9, so N = 2.11. The long cache need two reads before e break even, na why e no be the default choice.
The chart below calculate the price for a 20,000 token prefix on Claude Opus 5, wey e base input rate na $5 per million tokens as of August 2026. Multiply every figure by 0.6 for a $3 per million model. The shape of the curve no 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 by itself cost $0.10 when e no get cache and $0.125 with cache, so caching one-shot prompt na pure loss. By the second request, the 5 minute cache don reach $0.135, compared with $0.20. The 1 hour cache still dey behind for that point, $0.21 compared with the same $0.20, and e only pass the uncached line for the third request: $0.22 compared with $0.30. By 20 requests, the gap na $2.00 compared with $0.315.
Cache hit also refresh the entry. Na why the published price table call that column cache hits and refreshes. So, busy endpoint fit keep 5 minute entry alive indefinitely at read prices. The 1 hour lifetime only collect its 2x write when your traffic get real gaps.
Wetin poor hit rate dey cost
Real traffic dey miss. Request wey miss cache but still carry breakpoint, dem go charge am as write. So, the correct way to model this one na make cost depend on hit rate. The chart below show am for 1,000 requests, and each request carry 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"
}
]For 0 percent hit rate, you go pay $125.00 instead of $100.00, and the 1 hour cache go double the bill reach $200.00. Solve 1.25 minus 1.15h = 1, and the 5 minute cache start to save money when hit rate reach about 22 percent. Na why 25 percent don already show $96.25. The same calculation for the 2x write give about 53 percent for the 1 hour cache. So, 50 percent hit rate still cost $105.00, wey pass the uncached line. For 90 percent, the two reach $21.50 and $29.00. For 99 percent, the short cache reach $11.15, close to the floor of one tenth of the uncached price.
Hit rate na the number wey you need instrument, because na the only input wey you fit control after prefix size don fixed.
Which prefixes dey worth breakpoint
A request fit carry up to four cache breakpoints, so the question na which blocks deserve one. The candidates na blocks wey remain byte-identical across calls and big enough to matter. The chart below price four common shapes over 1,000 requests with 90 percent hit rate for 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 for every 1,000 requests against $10.00 when cache no dey. Na real money at volume, but na not this one make caching interesting. Add the tool definitions and you don reach 8,000 tokens, with $31.40 saved. A 25,000 token policy document wey every request dey ask questions about saves $98.12. The last row na the one wey changes architecture: 120,000 tokens of codebase or transcript context costs $600.00 when cache no dey and $129.00 when cached, so e saves $471.00.
Savings dey increase with prefix size and hit rate, and with nothing else. This changes wetin make sense to put inside prompt at all: how much one million Claude tokens really cost drops to one-tenth of the sticker price for anything wey you send more than once.
Wetin e go look like for monthly bill
The chart below take the 8,000 token prefix from above, plus system prompt and tool definitions, with 90 percent hit rate, then scale am 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"
}
]For 10,000 requests every month, the saving na $314.00. Na the difference between $400.00 and $86.00. For 100,000 requests, e na $3,140.00. For one million requests, the uncached input bill na $40,000.00, and caching remove $31,400.00 from am. These na input tokens only. Output get separate pricing, and caching no affect am. Remember this before you promise anybody 90 percent cut for bill. Caching dey work together with the wider habits for keeping an AI agent bill under control for VPS.
How to prove cache dey work
No trust the design blindly. Read the usage block for the response. Every Messages API (application programming interface) reply dey report the cached tokens wey e write, the cached tokens wey e read, and the fresh tokens wey e 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 am twice with the same document but different question. The first call go report non-zero cache_creation_input_tokens and zero cache_read_input_tokens. The second call go reverse am, because e find the prefix. input_tokens dey count only the tokens after the last breakpoint, so for healthy second call e go small, usually na only the new user message.
You fit do the same check from shell, against request body wey you save for 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'Healthy second call go print something like this:
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}One line go show you the truth. If cache_read_input_tokens remain 0 across calls, you dey pay the 1.25x write cost every time and you no dey get anything back.
For the 1 hour lifetime, breakpoint get time to live (TTL):
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}Automatic caching dey also available: one cache_control field for the top level of the request, after that the API go manage breakpoints as the conversation dey grow. E go use one of your four breakpoint slots. Start with this one. Use explicit breakpoints when you need decide exactly where the boundary go dey.
The ordering rule wey dey kill hit rates
Cache dey match prefix byte for byte from the beginning of the request. Request dey assemble for fixed order: tools, then system, then messages. If anything change for one level, that level and everything after am become invalid. If you edit one tool description, system prompt and the whole message history become invalid too, even though you no touch dem.
This give one rule wey get no exception. Anything wey fit change between calls must come after everything wey no dey change.
Timestamp na the common offender. A line wey read Current time: 2026-08-03T14:07:11Z for top of system prompt go guarantee 0 percent hit rate, because prefix hash dey different for every call and no earlier entry fit ever match am. Move am into user message, for the end. Session identifier or per-request nonce dey cause the same problem and get the same fix. Retrieved documents wey different for every request must also come after the cached block. Otherwise, dem go push every stable token behind a boundary wey dey move.
The second offender na putting breakpoint on the block wey dey change. Cache writes happen for the breakpoint. So, if that block different every time, nothing stable ever gets stored. The lookback go only find entries wey earlier requests write for their own moving breakpoints. Put cache_control on the last block wey content dey identical across requests.
The third one na parameter change wey you no think say na prompt content. Different model get different cache. If you change tool choice, cache invalidation start from system level go forward. If you add or remove a tool, everything becomes invalid.
The minimum prefix, and the silent no-op
Prefix wey short pass the model minimum no go enter cache, and nothing go tell you. No error, no warning. Request go succeed, and both counters go read 0. As of August 2026, the published minimums be:
- 512 tokens for Claude Opus 5 and Claude Fable 5
- 1,024 tokens for Claude Sonnet 5 and Claude Opus 4.8
- 4,096 tokens for Claude Haiku 4.5
If both counters read 0 for request wey you believe say e dey cached, check the prefix length before anything else. Na this same reason why the cheapest model no automatically be the cheapest one for caching workload. Haiku 4.5 need prefix wey long eight times pass Opus 5 before caching fit start at all. So, 2,000-token system prompt go cache for one, but the other one go silently ignore am.
Where Claude Code dey cache for you, and where e no fit help
Claude Code dey cache e own prefix. The system prompt and the tool definitions dey for front of every request and dem no dey move, so dem write once and read again for the rest of the session. Na why the cost for each turn of long session dey far below wetin the context size suggest, and e dey show for the counters wey how Claude Code dey report token usage describe.
Where e no fit help na when you edit something near the beginning of the context. Conversation history na append-only, so ordinary new turns dey extend prefix wey don already cache. If you edit file wey Claude read early for the session, e change content for the middle of that prefix, and every token after the change must write again. Long idle gap dey do the same thing, because the entry expires and the next turn must pay for full write. None of these na bug. Both na the prefix rule dey work exactly as e talk.
If na your own client you dey write, apply the layout from the first request instead of trying to retrofit am later: build the call the way a first Claude API app on a VPS do am, with the stable blocks first and the volatile ones last.
Failure modes, and wetin you go see
Every call na write. cache_creation_input_tokens dey non-zero for every request while cache_read_input_tokens dey 0. Something for or before the breakpoint dey change between calls. Print the first 200 characters of the prefix wey you assemble for two consecutive requests, then compare dem by eye.
Both counters na 0. The prefix dey below the model minimum, or the cache_control field never reach the API. Count the prefix tokens first, then log the request body wey you actually send.
Reads dey work, then dem stop. You get hits for some time, then one write, then hits again. The gap between requests pass the lifetime. Accept the write, or move to the 1 hour TTL after you don check say your hit rate pass 53 percent.
Hit rate drop after deploy. You edit one tool description or change model. Both things invalidate the whole prefix. Expect one expensive round of writes after every deploy wey touch the prompt.
The bill increase after you enable caching. Your hit rate dey below the break-even point. If e dey below about 22 percent for the 5 minute cache, sending the prefix without cache dey cheaper. If e dey below about 53 percent, the same thing apply to the 1 hour cache.
FAQ
How many times you suppose reuse prompt before caching go pay for itself?
Once, for the 5 minute cache. Write dey cost 1.25x base input, while read dey cost 0.1x. So N uncached requests go cost N, while N cached requests go cost 1.25 plus 0.1 times N minus 1. The two costs cross for N = 1.28, so the second request don already save money. The 1 hour cache dey write at 2x and crosses for N = 2.11, so e need two reads.
Why cache_read_input_tokens dey always show zero?
First check the prefix length: if e dey below the model minimum, 512 tokens for Claude Opus 5 and 4,096 for Claude Haiku 4.5 as of August 2026, caching go skip am silently and both counters go read 0. If the prefix long enough, check whether content wey dey change between calls dey at or before the breakpoint, like timestamp or session identifier inside the system prompt. If the counters dey work before but stop now, the gap between requests pass the cache lifetime.
Prompt caching dey change Claude answers?
No. The cache dey store the processed form of tokens wey you don already send, and the model dey see the same prompt either way. Na billing and latency feature, e no dey change behaviour. This also mean say you fit enable am for prompt wey dey work without running your evaluations again.
I suppose pay for the 1 hour cache?
Only when your traffic get gaps wey pass 5 minutes and your hit rate go still pass roughly 53 percent. The 2x write get twice the downside of the 1.25x write when cache miss happen. A 5 minute entry dey refresh on every hit, so steady traffic go keep am alive at read prices without paying for the longer lifetime.