Prompt Caching Cost Guide: Cache Hits, Prefixes, and Real API Spend

Prompt caching cost depends on whether your second request starts with exactly the same content as your first, not on the headline discount. In our worked example, a 20,000-token system prompt on claude-sonnet-5 costs about $12.12 per 1,000 requests without caching and about $1.33 when every request after the first reads the cache. If the prefix changes on every call, the same traffic costs about $15.12, which is more than no caching at all.

The prices below were read from the TokenLab model API on 2026-10-24 (registry revision 2026-10-23). They change, so treat the arithmetic as a template and read the live price before you forecast.

Key Takeaways

How to turn caching on

This is from the billing guide and the Chat Completions reference, read 2026-10-24.

• Chat Completions, Claude models: send "anthropic_options": {"prompt_caching": true}. TokenLab marks the end of the system prompt and the latest user message as cache points. If any message already carries cache_control, TokenLab adds no cache points of its own.
• Messages API: add cache_control to the blocks yourself.
• Lifetime: the default is 5 minutes. Add "prompt_caching_ttl": "1h" for a 1-hour cache, which the billing guide prices at about 2 times input for the write. If the serving route does not support one hour, TokenLab uses five minutes and does not reject the request.
• Minimum size: a prompt shorter than the model's minimum (512 to 4,096 tokens for Claude, depending on the model) is not cached and has no cache write charge.
• GPT, Gemini and some other models: no setting. Long repeated prompts are cached automatically.

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "anthropic_options": { "prompt_caching": true },
  "messages": [
    { "role": "system", "content": "You are a support assistant. The following policy governs all responses: [Full Policy Text]" },
    { "role": "user", "content": "What is the return period for damaged items?" }
  ]
}

To see whether it worked, read usage.prompt_tokens_details.cached_tokens (tokens read from the cache) and usage.cache_creation_input_tokens (tokens written to it) in the response, then compare the charge in Usage.

A worked prompt caching cost example

Every input is stated so you can swap in your own numbers. These are our assumptions, not measurements.

• A 20,000-token system prompt and tool block, identical on every request.
• A 200-token user message that changes on each request.
• 1,000 requests, with the cache alive for the whole run: one write and 999 reads.
• Output tokens ignored, because they cost the same either way. Tool and search fees are also left out.

Prices for claude-sonnet-5, Verified delivery, per 1M tokens, read 2026-10-24: input $0.60, cache read $0.06, cache write (default 5 minutes) $0.75.

Scenario	Working	Total
No caching	1,000 × 20,200 = 20,200,000 tokens × $0.60/1M	$12.12
Caching, every later request hits	write 20,000 × $0.75/1M = $0.015; reads 999 × 20,000 = 19,980,000 × $0.06/1M = $1.1988; suffixes 200,000 × $0.60/1M = $0.12	$1.3338 (about 89% below no caching)
Caching, prefix changes every call	1,000 × 20,000 × $0.75/1M = $15.00 for writes, plus $0.12 for suffixes	$15.12 (about 25% above no caching)

The break-even follows from the same prices. Per 1M prefix tokens, a write costs $0.15 more than plain input, and each read saves $0.54. One read repays the write with room to spare ($0.15 ÷ $0.54 ≈ 0.28 reads per write).

Those prices are a snapshot. An earlier version of this guide, written on 2026-10-03 from a different registry revision, showed higher numbers for the same model (input $0.90). That was the price on that date, not a billing error; we replaced the old table instead of keeping two sets of figures. Other models have different ratios and some list no cache write price, so check the model before you reuse the ratios above. Live prices are on the TokenLab Models page and from curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5", which returns the cache read and write prices for that model.

Making a prompt cacheable

A read price only applies to the part of the prompt that matched, so the repeated material has to come first and be byte-identical.

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲
Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

Three habits break reuse most often:

• Timestamps, user IDs or session IDs at the top of a system prompt.
• Tool definitions or JSON keys reordered between requests.
• Indentation or newline changes in the shared text.

When prompt caching does not pay off

Workload pattern	Caching viability	Why
Multi-turn tool loops	High	Instructions and tool definitions stay fixed across steps.
Many users querying one large document	High	Bursts of traffic amortize the write quickly.
Infrequent background jobs	Low	Gaps wider than the cache lifetime force repeated writes.
Varying system prompts	Low	Changes ahead of the boundary break the match.

Prompt caching differs from the "Implement caching" tip in the billing guide, which means storing responses in your own app for repeated identical requests. For long agent sessions, the coding agent cost guide covers context size, output limits and model choice alongside caching.

FAQ

Does a cache hit always make a request cheaper?

Only for the matched prefix, and only if the model lists a cache read price. The suffix and all output tokens bill at normal rates. A miss on a model with a write premium can cost more than an uncached call.

Does a normal Claude request use the cache?

No. Claude models cache only when you ask, with anthropic_options.prompt_caching on Chat Completions or cache_control on the Messages API.

Is a missing cache write price the same as free?

No. A dash or a missing price means no listed offer, not free. Send one first request and read the charge in Usage rather than assuming zero or the input rate.

Where do per-user values go in a cacheable prompt?

After the shared content, in the user message or a late messages entry. Anything that varies before the shared block changes the prefix and forces a new write.

Why would a repeated request show no cached tokens?

Check in order: is caching turned on for a Claude model, is the prompt above the model's minimum size, is the prefix byte-identical between calls, and did the second call arrive inside the cache lifetime. Then read usage.prompt_tokens_details.cached_tokens and usage.cache_creation_input_tokens in the response.