# 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.

_Source: https://aiprimetech.io/docs/guides/prompt-caching/ · Home > Docs > Working with the API_

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

```json
{
  "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.

> Serialise cached content deterministically. `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.

- [Cost control](https://aiprimetech.io/docs/guides/cost-control/) — The other three levers
- [Tool use](https://aiprimetech.io/docs/api-reference/tool-use/) — Why schemas dominate input
- [Messages API](https://aiprimetech.io/docs/api-reference/messages/) — Where cache_control goes


---
_ClaudeAPIKey.dev is an independently operated, Anthropic-compatible API gateway. Not affiliated with Anthropic._