Claude Prompt Caching: The Real Setup Guide (Cut API Costs Up to 90%)

The short answer

Claude's prompt caching gives you an up to 90% discount on the input tokens you re-use across requests. Anthropic charges 0.1x the base input rate on cache reads. The catch: you pay 1.25x on the first request (the cache write), and the cache expires after 5 minutes (or 1 hour if you pay 2x on the write).

Which means prompt caching is worth it only if you actually re-use the same prefix within that window. On a chat app with returning users, it is dramatically worth it. On one-off single-call scripts, it costs you more than it saves. This guide is the honest math on when it wins.

Everything below is verified against Anthropic's official prompt caching docs. If a number looks off, click through and check yourself, do not take my word for it.

Where to use this

This is an Anthropic API feature. It works when you call Claude via the API (or via any wrapper that surfaces the cache_control parameter). It does not apply to Claude.ai chat, where Anthropic manages caching internally and you cannot control it. If you are building on top of the API, this is the single biggest cost lever available to you.

What actually gets cached

Anthropic lets you place up to 4 explicit cache_control breakpoints per request. Anything before a breakpoint that has appeared in a prior request within the TTL window gets billed at the cache-read rate.

Cacheable content:

• Tool definitions in the tools array
• Content blocks in the system array (your system prompt)
• Text, image, and document content blocks in messages.content (user and assistant turns)
• Tool use blocks and tool results in messages.content

What cannot be cached with an explicit breakpoint: thinking blocks, sub-content blocks like citations (cache the top-level document instead), and empty text blocks.

The real cost math

Pricing multipliers, straight from the Anthropic docs:

So the honest break-even math on a 5-minute cache is:

You need at least 2 reads within 5 minutes for the write to pay for itself, and 3+ reads for it to matter.

• 1 write (1.25x) + 1 read (0.1x) = 1.35x cost for 2 total requests. Base uncached would be 2.0x. Saves 32%.
• 1 write (1.25x) + 2 reads (0.2x) = 1.45x cost for 3 total requests. Base uncached would be 3.0x. Saves 52%.
• 1 write (1.25x) + 9 reads (0.9x) = 2.15x cost for 10 total requests. Base uncached would be 10x. Saves 78.5%.
• 1 write (1.25x) + 99 reads (9.9x) = 11.15x cost for 100 requests. Base uncached would be 100x. Saves 88.85%. This is where the "up to 90%" figure comes from.

The 1-hour cache is worth it when your read pattern is bursty across 5-minute windows but predictable within an hour. Break-even for the 2x write cost is 3 reads. On steady traffic where reuse is constant, always use 5-minute.

Minimum tokens to cache

Small prompts do not get cached. Every model has a minimum token threshold, and if your prefix is below it, the breakpoint is silently ignored. The Anthropic API thresholds:

Amazon Bedrock has different minimums (1,024 for Fable 5 and Mythos 5). If you are on Bedrock, check the Bedrock-specific number.

Practical read: if your system prompt plus tools is under 1,024 tokens on Sonnet, caching does nothing. The break-point is silently discarded. Verify with the response usage fields (below) before assuming it worked.

The exact syntax

Two forms. First, top-level automatic caching:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "Your long system prompt here...",
  "messages": [{"role": "user", "content": "..."}]
}

Second, explicit block-level breakpoints (this is the pattern you want for real control):

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "Your long system prompt here...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Static context that repeats across every request...",
          "cache_control": {"type": "ephemeral"}
        },
        {
          "type": "text",
          "text": "The variable per-request user message."
        }
      ]
    }
  ]
}

For a 1-hour TTL, add "ttl": "1h" inside the cache_control object.

How to verify the cache actually hit

Anthropic returns three token counts in the response usage field:

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 248,
    "cache_read_input_tokens": 1800,
    "output_tokens": 503
  }
}

• cache_creation_input_tokens: tokens you paid the 1.25x (or 2x) write cost on. First request into a new cache entry.
• cache_read_input_tokens: tokens billed at 0.1x. This is your savings line.
• input_tokens: tokens after the last breakpoint. Not eligible for caching.

On the first request, expect cache_creation_input_tokens to be non-zero and cache_read_input_tokens to be zero. On the second request within the TTL window with the same prefix, expect the reverse. If you see zeros on both after the second request, your breakpoint is on unstable content and the cache never matched. Fix the breakpoint before you rely on the savings.

The gotcha that kills most people's caching

Anthropic's docs are explicit about this. Cache writes only happen at the breakpoint, and the lookback for prior cache entries checks at most 20 positions backward. So:

Put your cache_control on the last block whose content is 100% identical across every request.

If your "static" block includes a timestamp, a per-user greeting, a request ID, the current date, a session token, or anything else that changes, the prefix hash will not match and every request re-writes the cache. You pay 1.25x on every request and never see a single cache read. This is the most common caching failure, and the response usage field is the only way to catch it before it burns through your budget.

Other things that invalidate cache:

• Any change to tool definitions invalidates the entire cache (tools, system, messages)
• Toggling web search, citations, or fast mode invalidates system and message cache
• Changing tool choice, image counts, or thinking parameters invalidates message cache
• Changing the model or the model version

If you are testing caching in dev, run two identical requests back to back and check the usage field. If the numbers match the pattern above, you are cached. If not, something changed and you have to find it.

When prompt caching actually pays off

Straight practical read:

Cache wins big:

• Chat apps with returning users (system prompt + tool defs + prior conversation reused every turn)
• RAG applications with a large stable context document plus a small variable query
• Agent loops where the same system prompt is used across dozens of tool calls
• Long-context summarization or Q&A where the document reads the same, only the question changes
• Any workflow where the same 5,000+ token prefix runs 10+ times within 5 minutes

Cache loses money:

• One-off single-call scripts where nothing repeats
• Prompts under the model's minimum token threshold (silently ignored)
• Highly variable prefixes where the "stable" part is actually rewritten every call
• Traffic patterns where the same prefix is used less than 2 times within 5 minutes (write cost is not recouped)

Cache is neutral or slight loss:

• Exactly 2 requests within TTL (32% savings, but engineering overhead of setting it up may not be worth it)
• Prompts where the cacheable prefix is small (under 500 tokens) relative to the per-request variable content

The one setup pattern that works for 90% of use cases

For an agent or chat application:

1. Put all tool definitions in the tools array
2. Put your full system prompt in the system array with a single cache_control breakpoint on the last system block
3. Put stable context (RAG docs, user profile, session config) as the first content blocks in the first user message, with a cache_control breakpoint on the last stable block
4. Put the actual per-request user message as the last content block, no breakpoint

This uses 2 of your 4 available breakpoints. Reserve the other 2 for future stable sections you add (extended RAG context, tool result caching across turns, etc). Do not spend all 4 breakpoints on day one, you will regret it when you need one and cannot add it without invalidating existing cache.

Where the rest of this lives

Caching is the cost lever. Prompt structure is the quality lever. You want both. The Cheat Sheet has 160+ tested prompt patterns with the exact temperature, top_p, and system prompt structure I use for each. Every pattern is designed to cache well (stable prefix, variable tail) so you get the API cost savings for free. $15 for Full, $35 for Pro with the deeper analysis on the reasoning-shifter codes.

The free 75-page Claude guide covers the setup basics if you want the long version first: clskillshub.com/guide