Claude Launches Prompt Cache Diagnostics: No More Guessing Why Your Token Costs Skyrocketed

By winkrun, May 19, 2026

Earlier this month, I wrote about how to cut Claude Code token usage by up to 49x with 10 open source tools — and today, Anthropic just dropped a game-changing native tool for anyone struggling with unexpected Claude API costs.

Claude has officially announced that Prompt Cache Diagnostics is now live in the Claude Console.

The core value of this new feature solves one of the most frustrating pain points of working with Claude prompt caching: debugging cache misses. Previously, when a request failed to hit your cache, all developers would see was cache_read_input_tokens drop to zero — with zero context about which part of the prompt changed to break the cache. Now, after a cache miss, you get a direct breakdown of exactly what changed, and how many tokens that cache miss ended up costing you.

You can check out the feature in the Claude Console’s usage cache dashboard here: https://platform.claude.com/usage/cache, and find the full official documentation here: https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics

Background: Why Does This Feature Matter?

For context, let’s start with a quick breakdown of what prompt caching does for anyone new to Claude: it’s Anthropic’s core feature for cutting API costs and reducing response latency. If two consecutive requests have an identical prompt prefix (we’re talking byte-for-byte matching here), you can reuse the cached prefix. You won’t get charged twice for those cached tokens, and responses load much faster.

The catch? That matching rule is extremely strict. Even a tiny change — an auto-injected timestamp in your system prompt, a reordered tool list, an extra space in your message history — is enough to break the entire cache. Before this update, there was zero official tooling to debug this. When developers suddenly saw their token costs skyrocket out of nowhere, they were stuck manually comparing prompts line by line. It was an incredibly slow, inefficient process.

How To Use Prompt Cache Diagnostics (For Developers)

Right now, the feature is in open beta. To use it, you need to add the beta header cache-diagnosis-2026-04-07 to your Claude API calls, and pass the previous_message_id returned from your last response in your request parameters. The API will automatically compare the structure of the two requests, and return the cause of the cache miss in the diagnostics field of the response.

The full workflow looks like this: you carry the beta header on every conversation turn. For your first request, you pass previous_message_id: null to opt into the feature. On every subsequent turn, you pass the ID from the previous response, and the API will compare the two requests and return the first point of divergence it finds.

Below is the basic Python example from Anthropic’s official documentation:

client = anthropic.Anthropic()  

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"  

# Turn 1: opt in with previous_message_id=None  
r1 = client.beta.messages.create(  
    model="claude-opus-4-7",  
    max_tokens=1024,  
    cache_control={"type": "ephemeral"},  
    system=SYSTEM,  
    messages=[{"role": "user", "content": "Summarize section 1."}],  
    diagnostics={"previous_message_id": None},  
    betas=["cache-diagnosis-2026-04-07"],  
)  

# Turn 2: reference the previous response id  
r2 = client.beta.messages.create(  
    model="claude-opus-4-7",  
    max_tokens=1024,  
    cache_control={"type": "ephemeral"},  
    system=SYSTEM,  
    messages=[  
        {"role": "user", "content": "Summarize section 1."},  
        {"role": "assistant", "content": r1.content},  
        {"role": "user", "content": "Now summarize section 2."},  
    ],  
    diagnostics={"previous_message_id": r1.id},  
    betas=["cache-diagnosis-2026-04-07"],  
)  

diagnostics = r2.diagnostics  
if diagnostics is None:  
    print("No divergence detected.")  
elif diagnostics.cache_miss_reason is None:  
    print("Comparison still pending.")  
else:  
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

If you use streaming responses, the diagnostics data will be included in the message_start event. Here's a streaming example:

