Prompt Caching

Prompt Caching is an Anthropic API feature that lets you mark portions of your API request as "this text is static, please cache it." Once a text segment is cached, subsequent API calls reading that cached segment pay only 10% of the original computation cost — meaning the same System Prompt costs full price the first time, then 10% for every subsequent read. Most intuitive understanding: think of your System Prompt as a work manual. Without caching, every API call has Claude read the complete manual from start to finish (full price). With caching, after Claude reads it the first time, subsequent calls just "verify the manual is the same" (10% cost), dramatically reducing per-call processing overhead. Activation requirements: the segment marked for caching must exceed 1,024 tokens (Claude 3 Haiku) or 2,048 tokens (Claude 3.5 Sonnet and Opus). Cache lifetime is 5 minutes, resetting on each use.

Prompt Caching use cases by benefit, from high to low: **Highest benefit**: large fixed System Prompts (over 2,000 tokens) with high daily call volumes. Per-call savings multiplied by daily call count creates substantial cumulative savings. **Medium benefit**: applications injecting reference documents into Context (e.g., RAG systems with background documents in the System Prompt). These documents are often long, and caching significantly reduces costs. **Low benefit or not applicable**: very short System Prompts (below threshold); System Prompt content differs per call (low cache hit rate); very low call frequency (5-minute cache lifetime means low hit rates for infrequent calls).

Technical implementation details for Prompt Caching: ```python response = client.messages.create( model="claude-sonnet-4-5", system=[ { "type": "text", "text": "[Your static System Prompt text, over 1,024 tokens]", "cache_control": {"type": "ephemeral"} # mark for caching } ], messages=[{"role": "user", "content": user_message}], ) ``` Important: only the static portions of your System Prompt (parts identical across every call) are suitable for caching. If your System Prompt has dynamic content (current date, user name), place dynamic content after the static portion and only enable cache_control for the static portion. Monitoring cache hit rate: in the API response's `usage` field, `cache_creation_input_tokens` (first computation) and `cache_read_input_tokens` (cache reads) let you measure caching efficiency.

Prompt Caching best practices: **Structure your System Prompt**: place static, universal rules first (this part gets cached); place dynamic, per-call-variable content last (this part doesn't cache). This maximizes cache hit rate. **Mind the cache lifetime**: the 5-minute cache lifetime means if your application has call intervals exceeding 5 minutes in some periods, the cache will expire and the next call must recompute. For applications with irregular call patterns, actual cache savings may be less than expected. **Pair with Prompt Compression**: first trim the System Prompt (reduce total tokens), then enable Caching (compute those trimmed tokens only once) — combining both techniques yields the best results. **Suitable for long-document RAG**: if you have fixed reference documents to inject into Context, place them in the System Prompt with Caching enabled to significantly reduce per-query costs.