Your prompt cache leaves its verdict on one screen

Prompt caching fails silently. I know because I broke one on purpose for this guide: twelve requests, each paying to re-write a 19,000-token prefix it should have been reading back, and not one of them raised an error. If that were your production traffic, the usual next move would be to instrument — log the usage block on every response, ship it, wait for enough data to tell you whether the cache is doing anything. You don’t have to. The Claude Console already collected those counters and drew them for you, on one page most people never open.

This guide reads that page. It is the Console companion to Prompt Caching Explained (the economics), How to Enable Prompt Caching (turning it on), and Why Your Prompt Cache Isn’t Working (the code-and-counters method, any provider). This one is Anthropic-only and about diagnosing by looking instead of instrumenting; where the mechanics or the math matter, it links back.

The screen is at platform.claude.com/usage/cache (Analytics → Caching in the Console). Everything below was observed there on July 8, 2026; the labels and numbers are dated because a vendor UI drifts, so re-check the tooltips against what you see.

One screen, three questions

Diagnosing a prompt cache reduces to three questions asked in order — did it read, did it pay, and, when a read broke, which segment changed (the troubleshooting guide derives them from the response counters). Each question has one home on this page.

• Did it read? The Cache read ratio tile and the Input token composition chart.
• Did it pay? The Write amort. column — short for write amortization — in the Cache usage breakdown table (and its own trend chart).
• Which segment broke? The Cache diagnostics area, backed by the Group by and Workspace controls.

The controls along the top — Workspace, Model, Range, and Group by — scope every panel beneath them. One caption deserves early suspicion: the “Data as of …” timestamp. Mine sat five days stale while the data underneath it was moving; the limits section covers why.

Did it read?

Start with the Cache read ratio tile — and define it precisely, because the denominator is not what you would guess. The dashboard computes it as cache-read tokens divided by cache-read plus uncached tokens; cache-write tokens are left out entirely. So it is not cache reads over total input; it is “of the input that wasn’t a fresh write, how much came from cache.” A number you compute with writes in the denominator will read lower than the tile for the same traffic. The tile’s own tooltip states it only loosely — “share of input tokens served from cache” — and never names the denominator, so it is worth spelling out here.

A stable prefix pushes the ratio toward 100 percent; a read-side failure — stored but never matched — collapses it toward zero. The Input token composition chart tells the same story as a picture: mostly green cache read band when it works, a stack of cache write bands with the read band absent when it doesn’t. The Cache usage breakdown table puts the models side by side.

Those two rows are mine. The test script sends the same large document — a chunk of Pride and Prejudice from Project Gutenberg — twelve times against each model. On one model it goes out as a byte-stable cached prefix. On the other, a fresh timestamp and UUID get prepended to the front of every request. The stable version read 99.9 percent of its non-write input from cache; the broken one read 0.0 percent and paid to re-write the whole prefix twelve times. If your own row looks like the second one, you have localized the problem to the read side, and the next question is which part of the request drifted. If it looks like the first, the cache is reading. Whether it is saving you anything is the next question.

Did it pay?

The Write amort. column of the breakdown table tracks reads-per-write reuse: cache-read tokens divided by cache-write tokens. On Claude a cache write is billed above the normal input rate, so a stored prefix only pays off once enough reads follow it before it expires. The multiplier tracks exactly that. Comfortably above one read per write, the reuse is paying the premium back. At or near one, it isn’t. And 0.00x, on a run that never reads, is the worst case: you paid to write the prefix and got nothing for it. In the contrast above, the working model sits at 11.0x — eleven reads for every write — against the broken model’s 0.00x.

This is why the read ratio alone is not enough. A workload can post a healthy read ratio and still lose money if the writes outnumber the reads that follow them — thin reuse, entries expiring between calls, or parallel calls that all write before any of them reads. That is an economics failure, not a broken cache, and the break-even math that decides it — the write premium, the read discount, the point where reuse starts paying — belongs to Prompt Caching Explained; this guide does not re-derive it. What the screen adds is the over-time view: dedicated Write amortization and Cache read ratio trend charts, each with its own Window selector. A read ratio that drifts down, or an amortization that sags toward one, is a regression starting to show.

Which segment broke?

When the read ratio has collapsed, you know a stored prefix stopped matching. The cache compares the leading prefix byte for byte and stops at the first token that differs, so the break lives in exactly one part of the request — the model, the system prompt, the tool definitions, or the earlier message history. Eyeballing two large requests for that one difference is miserable. The Cache diagnostics area does it for you.

Diagnostics is a separate opt-in beta, and it is API-driven — there is no Console toggle. Two additions to each request turn it on: the beta header, and the prior response’s id threaded in as previous_message_id (None on the first turn).

resp = client.beta.messages.create(
    model="claude-opus-4-8",
    system=[{"type": "text", "text": SYSTEM, "cache_control": {"type": "ephemeral"}}],
    messages=messages,
    diagnostics={"previous_message_id": prev_id},   # None on the first turn
    betas=["cache-diagnosis-2026-04-07"],
    max_tokens=1024,
)
prev_id = resp.id
# resp.diagnostics.cache_miss_reason.type -> "system_changed", "model_changed", ...

