Claude Prompt Cache Warm: What It Means and How to Check Cache Hits

A search for “Claude prompt cache warm” usually leads to a practical question: will the next request reuse work already done? A warm cache holds a reusable prompt prefix. An actual cache hit means a particular request reused it. Anthropic describes prefix reuse in its prompt-caching documentation.

This guide is for developers checking the direct Claude API. It follows one small experiment from a first request to a repeat request, then explains what to investigate when the numbers disagree with your expectations.

What does a warm prompt cache mean?

“Warm” describes availability, not permanent memory or a saved answer. Caching reuses processing of matching input; Claude still generates a response. The cacheable prefix follows the order tools, system, then messages. You can use automatic caching or place explicit cache_control breakpoints. The official caching guide explains both approaches.

For your first experiment, write down two separate success criteria: “The second request reads cached tokens” and “The answer still satisfies the task.” Keep both in the test report. A performance optimisation deserves its own measurement, alongside your existing output-quality checks.

Choose a useful repeated task

Imagine a purchase-request assistant. Its reference material contains a fictional company's approval policy, exception rules and worked examples. Each new request asks which information is missing and which review route the policy describes. The policy stays fixed during the experiment; the purchase details change.

You can sketch the task using Purchase Approval Branches from Spending Threshold Notes. For this exercise, ask for a recommendation only. Use a human reviewer to compare each answer against the policy before considering any operational use.

Prepare a real reference document of useful length. Cache eligibility has a model-specific minimum; a short greeting may produce no cache activity even with a marker. Check the documented minimum for your model. Avoid padding the document solely to make a demonstration look successful.

Run two requests and print the usage

The following original Python example uses the official anthropic package. Set ANTHROPIC_API_KEY in your environment, set CLAUDE_MODEL to an available model ID, and save your reference document as reference-policy.txt. Run the script from that file's directory. The request and response structure follows the Messages API reference.

The explicit marker sits at the end of the stable system content. Both calls reuse that content; each supplies its own question. This is a controlled pair of independent questions, not a conversation-history implementation.

import os
from pathlib import Path
import anthropic

client = anthropic.Anthropic()
model = os.environ["CLAUDE_MODEL"]
reference = Path("reference-policy.txt").read_text(encoding="utf-8")
stable_context = "Use the policy below. Flag missing facts.\n\n" + reference

questions = [
    "A team requests an equipment purchase. Which facts are needed?",
    "The same purchase is urgent. Which exception checks are needed?",
]

for number, question in enumerate(questions, start=1):
    response = client.messages.create(
        model=model,
        max_tokens=256,
        system=[{
            "type": "text",
            "text": stable_context,
            "cache_control": {"type": "ephemeral"},
        }],
        messages=[{"role": "user", "content": question}],
    )
    print("Request", number, "response ID:", response.id)
    print(response.usage.model_dump_json(indent=2))

This example has been checked for Python syntax, but has not been run against a live account. Running it sends two billable requests. Its purpose is to expose your account's actual results; it does not promise a particular token count or response time.

Read the counters before judging the result

Inspect the response's usage object. The API response schema exposes separate counters for cache creation, cache reads, ordinary input and output.

Fields to record for each request

Field	Meaning
cache_creation_input_tokens	Input tokens written to cache.
cache_read_input_tokens	Input tokens retrieved from cache.
input_tokens	Input tokens outside those cache reads and writes.
output_tokens	Generated output tokens.

A positive read count demonstrates reuse. A positive write count alone demonstrates creation. Both can be positive when a request reuses one prefix and caches additional content. For total input, add reads, writes and ordinary input; do not treat input_tokens alone as the complete prompt size. These interpretations follow Anthropic's usage-accounting explanation.

The numbers below are invented teaching examples, not measured results. Assume one unchanged eligible prefix and one explicit breakpoint.

Illustrative request sequence

Request	Cache writes	Cache reads	Ordinary input	Reading of the example
A	8,000	0	45	The prefix was written.
B	0	8,000	52	The next question reused it.
C	8,000	0	48	No reuse is recorded; investigate why.

Request B contains 8,052 input tokens in total. Request C is deliberately ambiguous: a counter reports what happened, while the request comparison and timing help you investigate the cause. Record the model, policy version, request start time and response ID beside each row.

Troubleshoot a cache miss systematically

Compare the actual requests your application sends. Anthropic's cache-diagnostics guide identifies changes to models, system content, tools and earlier messages as useful places to investigate. The following checks adapt that guidance to the purchase-policy experiment.

Checks for the next debugging pass

What to inspect	Practical check
System content	Compare the policy text and surrounding instructions. Look for an inserted timestamp or request ID.
Model	Confirm both requests used the same model configuration.
Tools, if added later	Compare definitions and ordering, not just tool names.
Conversation history, if added later	Check whether earlier messages were edited, removed or reordered.

Change one variable per debugging pass. First preserve the original pair of requests. Then test your suspected correction and label the new pair clearly. This gives a teammate enough evidence to reproduce your reasoning without relying on a screenshot of a “warm” label.

For direct Claude API integrations, Anthropic also offers beta cache diagnostics that compare requests using a previous response ID. This comparison is separate from whether reuse actually occurred: read it alongside usage. Consult the diagnostics setup and limitations before enabling it; field semantics may change during beta.

Account for expiration and Claude Code

The API's default cache lifetime is five minutes; a one-hour option is available. Cache reads refresh the lifetime. A sufficiently long gap can leave nothing to reuse. Claude Code manages caching automatically and selects lifetimes according to request type and billing context, so do not assume every Claude Code turn uses the API default. See Claude Code's cache-lifetime documentation.

If your problem occurs after a lunch break, include that timing in the report. If it occurs on immediately repeated calls, start with the request comparison. In either case, keep a record of what you observed instead of describing every slow response as a cache failure.

Decide whether warming is worth the cost

Cache writes, cache reads and generated output have separate prices. Five-minute writes generally use a 1.25-times base-input multiplier; one-hour writes use 2 times. Read pricing depends on the model. Check the relevant row in Anthropic's pricing table rather than applying one savings percentage to every request.

Use this planning calculation for the repeated prefix only:

Without caching = N × P × B
With caching    = P × W + (N − 1) × P × R

N = number of useful requests sharing the prefix
P = prefix size in millions of tokens
B = base input price per million tokens
W = cache-write price per million tokens
R = cache-read price per million tokens

This original calculation assumes one write and successful reads thereafter. Add any extra warming requests, rewrites, uncached input and output to estimate the full workload. It is a comparison method, not a quoted bill or benchmark.

Start by measuring normal useful traffic. Consider a separate warming request only when you can explain which upcoming requests should benefit and how you will measure that benefit. Record total cost, observed waiting time and answer quality together.

Build a repeatable cache check

Keep a short experiment record: the reference version, two questions, model configuration, usage counters, elapsed times and the reviewer's assessment of the answers. Expand the test only after the basic pair is understandable.

For additional policy scenarios, adapt the approval-routing prompt collection. If you want to turn the experiment into a reusable local utility, use the coding prompts to help specify logging and comparison requirements. Preserve the original questions as regression examples so later prompt edits can be checked against the same task.