Prompt caching

Most requests repeat themselves: the same system prompt, the same tool definitions, the same long document, the same conversation so far. Prompt caching lets the model reuse the work it already did on that repeated beginning, and you pay a fraction of the input price for the cached part.

It matters most for coding agents and chat apps, which resend almost their whole context on every turn.

How it is priced

Each model with caching has a cached_input price next to its input price, in the model list and on its model page. For example, claude-sonnet-4-6 charges $3 per 1M input tokens and $0.30 per 1M cached input tokens. Some models also charge more than the input price to write a cache entry the first time; their page lists it.

Cached tokens show up in usage, and in your request logs:

"usage": {
  "prompt_tokens": 12850,
  "completion_tokens": 210,
  "prompt_tokens_details": { "cached_tokens": 12288 }
}

On the Messages endpoint they are cache_read_input_tokens and cache_creation_input_tokens.

Automatic caching

Many models — including the GPT, Gemini, DeepSeek and Kimi families — cache automatically. You change nothing: when a request starts with the same tokens as a recent one, the shared prefix is served from cache. To get the most out of it:

• Put what stays the same first: system prompt, tool definitions, reference documents.
• Put what changes last: the newest user message.
• Don't put timestamps or request IDs in the system prompt; one changed token early on breaks the match for everything after it.

Explicit caching with cache_control

Claude models cache only what you mark. Add a cache_control breakpoint to the last block of the part you want reused, and everything up to it is cached:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "You are a support agent for Acme. Here is the full product manual: ...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "How do I reset the device?" }]
}

The same marker works on Chat Completions, on a text part of a message:

{
  "role": "system",
  "content": [
    { "type": "text", "text": "Long, stable instructions...", "cache_control": { "type": "ephemeral" } }
  ]
}

• A cache entry lasts five minutes by default, refreshed every time it is used. "ttl": "1h" keeps it for an hour, at a higher write price.
• Up to four breakpoints per request. Marking tool definitions and the system prompt separately lets either change without losing the other.
• Below a model-specific minimum length (about 1,024 tokens for most Claude models), nothing is cached. The request still succeeds.

Claude Code and most coding agents set these markers for you.

Checking it works

Send the same long prompt twice within a few minutes. The second response should report most of the prompt as cached tokens. If it reports none, look for something that changes at the start of the prompt between requests.