By Claude prompt caching: when e go save money
Claude cache write na 1.25x and read na 0.1x, so second use don break even. See the algebra and how API billing prove the exact result.
Prompt caching save money before e cost
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 below no go 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 go 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.
The break-even, for one line algebra
Call B the base input cost of the prefix if you send am uncached. If caching no dey, N requests go cost N times B. With the 5 minute cache, the first request go write the prefix for 1.25B, while the other N minus 1 requests go 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 pass no caching at all.
Repeat the same calculation with the 2x write cost of 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 cost for a 20,000 token prefix on Claude Opus 5, wey 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 curve shape no go 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 if e no dey cached and $0.125 if e dey cached, so caching prompt wey dem go use only once na pure loss. By the second request, the 5 minute cache don reach $0.135 against $0.20. The 1 hour cache still dey behind at that point, $0.21 against the same $0.20, and e only pass the uncached cost for the third request: $0.22 against $0.30. By 20 requests, the difference na $2.00 against $0.315.
Cache hit dey refresh the entry too. Na why the published price table call that column cache hits and refreshes. So busy endpoint fit keep 5 minute entry alive indefinitely for read prices, while the 1 hour lifetime only justify its 2x write cost when real gaps dey between your traffic.
Wetín poor hit rate dey cost
Real traffic fit miss. If request miss cache but e still get breakpoint, dem go charge am as write. So the correct way to model am na to calculate cost based on hit rate. The chart below do this 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 go start 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, dem land for $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.
Na hit rate be 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
One request fit carry up to four cache breakpoints, so the question be which blocks deserve one. 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 at 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 compared with $10.00 when e no dey cached. This fit be real money at high volume, but na not wetin make caching interesting. Add the tool definitions and e 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 fit change architecture: 120,000 tokens of codebase or transcript context cost $600.00 when e no dey cached and $129.00 when e dey cached, so e saves $471.00.
Savings dey increase with prefix size and hit rate, and nothing else. This one change wetin make sense to put inside prompt at all: how much one million Claude tokens really cost drop to one-tenth of the listed price for anything wey you send more than once.
Wetin e go look like for monthly bill
The chart below dey use the 8,000 token prefix wey we mention above, plus system prompt and tool definitions, with 90 percent hit rate, then e 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 ones na input tokens only. Output get separate pricing, and caching no affect am. Remember this before you promise anybody 90 percent bill reduction. Caching dey work together with the wider habits for keeping an AI agent bill under control for VPS.
How to confirm say cache dey work
No just trust the design. 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 need 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 this, 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 just the new user message. Both calls dey incur charges, because Claude API no get free tier, although for the 20,000 token prefix price wey we show above, the two calls go cost about fourteen cents.
You fit do the same check from the shell against request body wey you save 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'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 charge every time and you no dey get anything back for am.
For the 1 hour lifetime, the breakpoint get time to live (TTL):
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}Automatic caching dey available too: na 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 option. Switch to explicit breakpoints when you need control over exactly where the boundary dey.
The ordering rule wey dey kill hit rates
Cache dey match prefix byte for byte from request start, and request dey assemble for fixed order: tools, then system, then messages. If you change anything for one level, e invalidate that level and everything after am. If you edit one tool description, system prompt and the complete message history go invalidate 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 fit change.
Timestamp na the common problem. 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 go user message, for the end. Session identifier or per-request nonce dey cause the same problem and get the same solution. Retrieved documents wey different for each request belong after the cached block too. Otherwise, dem go push every stable token behind a boundary wey dey move.
The second problem na when you put breakpoint for the block wey dey change. Cache writes dey happen for the breakpoint. So if that block different every time, nothing stable go ever store, and lookback go find only entries wey earlier requests write for their own moving breakpoints. Put cache_control on the last block wey content identical across requests.
The third problem na parameter change wey you no see as prompt content. Different model get different cache. If you change tool choice, e go invalidate from system level go forward. If you add or remove tool, e go invalidate everything.
The minimum prefix, and the silent no-op
Prefix wey shorter than 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 na:
- 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 prefix length before anything else. Na this same reason the cheapest model no automatically be the cheapest for caching workload. Haiku 4.5 need prefix wey eight times longer 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 its own prefix. The system prompt and tool definitions dey for front of every request and dem no dey move, so system dey write dem once and read dem back for the rest of the session. Na why cost per turn for long session dey far below wetin 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 start of the context. Conversation history na append-only, so normal new turns dey extend prefix wey don already cache. If you edit file wey system read early for the session, e change content for 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 next turn go pay for full write. None of dem na bug. Na 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 first Claude API app for one VPS dey do am, with stable blocks first and 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 requests one after another, then compare dem by eye.
Both counters dey 0. The prefix dey below the model minimum, or the cache_control field no ever reach the API. Count the prefix tokens first, then log the request body wey you actually send.
Reads dey work, then dem stop. E go get series of hits, then one write, then hits again. The gap between requests long pass the lifetime. Accept the write, or move go the 1 hour TTL after you don check say your hit rate pass 53 percent.
Hit rate dey fall 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 go up 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 cheaper. If e dey below about 53 percent, the same thing apply to the 1 hour cache.
FAQ
How many times you need reuse one prompt before caching go pay for itself?
Once, for the 5 minute cache. Write cost na 1.25x base input, while read cost na 0.1x. So N uncached requests cost N, while N cached requests cost 1.25 plus 0.1 times N minus 1. The two costs meet for N = 1.28, so the second request don already save money. The 1 hour cache dey write at 2x and the costs meet 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 silently and both counters go read 0. If the prefix long reach, check whether content wey dey change between calls dey at or before the breakpoint. Example na timestamp or session identifier inside the system prompt. If the counters dey work before but stop now, the time between requests don 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, not change for behaviour. This one 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 gaps for your traffic dey longer than 5 minutes and your hit rate still go pass roughly 53 percent. The 2x write cost na 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 you ever paying for the longer lifetime.