How to Set Up Claude Prompt Caching So It Actually Saves Money: The 512-Token Floor, 4 Breakpoints, and the One Line Most People Get Wrong (2026 Guide)

If you call the Claude API for anything repetitive — the same tool definitions, the same system instructions, the same reference document, request after request — you should not be paying full price for that repetition every time.

The mechanism is prompt caching. Set it up correctly and repeated context costs a tenth of the base input price, or on Claude Fable 5.1 just 2.5% of it. Set it up wrong and you save nothing while paying extra for cache writes.

Here is how to get it right, straight from the official docs.

1. Understand the billing first

Cache pricing is expressed as a multiplier on the base input price:

For Claude Opus 5 (base input US$5 per million tokens):

• 5-minute cache write: US$6.25
• 1-hour cache write: US$10.00
• Cache read: US$0.50

The takeaway: writing costs slightly more, reading costs dramatically less. So caching pays off only when you actually reuse it. Write once, read once, and you lose money.

2. Is your content long enough?

Content below the floor is never cached at all — this is the single most common reason people say “I turned it on and saw no saving”. Official minimums:

Check the length of the block you want cached. A single short system line is usually well under the floor and will simply never cache.

3. The actual syntax

Add cache_control to the block you want cached:

{
  "type": "text",
  "text": "(your large unchanging block)",
  "cache_control": {"type": "ephemeral"}
}

For a 1-hour TTL instead of the 5-minute default:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

ephemeral is currently the only supported cache type.

What can be cached:

• Tool definitions (the tools array)
• System messages (content blocks in the system array)
• Text messages (blocks in messages, both user and assistant turns)
• Images and documents (user turns)
• Tool use and tool results

What cannot: thinking blocks cannot be marked directly (though they can be cached as part of a previous assistant turn), sub-content blocks such as citations (cache the top-level block instead), and empty text blocks.

4. The rule that matters most

The docs state it directly: place cache_control on the last block whose prefix is identical across the requests you want to share a cache.

That single sentence is where most setups fail.

The classic mistake is putting the breakpoint on something that changes — a timestamp, or the user’s per-request question. The hash differs every time, so it never hits, and you simply pay the 1.25x write premium on every call.

The right mental model: treat every request as a fixed front half plus a varying back half, and put the breakpoint at the end of the fixed half.

Also note: at most 4 explicit breakpoints. If all four are taken, the API returns a 400 error because there is no slot left for automatic caching.

5. What invalidates a cache

Caching is hierarchical, always in this order: tools → system → messages.

A change at any level invalidates that level and everything after it.

From the official table:

What this means in practice: if you tweak tool descriptions every other day, your cache is invalidated almost every run. Stabilise your tool definitions first, or caching is pointless.

6. Automatic caching looks back 20 blocks

Beyond explicit breakpoints, Claude also looks for cache hits automatically. It checks the position where a previous request wrote a cache entry; if there is no hit, it walks backwards block by block, up to 20 positions, then stops.

A run of consecutive tool_use blocks counts as one position, as does a run of tool_result blocks.

Why long conversations suffer: once too many turns pile up, the reusable prefix can fall outside the lookback window. This is exactly why agentic workloads should keep the unchanging material grouped at the front.

7. The checklist

1. Measure: does the block clear your model’s floor (512 / 1,024 / 2,048 / 4,096)?
2. Reorder: move everything that never changes — tools, system instructions, reference docs — to the front.
3. Place the breakpoint: cache_control on the last fixed block, never on varying content.
4. Pick a TTL: default 5 minutes if the next call comes soon; "ttl": "1h" only when you need the hour (write costs double).
5. Stay under 4 explicit breakpoints.
6. Freeze tool definitions: change them and the whole chain collapses.
7. Verify: send the same request twice and read the cache-read token count in the response — a number is proof, a feeling is not.

8. When not to bother

• One-off requests: written once, read once, you pay 1.25x for nothing.
• Content under the floor: it will never cache.
• Requests that differ every time: there is no shared prefix to reuse.

Official links

• Prompt caching docs: https://platform.claude.com/docs/en/build-with-claude/prompt-caching

More on this site

• Claude tool page
• Claude Fable 5.1 cuts cache reads by 75%
• Cutting your Gemini API bill with batch and cache

Steps and figures read directly from the official documentation on 2026-09-05. API specifics change; check the docs before implementing.