Claude Prompt Caching: Setup Cheat Sheet

Prompt caching lets Claude resume from a prefix it has already processed, so the part of your prompt that repeats on every call gets much cheaper and faster.

The 4 steps

1. Put static content first. The cache prefix is built in this order: tools, then system, then messages. Put tool definitions, system instructions, context and examples at the top. Put the user's new question last.
2. Mark where the static part ends. Add "cache_control": {"type": "ephemeral"} to the last static block. Or add a single top-level cache_control field and the API places the breakpoint on the last cacheable block for you.
3. Clear the minimum length. Shorter prefixes aren't cached, even when they're marked.
   • 512 tokens: Claude Opus 5.5, Opus 5, Fable 5.1, Fable 5
   • 1,024 tokens: Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5, Opus 4.8
   • 4,096 tokens: Claude Haiku 4.5
4. Verify it hit. In the response's usage, cache_creation_input_tokens counts the tokens written to the cache. cache_read_input_tokens counts the tokens read from it. If both are 0, nothing was cached.

Minimal example

"system": [
  {"type": "text", "text": "YOUR LONG, UNCHANGING INSTRUCTIONS",
   "cache_control": {"type": "ephemeral"}}
]

The price math

• A 5-minute cache write costs 1.25× the base input price.
• A cache read costs 0.1× on most models. Opus 5.5 is 0.05×, and Fable 5.1 and Mythos 5.1 are 0.025×.

How long it lasts

• By default the cache lasts 5 minutes. It's refreshed for free every time it's used.
• If your calls are more than 5 minutes apart, use "ttl": "1h". A 1-hour write costs 2× the base input price.

What quietly breaks your cache

• Editing anything above the breakpoint. A change at one level (tools → system → messages) invalidates that level and everything after it. Changing tool definitions invalidates the whole cache.
• Putting changing content early. Timestamps and user names belong below the breakpoint.
• Too many breakpoints. The limit is 4 per request.

Sources: Anthropic's prompt caching docs (platform.claude.com) and the Amazon Bedrock prompt caching guide.