# Turn 2: stream, referencing the previous response id  
with client.beta.messages.stream(  
    model="claude-opus-4-7",  
    max_tokens=1024,  
    cache_control={"type": "ephemeral"},  
    system=SYSTEM,  
    messages=[  
        {"role": "user", "content": "Summarize section 1."},  
        {"role": "assistant", "content": r1.content},  
        {"role": "user", "content": "Now summarize section 2."},  
    ],  
    diagnostics={"previous_message_id": r1.id},  
    betas=["cache-diagnosis-2026-04-07"],  
) as stream:  
    for text in stream.text_stream:  
        print(text, end="", flush=True)  
    print()  
    r2 = stream.get_final_message()  

diagnostics = r2.diagnostics  
if diagnostics is None:  
    print("No divergence detected.")  
elif diagnostics.cache_miss_reason is None:  
    print("Comparison still pending.")  
else:  
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

Currently, the tool can detect these common cache miss causes:

• Model change: The model called in the two requests doesn’t match, usually caused by routing, A/B testing, or model fallback logic switching models mid-conversation
• System prompt change: The content of your system prompt changed, usually from dynamic injected content like timestamps or request IDs
• Tool list change: Tools were added/removed/reordered, or the JSON serialization format for tool parameters changed
• Message history change: Content or order of the message list changed, for example from truncating history or re-serializing assistant responses

The response also includes an estimated count of how many tokens were lost to the cache miss, so developers can easily assess the cost impact. Here’s a sample response structure with a cache miss diagnosis:

{  
  "id": "msg_01Xyz...",  
  "type": "message",  
  "role": "assistant",  
  "content": [{ "type": "text", "text": "..." }],  
  "usage": {  
    "input_tokens": 42,  
    "cache_read_input_tokens": 0,  
    "cache_creation_input_tokens": 41850,  
    "output_tokens": 210  
  },  
  "diagnostics": {  
    "cache_miss_reason": {  
      "type": "system_changed",  
      "cache_missed_input_tokens": 41850  
    }  
  }  
}

You can combine the diagnostics result with your actual cache hit rate to debug issues systematically:

| Diagnosis Result | Cache Read Token Count | Conclusion | | — -| — -| — -| | null | High | Everything working as expected: your prefix is stable and caching properly | | null | Low or Zero | Your request structure didn’t change, but the cache expired. Shorten your request interval to fix this. | | Has *_changed result | Low or Zero | A structural change caused the cache miss. Fix the change at the reported location. | | Has *_changed result | High | The change happened at a late position in the prompt, and your earlier prefix still hits cache. Lower priority to fix. |

Current Limitations

1. This feature only works with native Claude API right now. It doesn’t support Claude hosted on Amazon Bedrock or Google Vertex AI.
2. Request fingerprints used for comparison have a limited retention window. Comparisons only work for requests within the same organization and workspace.
3. Deep divergences in extremely long conversations may not be identified accurately, and will return an unavailable status.
4. The diagnostic feature is provided on a best-effort basis, and will never block your normal requests. If diagnostics can’t be generated, it will just return the corresponding status code.

It’s also worth noting the privacy policy here: The feature complies with zero data retention standards. Anthropic does not store your raw prompt or response content. They only store request fingerprints made up of hashes and estimated token counts, and these fingerprints expire and get deleted after a short period.

What Developers Are Saying

The announcement sparked a ton of discussion among AI practitioners, with very different perspectives from different user groups.

Many developers building production-grade AI apps gave the feature extremely high praise, calling it one of the most useful updates Claude has shipped recently. Before this launch, running a cached prompt in production was basically “flying blind” — you had no idea when your cache hit rate would drop out of nowhere. Being able to see exactly what changed is massive for cost optimization.

One developer joked that we can finally see exactly where all our tokens are getting “burned”.

Other developers have already pushed for further improvements: if we can already identify why the cache missed, why not automatically handle compatibility and reuse cache for the unchanged portions of the prompt?

Regardless of the reception, this is a clear response from Anthropic to developer demand for more transparency around token usage. It’s a great win for developers who want to use Claude without hidden unexpected costs.