Claude API prompt caching: how it works and what it saves

What prompt caching does to a Claude API bill

Prompt caching tells Anthropic to store a reusable prefix of your request — anything up to a breakpoint you set — so the next request with the same prefix reads it from cache instead of reprocessing it. Cache reads cost a fraction of fresh input tokens, while cache writes cost a small premium over input. If your application resends the same large context (a system prompt, a codebase snapshot, a document set), caching converts the most expensive part of every call into the cheapest.

Cache writes and cache reads are metered as separate token buckets in the API response and on your bill, so you can always see exactly what the cache earned you. Nothing about the response itself changes — same model, same quality, same streaming behavior.

See also: How to save tokens on the Claude API

Placing cache_control breakpoints in a request

Claude requests get a five-minute prompt cache automatically when cache_control is absent or null everywhere. Add a cache_control marker when you need an exact native Messages breakpoint. Everything before the marker — system prompt, tool definitions, earlier messages — becomes the cacheable prefix. Here is a real request against apiToken.sale with the system prompt cached:

curl https://router.apitoken.sale/v1/messages \
  -H "x-api-key: sk-pool-•••" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are a senior reviewer... (long stable instructions)",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [{"role": "user", "content": "Review this diff: ..."}]
  }'

• You can set up to four cache_control breakpoints per request — a common layout is one after tools, one after the system prompt, and one after a large reference document.
• Caching matches prefixes exactly, from the first token. Change one character in the system prompt and everything after it misses the cache.
• Only blocks above the minimum cacheable size are stored — about 1,024 tokens on Sonnet and Opus models, more on Haiku. Short prompts silently skip caching.
• Put volatile content (timestamps, user-specific data) after the last breakpoint, never inside the prefix.

Using Claude caching from OpenAI-compatible clients

Claude models use the same prompt-cache path through native Messages, Chat Completions and Responses. On the OpenAI-compatible paths, send cache_control as a top-level custom request extension. Do not put an Anthropic breakpoint inside an OpenAI message or input part: those parts are translated. If you omit the extension, apiToken.sale inserts the automatic five-minute cache after translation.

# Chat Completions — explicit 1-hour Claude cache
curl https://router.apitoken.sale/v1/chat/completions \
  -H "Authorization: Bearer sk-pool-•••" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [
      {"role":"system","content":"<long stable instructions>"},
      {"role":"user","content":"Review this diff"}
    ],
    "max_completion_tokens": 1024,
    "cache_control": {"type":"ephemeral","ttl":"1h"}
  }'

# Responses — explicit 1-hour Claude cache
curl https://router.apitoken.sale/v1/responses \
  -H "Authorization: Bearer sk-pool-•••" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "instructions": "<long stable instructions>",
    "input": "Review this diff",
    "max_output_tokens": 1024,
    "cache_control": {"type":"ephemeral","ttl":"1h"}
  }'

• The OpenAI SDK does not define cache_control. Pass it through extra_body, and pass the Anthropic beta through extra_headers.
• Chat Completions reports hits in usage.prompt_tokens_details.cached_tokens.
• Responses reports hits in usage.input_tokens_details.cached_tokens.
• This extension applies only when the selected model is in the anthropic/* catalog plane. OpenAI and Gemini models keep their provider-native cache behavior.

Cache write vs cache read pricing

Anthropic prices cache operations as multipliers of the model's input token rate. Writing is a one-time premium per cached block; reading is where the money comes back. On apiToken.sale the flat 50% B2C discount applies to every usage leg, cache legs included, after the official spend is computed.

The default cache entry lives five minutes and the timer resets on every hit, so an active session keeps its cache warm indefinitely. A one-hour TTL is available at a higher write cost for bursty workloads. A cache read costs one-tenth of fresh input — and one-twentieth once the discount lands — so a prefix read three times within its TTL is already cheaper than sending it fresh twice.

Cache entries are not shared across accounts and never leak between apiToken.sale customers. Your cached prefix is only reusable by requests authenticated under the same upstream account context.

Workloads that hit the cache — and ones that never will

• Coding agents and IDE assistants that resend the same repo context, CLAUDE.md, and tool schemas with every turn.
• RAG pipelines querying a fixed document set — cache the corpus, vary only the question.
• Chatbots with long stable system prompts and few-shot example libraries.
• Batch jobs that classify or extract from many short items against one large instruction block.

Caching does nothing for one-off questions, prompts that change on every call, or prefixes below the minimum size. If each request is genuinely unique, you pay the write premium and never collect a read — measure before you blanket-enable it.

Confirming cache hits in the usage object

Every Messages API response reports the cache legs directly in its usage block. A warm cache looks like this:

"usage": {
  "input_tokens": 38,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 14802,
  "output_tokens": 412
}

Watch cache_read_input_tokens across requests: a healthy integration shows most of the context landing there after the first call, with cache_creation_input_tokens near zero until the TTL lapses. On apiToken.sale the same legs show up in your dashboard — every request is listed with model, provider and a token-level breakdown, and every cache line is visible in your usage detail, so the savings are auditable rather than implied.

Stacking the cache with the prepaid discount

Caching lowers the token count you pay full price for; the apiToken.sale discount lowers the price per token. They compound. Concrete math on Claude Sonnet 5 (official $2 per 1M input tokens): resending a 100,000-token context fresh costs $0.20 per call. Read from cache it costs $0.02, and after the flat 50% B2C discount the call's context leg lands at $0.01 — a 20× reduction on the part of the bill that used to dominate it.

Billing stays prepaid and simple: one balance covers supported Claude, GPT, Gemini and Kimi models, each metered at its official rate card before the discount. Top up once, and a well-cached workload stretches the same balance far further than uncached traffic.

Per-model input, output and cache rates →

Model a cached workload in the Claude API cost calculator →

Frequently asked questions

Related guides