The API compares each request against its predecessor and returns a cache_miss_reason naming the first divergence; until diagnosed requests exist, the Console area reads “No diagnostics data yet.” The reasons map one-to-one onto the request segments, and each points at a fix that lives in the troubleshooting guide — the screen’s job is to point at the right one. (The evidence script has the full version, including the loop that threads prev_id across turns.)

cache_miss_reason	What changed	Fix
model_changed	a router or fallback picked another model	hold the model constant
system_changed	a per-request value in the system prompt	make the system prompt byte-stable
tools_changed	tools reordered, added, or serialized non-deterministically	send a fixed, sorted tool list
messages_changed	earlier history edited instead of appended	treat history as append-only
previous_message_not_found, unavailable	no comparison was produced	not a divergence — resend with the beta header, keep calls close in time

That is exactly what my broken run reported. Its only per-call change was the timestamp prepended to the system prompt, and all eleven diagnosed misses came back system_changed — roughly 224K tokens of prefix lost. (The first call shows no reason at all; there was nothing to compare it against yet.) Diagnostics answers “did my request change”; the read counter answers “did the cache hit.” Read together they separate a changed request from an entry that simply expired — the same distinction the troubleshooting guide draws.

The controls are diagnostic levers

Two of the filters along the top do more than narrow the view; they isolate specific read-side causes.

Group by Model catches a model_changed miss. The cache is per-model, so if a router, an A/B split, or a retry path quietly selected a different model than the one that wrote the entry, nothing matches. Grouping by model shows it directly: one model carries a healthy read ratio while another running the same workload sits near zero. Without the grouping you would be chasing that through logs.

The Workspace filter catches an isolation-boundary miss. Caches are scoped to an API key, workspace, and organization, so two calls made from different workspaces cannot reuse each other’s entries even when the bytes match perfectly. If reads look healthy under one workspace and vanish under another, the boundary, not the prefix, is the problem. (The same scoping is why diagnostics only compares requests made within one workspace.)

What the screen can’t tell you

Two limits keep this from being the whole story.

First, it is Claude only, though the boundary is narrower than it looks. Only the why-it-missed diagnosis is exclusive: the request-comparison Cache diagnostics, and the cache_miss_reason that names the segment that changed, run only on the Claude API. The read and write metrics are not — Amazon Bedrock publishes CacheReadInputTokens and CacheWriteInputTokens to CloudWatch (chartable over time, with per-interaction caching metrics in the console playground), and Google Vertex exports cached-token counts to Cloud Monitoring. What neither has is a purpose-built cache page like this one, so on those providers you build the read/write view yourself, or read the counters straight from each response’s usage object, with the portable method in the troubleshooting guide.

Second, it lags, and the caption lies about it. The page updates hourly, and the usage-based panels lag further than the diagnostics panels. When I ran the tests above, the diagnostics picked them up quickly — but the tiles, the breakdown, and the “Data as of” caption sat on a five-day-old snapshot for hours afterward. I assumed I had done something wrong. I hadn’t; the usage rollup simply had not run yet, and when it did, everything appeared at once. Don’t read the caption as freshness. The reliable signal that a run has landed is the model rows you expect appearing in the Cache usage breakdown table; until they do, you are looking at stale usage even if the diagnostics already moved.

Watching it over time

Every failure on this screen is silent — the request succeeds and only a number moves. A cache you repaired today can regress next month from a change that looks unrelated: a per-request field added to the system prompt, a tool reordered in a refactor, a debug timestamp left in after an incident. The only thing that catches them is a signal you are already watching.

On Claude, the read ratio and write amortization trend charts are that signal — check that cached-token share holds near the fraction you expect and that amortization stays above one. If you call several providers, those signals sit on a different screen for each provider, which is where pulling them into one place earns its keep; tracking AI costs across providers covers that, and CostCompass pulls usage from your connected providers into one running total so cached-token share and cost-per-request are visible when you look, instead of being reconstructed from a separate dashboard each.

Next steps

The Claude Console already ran the diagnosis for you; the skill is knowing which panel answers which question. Read the read ratio, then the write amortization, then the diagnostics, and every failure lands in one place: nothing reading (read-side), reading but not paying (economics-side), or a named segment that changed.

From here:

• Understand the economics behind the write amortization column. Prompt Caching Explained derives the write premium, read discount, and the break-even that decides whether a working cache actually saves.
• Diagnose caches in code, on any provider. Why Your Prompt Cache Isn’t Working is the portable method behind this screen, including the per-segment fixes for each cache_miss_reason.
• Revisit how you turned it on. How to Enable Prompt Caching has the exact per-provider markers and the verify-once procedure.
• Watch it across providers over time. Tracking AI costs across providers covers keeping cached-token share and cost-per-request in view so a regression shows up as a moving metric.