If your app sends the same long system prompt or tool list on every request, you are probably paying full input price for tokens Claude has already read. Prompt caching bills the repeated prefix as a cache read instead. It is easy to switch on and just as easy to configure wrongly: the prompt can sit under the model's minimum length, or a timestamp can sit in front of the breakpoint, and nothing errors. You just pay full price. This post shows where the breakpoints go and how to prove, from the response itself, that you got a hit.
What the cache stores
The cache covers a prefix of your request, in a fixed order: tools, then system, then messages. A change at one level invalidates that level and everything after it. Matching is exact, so one changed character before the breakpoint is a miss.

Two limits matter before you write any code:
- Minimum length. A prompt shorter than the model's minimum is processed without caching and no error is returned. The docs list 512 tokens for Sonnet 5.5, Opus 5.5 and Haiku 5.5, 1,024 for Sonnet 4.5 and 4.6, 2,048 for Opus 4.7, and 4,096 for Haiku 4.5 and Opus 4.5/4.6. Check the table for your model.
- Lifetime. The default is 5 minutes, refreshed for free every time the entry is read. You can ask for 1 hour with
"ttl": "1h". The lifetime counts from the start of the request, so generation time eats into it.
What it costs
A cache write costs more than normal input and a read costs far less. Relative to the base input price, a 5-minute write is 1.25×, a 1-hour write is 2×, and a read is 0.1× on most models. Opus 5.5 and Sonnet 5.5 list a read multiplier of 0.05×. The chart uses the standard 0.1× figure.

Read the chart as a break-even question: the write premium is paid once, each read saves most of the input price. A prefix reused twice within the lifetime already comes out ahead on the 5-minute tier; the 1-hour tier costs more up front, so it pays off when requests are spread out and the 5-minute entry would keep expiring.
Automatic or explicit breakpoints
Automatic caching is one top-level field. The breakpoint lands on the last cacheable block and moves forward as a conversation grows. It is not supported on Amazon Bedrock, which returns a 400.
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "...",
"messages": [{"role": "user", "content": "..."}]
}
Explicit breakpoints put cache_control on individual blocks, up to four per request. Use them when only the front of the prompt is stable, for example a long system prompt followed by changing content. A cache write happens only at a breakpoint, and breakpoints themselves cost nothing.
One lookback rule is worth knowing: on each request the system walks backwards from the breakpoint, one block at a time, for up to 20 positions, looking for an entry an earlier request wrote. In a long conversation, add a second breakpoint closer to the stable content before the gap grows past 20 blocks.
Prove you got a hit
Do not trust the bill; read the usage block. This script sends the same system prompt twice and prints the three counters.

import anthropic
client = anthropic.Anthropic()
# Must be longer than the minimum for your model (512 tokens for Sonnet 5.5)
SYSTEM = open("policy.md").read()
def ask(question: str) -> None:
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=300,
system=[
{
"type": "text",
"text": SYSTEM,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": question}],
)
u = response.usage
print(
"written:", u.cache_creation_input_tokens,
"read:", u.cache_read_input_tokens,
"uncached:", u.input_tokens,
)
ask("Summarise the refund rules.")
ask("Summarise the shipping rules.")
What you should see: the first call reports a non-zero cache_creation_input_tokens and zero reads. The second, sent within the lifetime, reports a non-zero cache_read_input_tokens and zero writes. Note that input_tokens is not the grand total. Per the docs it counts only the tokens after the last breakpoint that were neither read nor written, and total input is cache_read_input_tokens + cache_creation_input_tokens + input_tokens. The docs' own example: 100,000 tokens read, 0 written and 50 uncached add up to 100,050 input tokens.
call 1: written > 0, read = 0, uncached = small
call 2: written = 0, read > 0, uncached = small
If both cache_creation_input_tokens and cache_read_input_tokens are 0, the prompt was not cached at all. Most often it is under the minimum length.


