Prompt Caching

Definition

Prompt caching lets API requests resume from a cached prompt prefix, cutting processing time and cost for repetitive prompts. Enabled via cache_control, either as automatic caching (one top-level field; the system puts the breakpoint on the last cacheable block and moves it forward as the conversation grows) or explicit cache breakpoints (placed on individual content blocks).

Key Points

• Pricing multipliers (vs base input): 5m cache write = 1.25×, 1h cache write = 2×, cache read = 0.1×. On Opus 5 ($5/MTokbase):5mwrite$6.25, 1h write $10,cacheread$0.50.
• TTL: default 5 minutes (refreshed free on each hit); 1-hour TTL available via "ttl": "1h" at 2×.
• Minimum cacheable prefix: 512 tok (Opus 5/Fable 5/Mythos 5), 1024 (Opus 4.8, Sonnet), 2048 (Opus 4.7, Mythos Preview), 4096 (Opus 4.6/4.5, Haiku 4.5). Shorter prompts cannot be cached even with cache_control.
• Mechanics: each request hashes the prefix at the breakpoint and walks backward (max 20-block lookback) for a prior write; writes occur only at breakpoints. Cacheable: tools, system prompts, text/images/documents, tool use/results. Thinking blocks, citations, and empty text blocks cannot be cached directly.
• Isolation & limits: exact match required; cache isolated per workspace (org-level on Bedrock/Vertex); cache hits are not deducted against rate limits; pre-warming possible via max_tokens: 0 (no output billed).

Implications

Prompt caching is the mechanism behind the “repeated content is cheap” rule in token-usage-reduction. The 0.1× read price makes conversation history, system prompts, and tool definitions the cheapest content to re-send — so cache-aware tools (like claude-code-system-prompt’s deferral of tool definitions) exist to keep cacheable prefixes stable and large. The per-model minimum-prefix thresholds and write multipliers (1.25–2×) mean caching is only a win above the prefix minimum and when reads dominate writes.

Open Questions

• Whether the model-specific thresholds shift as new models ship (version-sensitive numbers).
• How automatic breakpoint placement performs vs explicit breakpoints on long, heterogeneous prompts.
• Anthropic’s read/write multipliers (0.1× read, 1.25–2× write) and OpenAI’s (1.25× write) are provider-specific and version-sensitive; do not compare numerically across providers.

OpenAI: Prompt caching (confidence: high)

OpenAI’s prompt caching uses exact-prefix matching at cache breakpoints, auto-enabled for prompts ≥1024 tokens.

• Routing & lookup: requests hash the initial prefix (first ~256 tokens, model-dependent) for machine routing; prompt_cache_key adds explicit routing control to improve hit rates on shared long prefixes. Maintain traffic at ~15 requests/minute per key to prevent cache misses at high volume.
• GPT-5.6 behavior change: the implicit breakpoint is placed at the latest user/tool message and — unlike earlier models — there is no fallback to the longest matching unmarked prefix before it. Shared static prefixes can therefore yield cached_tokens: 0 when the latest message changes. Fix: explicit prompt_cache_breakpoint after the stable prefix + shared prompt_cache_key; set prompt_cache_options.mode: explicit to disable the implicit breakpoint.
• Breakpoints: mode: implicit (default; breakpoint on latest message + any explicit ones) vs explicit (only explicit breakpoints eligible for reads/writes). A breakpoint marks the exact end of the cached prefix; content after it may change without invalidating the cache. TTL 30m (only supported value; minimum lifetime, not max retention). Up to 4 new cache writes/request; reads consider up to the latest 50 breakpoints; longest matching prefix wins.
• Retention: GPT-5.6+ uses prompt_cache_options.ttl. Earlier models use prompt_cache_retention: in_memory (5–10 min inactivity, max 1h, volatile GPU memory only) or 24h extended (KV tensors offloaded to GPU-local storage; prompt text itself never persisted). gpt-5.5/gpt-5.5-pro support only 24h.
• Pricing: GPT-5.6+ cache writes bill 1.25× the uncached input rate (exposed via cache_write_tokens); reads bill at the cached-input rate. Min cacheable prefix: 1024 tok strict (GPT-5.6+), 1024–2048 (GPT-5.5 and earlier).
• Structuring: static content (instructions, examples, tools, images) first; variable content last — identical to the Anthropic advice on this page.

Related

token-usage-reduction — cost-lever concept this mechanism underlies token-optimizer-mcp — tool that measures prompt-cache economics from transcripts claude-code-system-prompt — tool definitions deferred to keep cacheable prefixes stable claude-code-cache-fix — tool that repairs silent cache breaks on /resume and surfaces hit rates gpt-5-6 — the OpenAI model family whose caching behavior differs from earlier snapshots

Sources

• raw/external/platform-claude-com-prompt-caching-a167718a.md
• raw/external/developers-openai-com-prompt-caching-a7f81296.md
• raw/external/developers-openai-com-prompt-caching-bc9e0f40.md