Claude Prompt Caching Setup: Code + Real Cost Math (2026)

TL;DR: Claude prompt caching cuts repeated prompt prefixes to 5–10% of the input price. Enable it two ways: a single top-level cache_control: {"type": "ephemeral"} for automatic caching, or explicit breakpoints on content blocks (max 4) for control. Writes cost 1.25× input (5-minute TTL) or 2× (1-hour TTL), so a prefix needs at least 2 reuses to break even. On Sonnet 5.5, a 30K-token prefix called 50 times costs $0.22 cached vs $3.00 uncached — about 93% off. Prices checked 15 October 2026.

Anthropic is the one provider that makes you ask for the discount instead of giving it automatically. That friction is also the control: you decide exactly which parts of your prompt get cached, down to the content block. This post is the hands-on companion to Prompt Caching Compared and the mechanics explainer Prompt Caching Explained — what to write, where to put it, how to prove it's working, and what each request actually costs in real numbers.

The two ways to turn it on#

Option A: automatic caching (one line)#

Add a top-level cache_control field to your Messages request. Anthropic handles the rest — no per-block markers, no beta route (the old beta.messages prompt-caching route is deprecated). Verified against current implementation references on 15 October 2026.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",  # model IDs change — check the catalog, don't trust old tutorials
    max_tokens=1024,
    cache_control={"type": "ephemeral"},  # automatic caching, 5-minute TTL
    system="You are a code reviewer. <long stable instructions...>",
    messages=[{"role": "user", "content": "Review this diff: ..."}],
)

The same call with curl:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "<long stable instructions...>",
    "messages": [{"role": "user", "content": "Review this diff: ..."}]
  }'

Option B: explicit breakpoints (up to 4, you choose)#

Put cache_control on individual content blocks. Each breakpoint means "cache everything up to and including this block." This is the mode to use when only part of your prompt is stable — a big reference doc at the top, a dynamic question at the bottom.

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": short_instructions},
        {"type": "text", "text": large_reference_doc,  # ~30K tokens, static
         "cache_control": {"type": "ephemeral"}},      # breakpoint 1: cache up to here
    ],
    tools=[
        *tool_definitions,
        {"name": "last_tool", "description": "...", "input_schema": {...},
         "cache_control": {"type": "ephemeral"}},     # breakpoint 2: cache tool defs too
    ],
    messages=[{"role": "user", "content": "Summarize section 3."}],
)

For a 1-hour TTL instead of the 5-minute default, add "ttl": "1h" to the block:

"cache_control": {"type": "ephemeral", "ttl": "1h"}  # 1-hour TTL, 2x write premium

Where breakpoints go — and where they can't#

The placement rule is the whole game: static first, dynamic last. The cached prefix must be byte-identical across requests, so everything that changes between calls — the user's question, timestamps, request IDs, usernames — goes after the last breakpoint.

• Cache this: system prompt blocks, tool definitions (big win for agents with 20+ tools), reference documents prepended to the conversation, images and documents in user turns.
• Don't cache this: the dynamic tail of your prompt. In a multi-turn conversation the growing history becomes part of the prefix automatically — put your breakpoint at the end of the static section and let the tail stay fresh.
• Can't be cached: thinking blocks, empty text blocks, sub-content blocks (like citations).
• Minimums: the cacheable prefix must be at least 1,024 tokens on Sonnet/Opus, 2,048 tokens on Haiku. Content is cached in 128-token increments (rounded up).
• Don't mark every message. One breakpoint at the end of the static section is usually enough. The extra three breakpoints exist for layered setups (e.g. stable docs and a semi-stable retrieved context) — not for decoration.

The real cost math#

Current list prices, USD per million tokens, checked 15 October 2026:

For Bangladeshi billing: at ৳123.45 per USD (October 2026), Sonnet 5.5 works out to about ৳246.90/M input, ৳308.63/M for a 5-minute cache write, ৳493.80/M for a 1-hour write, and ৳12.35/M for cache reads.

Break-even in one line#

In units of the base input price, caching a prefix used N times costs 1.25 + 0.10×(N−1) against N×1.0 without caching (Sonnet 5.5, 5-minute TTL):

• 1 use: 1.25 vs 1.0 — caching loses. Don't mark one-off prefixes.
• 2 uses: 1.35 vs 2.0 — caching saves about a third.
• 10 uses: 2.15 vs 10 — caching saves about 80%.

Worked example A: coding agent, bursty traffic#

A 30,000-token stable prefix (system prompt + tool definitions), 50 requests inside one 5-minute window, Sonnet 5.5:

• Without caching: 50 × 0.03M × $2.00 = $3.00
• Cache write: 0.03M × $2.50 = $0.075
• Cache reads (49): 49 × 0.03M × $0.10 = $0.147
• With caching: $0.222 ≈ $0.22 — about 93% off the prefix, saving $2.78.

The chart above shows the shape: the uncached cost per request stays flat at 6.0¢ while the cached cost falls from 7.5¢ on the first request to 0.44¢ at 50 requests. Caching wins from the second reuse.

Worked example B: support bot, spaced traffic#

