Prompt caching
Re-read a stable prefix at a fraction of the input price — what to cache, what not to, and how to verify it worked.
Prompt caching stores a prefix of your request so later calls that share it are billed at a reduced input rate. For anything with a large stable preamble — a system prompt, tool schemas, a document being questioned — it is the highest-return change available.
What makes a good cache target
| Good | Why |
|---|---|
| System prompts | Byte-identical on every call in a session |
| Tool / function definitions | Stable across an entire agent run, and often large |
| A document being asked about repeatedly | One upload, many questions |
| Few-shot examples | Fixed, and frequently long |
| Bad | Why |
|---|---|
| The user's latest message | Different every time — never a cache hit |
| Anything with a timestamp or request id near the top | One changing byte early in the prefix invalidates everything after it |
| Short prompts | Below the minimum cacheable length, so there is nothing to gain |
Marking a prefix
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [{
"type": "text",
"text": "<long stable instructions...>",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "Question that changes every call"}]
}Everything up to and including the marked block becomes the cached prefix. Order matters: put stable content first and volatile content last.
Verifying it works
Check the usage object. A cache hit reports tokens under cache-read rather than ordinary input. If cache-read stays at zero across repeated calls, your prefix is not actually identical — a common cause is a timestamp, a session id or non-deterministic JSON key ordering in the preamble.
json.dumps(obj) without sort_keys=True can reorder keys between runs, which changes the bytes and silently costs you every cache hit.Where it matters most
Agentic tools resend the same system prompt and the same tool schemas on every single turn. In a 50-turn session that preamble is paid for 50 times without caching, and roughly once with it.