Claude Prompt Caching: Complete Guide With Examples

Claude Prompt Caching: Why It Matters

Most AI apps resend the same thing on every request: a long system prompt, tool definitions, a reference document, or the whole conversation so far. Without caching, you pay full input price for those identical tokens every time.

Prompt caching lets Claude reuse that repeated prefix. You pay a bit extra the first time, then a small fraction on every reuse. For chatbots, agents and document Q&A, it's usually the single biggest cost saving available.

This guide shows how it works, what it costs, how to turn it on, and how to check it's actually working.

🎯 Quick Answer (30-Second Read)

• What it does: caches the beginning of your prompt so later requests reuse it at a fraction of the input price.
• Cost: a cache write costs 1.25× input (5-minute cache) or 2× (1-hour cache). A cache read costs 10% of input on most models, 5% on Opus 5.5 and Sonnet 5.5, and 2.5% on Fable 5.1.
• Enable it: add cache_control={"type": "ephemeral"} to your request.
• Verify it: check response.usage.cache_read_input_tokens is above zero on repeat calls.
• #1 mistake: anything that changes at the start of the prompt (like a timestamp) breaks the cache.

How Prompt Caching Works

Caching is a prefix match. Claude caches everything up to a cache point. On the next request, if the beginning is byte-for-byte identical, that part is read from cache.

Order matters: tools → system prompt → messages. Put stable content first and changing content last.

What It Costs

Prices per million tokens (from Anthropic's pricing page):

Step-by-Step: Enable Prompt Caching in Python

Option 1: Automatic caching (simplest)

Add cache_control at the top level. Claude caches up to the last cacheable block automatically.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

LONG_SYSTEM_PROMPT = open("support_handbook.md").read()  # stays identical every call

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=LONG_SYSTEM_PROMPT,
    messages=[{"role": "user", "content": "How do refunds work for annual plans?"}],
)

Option 2: Mark exactly what to cache

Put cache_control on a specific block. Use "ttl": "1h" for a 1-hour cache when requests are spread out:

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": LONG_SYSTEM_PROMPT,
        "cache_control": {"type": "ephemeral", "ttl": "1h"},
    }],
    messages=[{"role": "user", "content": "How do refunds work for annual plans?"}],
)

The default cache lifetime is 5 minutes, and each cache hit refreshes it.

How to Verify Cache Hits

Every response reports what happened:

u = response.usage
print("written to cache:", u.cache_creation_input_tokens)
print("read from cache: ", u.cache_read_input_tokens)
print("uncached input:  ", u.input_tokens)

• First call: cache_creation_input_tokens > 0
• Repeat calls (within the TTL): cache_read_input_tokens > 0

If cache_read_input_tokens stays at 0 on identical repeat calls, something is breaking the cache. See the mistakes below.

Common Mistakes That Silently Break Caching

• A timestamp or ID at the top of the system prompt. For example f"Today is {datetime.now()}". Every request has a different prefix, so the cache never hits. Move changing values to the end of the messages.
• Unsorted JSON. json.dumps() of a dict with varying key order changes the bytes. Use sort_keys=True.
• Changing the tools list. Tools come first in the prefix, so adding, removing or reordering tools invalidates everything after.
• A prompt too short to cache. Each model has a minimum cacheable length (as low as 512 tokens on the newest models). Shorter prefixes simply don't cache, with no error.
• Switching models. Caches are per model, so a cascade between models doesn't share them.

Worked Example: Support Chatbot

A chatbot sends a 10,000-token handbook as the system prompt with every question, 50,000 times a month, on Sonnet 5.5.

Illustrative maths at list prices. Cache writes happen whenever the cache expires, so real savings depend on how steady your traffic is. Steady traffic keeps the cache warm.

When Prompt Caching Helps Most

Caching also stacks with the Batch API discount (50% off), so batch jobs over a shared document get cheaper still.

Frequently Asked Questions

Conclusion

Prompt caching is the easiest big win in the Claude API: add one cache_control setting, keep your prefix stable, and repeated tokens cost a small fraction of normal input. Check cache_read_input_tokens to confirm it works, and keep timestamps and IDs out of the start of your prompt.

Sources

• Anthropic docs: Prompt caching
• Anthropic docs: Pricing, for cache write and read prices

Last verified: 14 October 2026.

Related reads: Claude API Pricing Explained · Claude Models Explained · Claude Code CLI Tutorial · RAG Explained

I write about AI dev tools and how real products are built. Follow on LinkedIn or X, or invite me to speak.