A 100,000-token retrieved-docs prefix, one request every 25 minutes over an 8-hour day — 20 requests, Sonnet 5.5:

• Without caching: 20 × 0.1M × $2.00 = $4.00
• 5-minute TTL (expires between requests, so every request rewrites): 20 × 0.1M × $2.50 = $5.00 — worse than not caching at all.
• 1-hour TTL: write 0.1M × $4.00 = $0.40; reads 19 × 0.1M × $0.10 = $0.19; total $0.59 — about 85% off.

The lesson: match the TTL to your request cadence. The 2× write premium on the 1-hour TTL only wins when the 5-minute cache would keep expiring between requests.

Worked example C: when caching loses#

That same 30K-token prefix used exactly once costs $0.075 cached vs $0.06 uncached — a 25% penalty for nothing. And a 900-token system prompt on Sonnet falls under the 1,024-token minimum: it can't be cached at all. Caching is a multiplier on repetition, not a discount on size.

Verify it's actually working#

Read the usage object — this is the receipt:

u = response.usage
print("fresh input:", u.input_tokens)
print("written to cache:", u.cache_creation_input_tokens)   # > 0 on the first call
print("read from cache:", u.cache_read_input_tokens)       # > 0 on later calls

Two rules for reading it: total input is the sum of all three fields (input_tokens alone understates your prompt), and if both cache fields are zero, nothing was cached. A healthy multi-turn session shows cache_creation_input_tokens once and cache_read_input_tokens on every call after.

Why zero hits — the three usual causes:

1. Something dynamic inside the prefix. A timestamp, user ID, or request ID before the breakpoint breaks the byte-identical match. Move it after the last breakpoint.
2. Non-deterministic tool serialization. If your tool definitions serialize differently between calls, the prefix never matches. Serialize once, reuse the object.
3. Under the minimum. A cacheable prefix below 1,024 tokens (Sonnet/Opus) or 2,048 (Haiku) silently earns nothing — full price, no error.

Five rules for a high hit rate#

1. Static first, dynamic last. Prefix discipline is 90% of the hit rate.
2. One breakpoint is usually enough. Mark the end of the stable section; spend the other three only on genuinely layered prefixes.
3. Keep it stable across turns. In multi-turn chats the conversation history joins the prefix — breakpoint before the tail, not inside it.
4. Match TTL to cadence. 5-minute for bursty, 1-hour for spaced-but-predictable.
5. Measure cache share: cache_read_input_tokens ÷ total input. Long sessions with a stable prefix should show 70%+; under 30% means something dynamic is leaking into your prefix.

Using this through tokens.bd#

The model catalog lists Claude Sonnet 5.5 at $2.20/M input (checked 15 October 2026), and tokens.bd exposes an Anthropic-compatible endpoint — so the same cache_control code above works with a base-URL and key swap (endpoint details). Watch the usage object's cached-token fields to confirm hits on your first runs. And because caching shrinks the average bill while the write premium hits first, put heavy cached workloads behind their own key with per-key spend caps plus usage alerts — a runaway loop multiplies against the write price before any read discount lands.

To fold cached rates into a monthly estimate, run the method in how to estimate your monthly token bill with the read/write prices from the table above. For the full provider landscape, see Prompt Caching Compared: Anthropic vs OpenAI vs Bedrock.

Claude prompt caching FAQ#

Do I still need the prompt-caching beta header? No. Caching is GA on the Messages API — the old anthropic-beta: prompt-caching-2024-07-31 route and beta.messages client are deprecated. Use top-level cache_control or per-block markers on the standard endpoint.

How do I know caching is working? Check response.usage: the first call shows cache_creation_input_tokens, later calls show cache_read_input_tokens. If both are zero, nothing was cached. Total input is the sum of input_tokens plus both cache fields.

Why is my cache hit rate near zero? Almost always one of three causes: dynamic content (a timestamp, user ID, or request ID) sits inside what you thought was the static prefix; tool definitions serialize non-deterministically between calls; or the cacheable prefix is under the 1,024-token minimum (2,048 for Haiku). All three fail silently — full-price input, no error.

Should I use the 5-minute or 1-hour TTL? Bursty traffic (requests seconds or minutes apart): 5-minute. Spaced but predictable (every 20–30 minutes): 1-hour — the 2× write premium beats paying 1.25× on every request when the 5-minute cache keeps expiring. Worked example B above turns a $5.00 day into $0.59.

Does prompt caching change model outputs? No. It caches the prefix computation, not generated tokens — sampling runs normally with your temperature and top-p. Latency drops because the prefix isn't recomputed, which is why cache-heavy prompts typically feel 40–80% faster.

List prices and mechanism details checked 15 October 2026. Provider pricing and defaults change; Anthropic's pricing page is the authority for list prices, and the model catalog for prices on Tokens.

Sources: Anthropic pricing · Anthropic prompt caching: how to verify hits (Oct 2026) · Prompt-caching implementation reference · Prompt Caching Compared: Anthropic vs OpenAI vs Bedrock · tokens.bd models · tokens.bd docs