Prompt Caching
APIDefinition
A Claude API feature that caches frequently-used prompt content (system prompts, large documents, tool definitions) to reduce cost and latency on repeated API calls. Cached tokens are billed at a discounted rate. Cache has a TTL that resets on each use. Must be enabled by marking content with cache_control.
Example Usage
Cache the system prompt and product documentation with cache_control: {type: 'ephemeral'} to save costs across thousands of daily requests.
Why It Matters for the CCA-F Exam
Prompt caching is a high-weight exam topic because it combines cost optimization, API mechanics, and a subtle correctness requirement (prefix ordering). Candidates must know the prefix-match rule, both TTL options and their cost multipliers, how to verify a hit via `usage`, and the common mistake of injecting volatile content into the cached prefix.
In Depth
Prompt caching lets you pay once to process a large, stable block of tokens and then reuse those processed representations across many subsequent API calls. Instead of resending and re-processing your full system prompt, reference documents, or tool definitions on every request, you mark content with cache_control: {type: "ephemeral"} and the API stores the KV cache at that boundary.
Prefix-match semantics — the most important thing to understand
Caching operates as a strict prefix match on the rendered request. The API renders your request in a fixed order: tools → system → messages. It then looks for the longest cached prefix it can reuse. A single byte change anywhere in that prefix — including adding a timestamp, tweaking a tool description, or reordering system prompt paragraphs — invalidates the cache for everything after the change point. This is why content ordering is a correctness issue, not just a style choice:
- Most stable first: tool definitions, static system prompt sections, reference documents
- Least stable last: dynamic instructions, the user's current message,
datetime.now()injections
The classic silent cache-killer is calling datetime.now() inside the system prompt. The cache never hits because every call produces a distinct prefix byte sequence.
Enabling caching
Add cache_control: {type: "ephemeral"} to the content block or message you want to cache up to. The default Cache TTL is 5 minutes; pass ttl: "1h" for a 1-hour TTL (at a higher write cost). A cache write costs approximately 1.25× the normal input token price for 5-minute entries and approximately 2× for 1-hour entries. A cache read costs approximately 0.1× the normal input token price — a roughly 10× read discount.
Verifying cache hits
The API response's usage object exposes cache_read_input_tokens (tokens served from cache) and cache_creation_input_tokens (tokens written to cache on this call). A non-zero cache_read_input_tokens confirms a hit; zero on both means neither a write nor a read occurred, which usually indicates a prefix mismatch.
Interaction with [batch-api](/glossary/batch-api)
Prompt caching and the Message Batches API compose naturally. A large shared system prompt cached once is reused across every item in the batch, compressing the effective cost of bulk processing significantly. For a complete treatment of how caching fits into broader token budget decisions, see Context Token Management & Caching.
How It Compares
| Attribute | 5-minute TTL (default) | 1-hour TTL (`ttl: "1h"`) |
|---|---|---|
| Write cost multiplier | ~1.25× normal input rate | ~2× normal input rate |
| Read cost multiplier | ~0.1× normal input rate | ~0.1× normal input rate |
| Best for | High-frequency, short-session workloads | Low-frequency, long-session or overnight jobs |
| TTL reset on each use | Yes | Yes |
| Enable with | cache_control: {type: "ephemeral"} | cache_control: {type: "ephemeral", ttl: "1h"} |
| Verify hit via | usage.cache_read_input_tokens | usage.cache_read_input_tokens |
Frequently Asked Questions
Why does my cache never hit even though I'm sending the same system prompt?
The most common cause is dynamic content injected into the cached prefix — a timestamp, request ID, or user name that changes on every call. Move any volatile content to the end of the messages array, after the cache boundary, so the stable prefix is never disturbed.
Can I cache multiple segments of a single request?
You can mark multiple content blocks with `cache_control`, but caching still operates on the longest matching prefix. Marking a block in the middle of an otherwise-changed prefix does not guarantee that block is cached independently — the prefix up to that point must still match.
Does caching work with tool definitions?
Yes. Tool definitions are rendered before the system prompt in the prefix order, so they are excellent candidates for caching. If your tool list is stable across requests, marking it with `cache_control` saves re-processing costs on every call.