Claude Cache Reads vs Writes: A Practical Walkthrough

花钱这件事EN2026-10-25

Start with a controlled experiment: send a reusable document twice, changing only the question. Compare the usage counters and the cost of each request. This walkthrough separates cache creation from cache reuse, then shows how to decide whether caching fits your workload.

§ Step 1: Separate writes from reads

A cache write stores a processed prompt prefix for reuse. A cache read reuses a matching prefix on a later request. This is prompt caching, not answer caching: Claude still generates a response for each request. One request can contain both reads and writes when it reuses earlier context and caches additional material. ([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/prompt-caching))

For your test, choose one substantial reference document and two questions about it. Keep a simple record of the request time, model, usage counters, and billed amount.

§ Step 2: Put stable content first

Claude caching depends on an exact prefix match. Put reusable instructions, tool definitions, and reference material before changing questions. A modification near the beginning can invalidate reuse farther downstream. ([github.com](https://github.com/anthropics/skills/blob/main/skills/claude-api/shared/prompt-caching.md))

Keep stable: shared instructions, document text, and tool ordering.
Move later: timestamps, request identifiers, and changing questions.
Check serialization: avoid rebuilding equivalent content with different ordering or formatting.

These precautions follow directly from prefix matching. For the experiment, save the shared content once and reuse that exact representation rather than reconstructing it independently for each request. ([github.com](https://github.com/anthropics/skills/blob/main/skills/claude-api/shared/prompt-caching.md))

§ Step 3: Mark the reusable boundary

With Anthropic Messages, place cache_control on the final content block of your shared material, using type ephemeral. Put the changing question in a subsequent block. The marker covers the preceding prefix, not just the marked block. The prefix must also meet the selected model's minimum cacheable length. ([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/prompt-caching))

Vana API supports Anthropic Messages alongside its OpenAI-compatible endpoint and Gemini native protocol. For this test, prefer the Messages format so the intended cache boundary stays explicit. Before scaling up, verify that your chosen route preserves the cache controls and exposes the relevant usage fields.

§ Step 4: Verify the first write and second read

Send the first request, then send the second promptly with the same shared prefix. Inspect the Messages response usage:

cache_creation_input_tokens: tokens written into cache.
cache_read_input_tokens: tokens retrieved from cache.
input_tokens: ordinary input tokens outside those categories.

Add all three to measure total input. Do not interpret a small input_tokens value alone as a smaller overall prompt. ([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/prompt-caching))

If the second request shows no reads, compare the actual outgoing payloads before changing your implementation. Check the shared prefix, cache boundary, elapsed time, and minimum-length requirement. Treat a successful response as proof that inference worked, not proof that caching worked.

§ Step 5: Choose a lifetime and calculate savings

Claude's default cache lifetime is five minutes, refreshed on reuse. A one-hour lifetime is available by adding ttl with the value 1h to cache_control. Choose based on the expected gap between requests. ([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/prompt-caching))

Anthropic prices five-minute writes at 1.25 times ordinary input and one-hour writes at twice ordinary input. Read discounts vary by model. For Claude Sonnet 5.5, reads cost 0.05 times ordinary input. ([platform.claude.com](https://platform.claude.com/docs/en/about-claude/pricing))

Using those multipliers, one five-minute write followed by nine reads costs 1.70 ordinary-input equivalents for the shared prefix, versus 10 without caching: an 83% reduction for that prefix alone. This calculation excludes changing input and output. Use Vana API's actual rates for your bill rather than assuming Anthropic's retail prices apply. ([platform.claude.com](https://platform.claude.com/docs/en/about-claude/pricing))

§ Step 6: Repeat with realistic traffic

Test your normal request intervals and document changes before adopting caching broadly. Compare total spend across the complete run, including the initial write. Vana API bills per real token without a monthly fee, making a small pilot a practical starting point. Create a Vana API account to run the experiment with your own workload.