← posts / ai integrations

Prompt caching with Claude: where the breakpoints go and how to prove you got a hit

Repeated system prompts and tool definitions are the cheapest thing to cache. Where to put cache_control, 5-minute vs 1-hour TTL, the price multipliers, and the usage fields that show a hit.

if.codesNov 16, 2026 · 5 min read#claude#prompt-caching#api#costAI-assisted

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.

A conceptual look at how prompt caching protects a stable prefix of data.
A conceptual look at how prompt caching protects a stable prefix of data.

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.

The trade-off between the initial cost to write a cache and the long-term savings of reads.
The trade-off between the initial cost to write a cache and the long-term savings of reads.
0 x0.5 x1 x1.5 x2 x5-minute write · Multiplier: 1.25 x1.25 x5-minute write1-hour write · Multiplier: 2 x2 x1-hour writeCache read · Multiplier: 0.1 x0.1 xCache read
Prompt caching price vs base input price Cache read is 0.05x on Opus 5.5 and Sonnet 5.5 Source: Anthropic prompt caching docs
Prompt caching price vs base input price
Multiplier
5-minute write1.25 x
1-hour write2 x
Cache read0.1 x

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.

Checking the usage metadata to verify if a cache hit occurred.
Checking the usage metadata to verify if a cache hit occurred.
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.

Want AI wired into the systems you already run?I build LLM integrations with costs and quality you can see. The estimate is free.

Why you get misses

  • Per-request content before the breakpoint. A timestamp or request ID in the system prompt changes the prefix every time. Move it after the breakpoint.
  • Changed tool definitions. Any change to tool names, descriptions or parameters invalidates tools, system and messages.
  • Unstable JSON key order. The docs call out non-deterministic key ordering in tool_use JSON, common in Swift and Go, as a cache breaker.
  • Toggles that touch the prefix. Switching tool_choice or adding or removing images anywhere in the prompt invalidates the cache, as do changes to the web search or citations settings at the tools level.
  • Mixed TTLs in the wrong order. A 1-hour entry must appear before any 5-minute entry.

Pre-warming

For a shared prefix, send a request with max_tokens: 0 and an explicit breakpoint. It writes the cache, returns stop_reason: "max_tokens" with empty content, and bills zero output tokens. It cannot be combined with streaming, extended thinking, structured outputs, tool_choice of tool or any, or the Message Batches API. With the default 5-minute lifetime, re-warm at least every 5 minutes.

Checklist

  1. Is the stable prefix longer than your model's minimum?
  2. Is everything that changes per request after the last breakpoint?
  3. Do two identical calls in a row show cache_read_input_tokens above zero on the second?
  4. Is requests-per-lifetime high enough to justify a 1-hour write?

Sources

if.codesI build RAG, AI integrations and agent pipelines on Go and Python backends — and write about it here.
// keep reading

More posts on AI and backends.

// free quote

Read something you need? I’ll quote it for free.

RAG, AI integrations, agents or the backend underneath — tell me what you have and what should change. I read every request myself.

Free · no commitment

Tell me what you have. I’ll tell you what it takes.

1Describe the projectA few sentences is enough — about two minutes.
2I review itI read it myself and may ask a follow-up question.
3You get a free quoteScope, approach and estimate — yours to keep, no strings.
What kind of project is it?
Free and without obligation. Your details are used only to reply — see the privacy policy.