Rules of prompt caching

Core Mechanism

• Initial request to Claude is processed and the work is saved to a temporary cache
• Follow-up requests with identical content retrieve cached work instead of reprocessing
• Cached work persists for one hour only
• Most useful when repeatedly sending the same content to Claude

Enabling Caching

• Not enabled by default; must manually add a cache control field to enable it
• Cache control is added to message blocks using the long-form syntax for text blocks
• Long-form syntax required: content field contains a list with a dictionary specifying type and text, plus cache_control field
• Short-form syntax (direct string assignment) does not support cache control

Cache Breakpoints

• A cache breakpoint marks where content should be cached up to and including that point
• All content before and including the breakpoint is cached; content after is not
• Follow-up requests must have identical content up to the breakpoint to use cached work
• Even small changes (like adding a word) invalidate the cache for that section

Scope of Caching

• Breakpoints can span multiple messages (user, assistant, user, etc. )
• Can be applied to text blocks, image blocks, tool use, tool results, tool schemas, and system prompts
• Behind the scenes, content is ordered as: tools → system prompt → messages
• Caching system prompts and tool schemas is common since they typically don't change

Multiple Breakpoints

• Up to 4 cache breakpoints can be added in a single request
• Multiple breakpoints allow selective caching of different sections
• Changing content after a breakpoint invalidates cache for that section but preserves earlier cached work

Minimum Content Length

• Must cache at least 1024 tokens for content to be written to cache
• Content below this threshold will not be cached even if a breakpoint is set

Takeaways

• Prompt caching saves processed work to a temporary cache (1 hour duration) when identical content is resent, avoiding reprocessing
• Caching must be manually enabled using long-form syntax with a cache_control field on message blocks; short-form syntax doesn't support it
• Cache breakpoints mark where content should be cached; follow-up requests must have identical content up to the breakpoint to retrieve cached work
• Up to 4 breakpoints can be added per request, and caching applies to text, images, tools, system prompts, and tool schemas
• Minimum 1024 tokens must be cached for content to actually write to cache