Repository Public
1---2title: Cache diagnostics3url: https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics4description: Diagnose unexpected prompt cache misses by comparing consecutive requests and identifying exactly where the prompt prefix diverged.5---67## Compatibility8- Status: Beta9- [Beta header](https://platform.claude.com/docs/en/api/beta-headers): `cache-diagnosis-2026-04-07`10- [ZDR](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention): eligible (excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements))11- Platforms: Claude API (beta); not available on Claude Platform on AWS, Amazon Bedrock, Google Cloud, Microsoft Foundry1213[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) cuts latency and cost significantly, but only when the beginning of your prompt is byte-for-byte identical to a recent request. A reordered tool, a timestamp interpolated into your system prompt, or an edit to an earlier message can silently invalidate the cache. Without cache diagnostics, the only signal is `usage.cache_read_input_tokens` dropping to zero, with no indication of what changed.1415Cache diagnostics closes that gap. Pass the `id` of your previous response, and the API compares the two requests and tells you where they diverged (the model, the system prompt, the tools, or the message history) so you can fix the root cause instead of guessing.1617## How cache diagnostics works1819When the beta header is present, the API stores a lightweight fingerprint of each request, keyed by the response `id`. On your next request, include that `id` as `diagnostics.previous_message_id`. The API rebuilds the fingerprint for the new request, compares it against the stored one, and attaches a `diagnostics` object to the response describing the first point of divergence.2021The comparison is about request structure, independent of whether the cache actually hit. See [Reading diagnostics alongside usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#reading-diagnostics-alongside-usage) for how to combine the `diagnostics` result with `usage.cache_read_input_tokens`.2223Fingerprints contain only hashes and token-count estimates (never raw prompt content), are retained for a limited time, are scoped to your organization and workspace, and are not used for any other purpose.2425## Basic usage2627Send the beta header on every turn. On the first turn, pass `"previous_message_id": null` to opt in without a prior message to compare against. On subsequent turns, pass the `id` from the previous response.2829<CodeGroup>30 ```bash cURL31 # Turn 1: establish the cache and opt in to diagnostics32 response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/messages \33 -H "x-api-key: $ANTHROPIC_API_KEY" \34 -H "anthropic-version: 2023-06-01" \35 -H "anthropic-beta: cache-diagnosis-2026-04-07" \36 -H "content-type: application/json" \37 -d '{38 "model": "claude-opus-5",39 "max_tokens": 1024,40 "cache_control": {"type": "ephemeral"},41 "system": "You are an AI assistant analyzing a large document. <document>...</document>",42 "messages": [{"role": "user", "content": "Summarize section 1."}],43 "diagnostics": {"previous_message_id": null}44 }')45 jq '{id, diagnostics}' <<< "$response"46 message_id=$(jq -r '.id' <<< "$response")4748 # Turn 2: reference the previous turn so the API can compare prefixes49 curl -sS --fail-with-body https://api.anthropic.com/v1/messages \50 -H "x-api-key: $ANTHROPIC_API_KEY" \51 -H "anthropic-version: 2023-06-01" \52 -H "anthropic-beta: cache-diagnosis-2026-04-07" \53 -H "content-type: application/json" \54 -d @- <<EOF | jq '{id, diagnostics}' # diagnostics: null means no divergence was found55 {56 "model": "claude-opus-5",57 "max_tokens": 1024,58 "cache_control": {"type": "ephemeral"},59 "system": "You are an AI assistant analyzing a large document. <document>...</document>",60 "messages": [61 {"role": "user", "content": "Summarize section 1."},62 {"role": "assistant", "content": "Section 1 covers..."},63 {"role": "user", "content": "Now summarize section 2."}64 ],65 "diagnostics": {"previous_message_id": "$message_id"}66 }67 EOF68 ```6970 ```bash CLI71 # Turn 172 turn1=$(ant beta:messages create \73 --beta cache-diagnosis-2026-04-07 \74 --transform '{id,usage,diagnostics}' <<'YAML'75 model: claude-opus-576 max_tokens: 102477 cache_control:78 type: ephemeral79 system: "You are an AI assistant analyzing a large document. <document>...</document>"80 messages:81 - role: user82 content: Summarize section 1.83 diagnostics:84 previous_message_id: null85 YAML86 )87 printf '%s\n' "$turn1"8889 # Turn 2: pass the id from turn 1 as previous_message_id90 message_id=$(jq -r '.id' <<<"$turn1")91 ant beta:messages create \92 --beta cache-diagnosis-2026-04-07 \93 --transform '{id,usage,diagnostics}' <<YAML94 model: claude-opus-595 max_tokens: 102496 cache_control:97 type: ephemeral98 system: "You are an AI assistant analyzing a large document. <document>...</document>"99 messages:100 - role: user101 content: Summarize section 1.102 - role: assistant103 content: Section 1 covers...104 - role: user105 content: Now summarize section 2.106 diagnostics:107 previous_message_id: $message_id108 YAML109 ```110111 ```python Python112 client = anthropic.Anthropic()113114 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"115116 # Turn 1: opt in with previous_message_id=None117 r1 = client.beta.messages.create(118 model="claude-opus-5",119 max_tokens=1024,120 cache_control={"type": "ephemeral"},121 system=SYSTEM,122 messages=[{"role": "user", "content": "Summarize section 1."}],123 diagnostics={"previous_message_id": None},124 betas=["cache-diagnosis-2026-04-07"],125 )126127 # Turn 2: reference the previous response id128 r2 = client.beta.messages.create(129 model="claude-opus-5",130 max_tokens=1024,131 cache_control={"type": "ephemeral"},132 system=SYSTEM,133 messages=[134 {"role": "user", "content": "Summarize section 1."},135 {"role": "assistant", "content": r1.content},136 {"role": "user", "content": "Now summarize section 2."},137 ],138 diagnostics={"previous_message_id": r1.id},139 betas=["cache-diagnosis-2026-04-07"],140 )141142 diagnostics = r2.diagnostics143 if diagnostics is None:144 print("No divergence detected.")145 elif diagnostics.cache_miss_reason is None:146 print("Comparison still pending.")147 else:148 print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")149 ```150151 ```typescript TypeScript152 const client = new Anthropic();153154 const SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>";155156 // Turn 1: opt in with previous_message_id: null157 const r1 = await client.beta.messages.create({158 model: "claude-opus-5",159 max_tokens: 1024,160 cache_control: { type: "ephemeral" },161 system: SYSTEM,162 messages: [{ role: "user", content: "Summarize section 1." }],163 diagnostics: { previous_message_id: null },164 betas: ["cache-diagnosis-2026-04-07"]165 });166167 // Turn 2: reference the previous response id168 const r2 = await client.beta.messages.create({169 model: "claude-opus-5",170 max_tokens: 1024,171 cache_control: { type: "ephemeral" },172 system: SYSTEM,173 messages: [174 { role: "user", content: "Summarize section 1." },175 { role: "assistant", content: r1.content },176 { role: "user", content: "Now summarize section 2." }177 ],178 diagnostics: { previous_message_id: r1.id },179 betas: ["cache-diagnosis-2026-04-07"]180 });181182 if (r2.diagnostics === null) {183 console.log("No divergence detected.");184 } else if (r2.diagnostics.cache_miss_reason === null) {185 console.log("Comparison still pending.");186 } else {187 console.log(`cache_miss_reason: ${r2.diagnostics.cache_miss_reason.type}`);188 }189 ```190191 ```csharp C#192 AnthropicClient client = new();193194 var system = "You are an AI assistant analyzing a large document. <document>...</document>";195196 var r1 = await client.Beta.Messages.Create(197 new()198 {199 Model = Messages::Model.ClaudeOpus5,200 MaxTokens = 1024,201 CacheControl = new(),202 System = system,203 Messages =204 [205 new() { Role = Role.User, Content = "Summarize section 1." },206 ],207 Diagnostics = new() { PreviousMessageID = null },208 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],209 }210 );211212 var r2 = await client.Beta.Messages.Create(213 new()214 {215 Model = Messages::Model.ClaudeOpus5,216 MaxTokens = 1024,217 CacheControl = new(),218 System = system,219 Messages =220 [221 new() { Role = Role.User, Content = "Summarize section 1." },222 new()223 {224 Role = Role.Assistant,225 Content = r1.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),226 },227 new() { Role = Role.User, Content = "Now summarize section 2." },228 ],229 Diagnostics = new() { PreviousMessageID = r1.ID },230 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],231 }232 );233234 Console.WriteLine(r2.Diagnostics switch235 {236 null => "No divergence detected.",237 { CacheMissReason: null } => "Comparison still pending.",238 { CacheMissReason.Type: var type } => $"cache_miss_reason: {type.GetString()}",239 });240 ```241242 ```go Go243 client := anthropic.NewClient()244 ctx := context.Background()245246 system := []anthropic.BetaTextBlockParam{247 {Text: "You are an AI assistant analyzing a large document. <document>...</document>"},248 }249250 r1, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{251 Model: anthropic.ModelClaudeOpus5,252 MaxTokens: 1024,253 CacheControl: anthropic.BetaCacheControlEphemeralParam{},254 System: system,255 Messages: []anthropic.BetaMessageParam{256 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize section 1.")),257 },258 Diagnostics: anthropic.BetaDiagnosticsParam{259 PreviousMessageID: param.Null[string](),260 },261 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},262 })263 if err != nil {264 panic(err)265 }266267 r2, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{268 Model: anthropic.ModelClaudeOpus5,269 MaxTokens: 1024,270 CacheControl: anthropic.BetaCacheControlEphemeralParam{},271 System: system,272 Messages: []anthropic.BetaMessageParam{273 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize section 1.")),274 r1.ToParam(),275 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now summarize section 2.")),276 },277 Diagnostics: anthropic.BetaDiagnosticsParam{278 PreviousMessageID: anthropic.String(r1.ID),279 },280 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},281 })282 if err != nil {283 panic(err)284 }285286 switch {287 case !r2.JSON.Diagnostics.Valid():288 fmt.Println("No divergence detected.")289 case !r2.Diagnostics.JSON.CacheMissReason.Valid():290 fmt.Println("Comparison still pending.")291 default:292 fmt.Printf("cache_miss_reason: %s\n", r2.Diagnostics.CacheMissReason.Type)293 }294 ```295296 ```java Java297 var client = AnthropicOkHttpClient.fromEnv();298299 var system = "You are an AI assistant analyzing a large document. <document>...</document>";300301 var r1 = client.beta().messages().create(302 MessageCreateParams.builder()303 .model(Model.CLAUDE_OPUS_5)304 .maxTokens(1024)305 .cacheControl(BetaCacheControlEphemeral.builder().build())306 .system(system)307 .addUserMessage("Summarize section 1.")308 // Pass null on the first turn to opt in without a prior message to compare.309 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId((String) null).build())310 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)311 .build()312 );313314 var r2 = client.beta().messages().create(315 MessageCreateParams.builder()316 .model(Model.CLAUDE_OPUS_5)317 .maxTokens(1024)318 .cacheControl(BetaCacheControlEphemeral.builder().build())319 .system(system)320 .addUserMessage("Summarize section 1.")321 .addMessage(r1)322 .addUserMessage("Now summarize section 2.")323 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())324 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)325 .build()326 );327328 if (r2.diagnostics().isEmpty()) {329 IO.println("No divergence detected.");330 } else if (r2.diagnostics().get().cacheMissReason().isEmpty()) {331 IO.println("Comparison still pending.");332 } else {333 var reason = r2.diagnostics().get().cacheMissReason().get();334 // CacheMissReason doesn't expose a typed .type() accessor; read it from the raw JSON.335 @SuppressWarnings("unchecked")336 var json = (Map<String, JsonValue>) reason._json().orElseThrow().asObject().orElseThrow();337 IO.println("cache_miss_reason: " + json.get("type").asStringOrThrow());338 }339 ```340341 ```php PHP342 $client = new Client();343344 $system = 'You are an AI assistant analyzing a large document. <document>...</document>';345346 $r1 = $client->beta->messages->create(347 model: Model::CLAUDE_OPUS_5,348 maxTokens: 1024,349 cacheControl: new BetaCacheControlEphemeral,350 system: $system,351 messages: [352 ['role' => 'user', 'content' => 'Summarize section 1.'],353 ],354 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID(null),355 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],356 );357358 $r2 = $client->beta->messages->create(359 model: Model::CLAUDE_OPUS_5,360 maxTokens: 1024,361 cacheControl: new BetaCacheControlEphemeral,362 system: $system,363 messages: [364 ['role' => 'user', 'content' => 'Summarize section 1.'],365 ['role' => 'assistant', 'content' => $r1->content],366 ['role' => 'user', 'content' => 'Now summarize section 2.'],367 ],368 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($r1->id),369 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],370 );371372 echo match (true) {373 $r2->diagnostics === null => "No divergence detected.\n",374 $r2->diagnostics->cacheMissReason === null => "Comparison still pending.\n",375 default => "cache_miss_reason: {$r2->diagnostics->cacheMissReason->type}\n",376 };377 ```378379 ```ruby Ruby380 client = Anthropic::Client.new381382 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"383384 r1 = client.beta.messages.create(385 model: :"claude-opus-5",386 max_tokens: 1024,387 cache_control: {type: "ephemeral"},388 system_: SYSTEM,389 messages: [390 {role: "user", content: "Summarize section 1."}391 ],392 diagnostics: {previous_message_id: nil},393 betas: ["cache-diagnosis-2026-04-07"]394 )395396 r2 = client.beta.messages.create(397 model: :"claude-opus-5",398 max_tokens: 1024,399 cache_control: {type: "ephemeral"},400 system_: SYSTEM,401 messages: [402 {role: "user", content: "Summarize section 1."},403 {role: "assistant", content: r1.content},404 {role: "user", content: "Now summarize section 2."}405 ],406 diagnostics: {previous_message_id: r1.id},407 betas: ["cache-diagnosis-2026-04-07"]408 )409410 case r2.diagnostics411 in nil412 puts "No divergence detected."413 in {cache_miss_reason: nil}414 puts "Comparison still pending."415 in {cache_miss_reason: {type:}}416 puts "cache_miss_reason: #{type}"417 end418 ```419</CodeGroup>420421## Streaming422423In streaming responses, `diagnostics` appears on the `message_start` event.424425<CodeGroup>426 ```bash cURL427 # Turn 2: stream the response. diagnostics arrives on the message_start event;428 # a null value means no divergence was found.429 curl -sS --fail-with-body https://api.anthropic.com/v1/messages \430 -H "x-api-key: $ANTHROPIC_API_KEY" \431 -H "anthropic-version: 2023-06-01" \432 -H "anthropic-beta: cache-diagnosis-2026-04-07" \433 -H "content-type: application/json" \434 -d @- <<EOF | jq -R 'select(startswith("data: ")) | ltrimstr("data: ") | fromjson | select(.type == "message_start") | .message.diagnostics'435 {436 "model": "claude-opus-5",437 "max_tokens": 1024,438 "stream": true,439 "cache_control": {"type": "ephemeral"},440 "system": "You are an AI assistant analyzing a large document. <document>...</document>",441 "messages": [442 {"role": "user", "content": "Summarize section 1."},443 {"role": "assistant", "content": "Section 1 covers..."},444 {"role": "user", "content": "Now summarize section 2."}445 ],446 "diagnostics": {"previous_message_id": "$message_id"}447 }448 EOF449 ```450451 ```bash CLI452 # Turn 2: stream. With --stream the CLI emits each SSE event as one JSON object.453 # diagnostics arrives on the message_start event; pick it out with jq.454 ant beta:messages create \455 --beta cache-diagnosis-2026-04-07 \456 --stream --format jsonl <<YAML |457 model: claude-opus-5458 max_tokens: 1024459 cache_control:460 type: ephemeral461 system: "You are an AI assistant analyzing a large document. <document>...</document>"462 messages:463 - role: user464 content: Summarize section 1.465 - role: assistant466 content: Section 1 covers...467 - role: user468 content: Now summarize section 2.469 diagnostics:470 previous_message_id: $message_id471 YAML472 jq -c 'select(.type == "message_start") | .message | {id,usage,diagnostics}'473 ```474475 ```python Python476 # Turn 2: stream, referencing the previous response id477 with client.beta.messages.stream(478 model="claude-opus-5",479 max_tokens=1024,480 cache_control={"type": "ephemeral"},481 system=SYSTEM,482 messages=[483 {"role": "user", "content": "Summarize section 1."},484 {"role": "assistant", "content": r1.content},485 {"role": "user", "content": "Now summarize section 2."},486 ],487 diagnostics={"previous_message_id": r1.id},488 betas=["cache-diagnosis-2026-04-07"],489 ) as stream:490 for text in stream.text_stream:491 print(text, end="", flush=True)492 print()493 r2 = stream.get_final_message()494495 diagnostics = r2.diagnostics496 if diagnostics is None:497 print("No divergence detected.")498 elif diagnostics.cache_miss_reason is None:499 print("Comparison still pending.")500 else:501 print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")502 ```503504 ```typescript TypeScript505 const stream = client.beta.messages.stream({506 model: "claude-opus-5",507 max_tokens: 1024,508 cache_control: { type: "ephemeral" },509 system: SYSTEM,510 messages: [511 { role: "user", content: "Summarize section 1." },512 { role: "assistant", content: r1.content },513 { role: "user", content: "Now summarize section 2." }514 ],515 diagnostics: { previous_message_id: r1.id },516 betas: ["cache-diagnosis-2026-04-07"]517 });518519 for await (const event of stream) {520 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {521 process.stdout.write(event.delta.text);522 }523 }524 process.stdout.write("\n");525526 // diagnostics arrives on message_start and is carried through to the final message527 const r2 = await stream.finalMessage();528529 if (r2.diagnostics === null) {530 console.log("No divergence detected.");531 } else if (r2.diagnostics.cache_miss_reason === null) {532 console.log("Comparison still pending.");533 } else {534 console.log(`cache_miss_reason: ${r2.diagnostics.cache_miss_reason.type}`);535 }536 ```537538 ```csharp C#539 // Turn 2: stream, referencing the previous response id540 BetaDiagnostics? diagnostics = null;541542 var stream = client.Beta.Messages.CreateStreaming(543 new()544 {545 Model = Messages::Model.ClaudeOpus5,546 MaxTokens = 1024,547 CacheControl = new(),548 System = system,549 Messages =550 [551 new() { Role = Role.User, Content = "Summarize section 1." },552 new()553 {554 Role = Role.Assistant,555 Content = r1.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),556 },557 new() { Role = Role.User, Content = "Now summarize section 2." },558 ],559 Diagnostics = new() { PreviousMessageID = r1.ID },560 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],561 }562 );563564 await foreach (var streamEvent in stream)565 {566 if (streamEvent.TryPickStart(out var start))567 {568 // diagnostics arrives on the message_start event569 diagnostics = start.Message.Diagnostics;570 }571 else if (streamEvent.TryPickContentBlockDelta(out var delta) && delta.Delta.TryPickText(out var textDelta))572 {573 Console.Write(textDelta.Text);574 }575 }576 Console.WriteLine();577578 Console.WriteLine(diagnostics switch579 {580 null => "No divergence detected.",581 { CacheMissReason: null } => "Comparison still pending.",582 { CacheMissReason.Type: var type } => $"cache_miss_reason: {type.GetString()}",583 });584 ```585586 ```go Go587 // Turn 2: stream, referencing the previous response id588 stream := client.Beta.Messages.NewStreaming(ctx, anthropic.BetaMessageNewParams{589 Model: anthropic.ModelClaudeOpus5,590 MaxTokens: 1024,591 CacheControl: anthropic.BetaCacheControlEphemeralParam{},592 System: system,593 Messages: []anthropic.BetaMessageParam{594 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize section 1.")),595 r1.ToParam(),596 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now summarize section 2.")),597 },598 Diagnostics: anthropic.BetaDiagnosticsParam{599 PreviousMessageID: anthropic.String(r1.ID),600 },601 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},602 })603 defer stream.Close()604605 // diagnostics arrives on message_start; Accumulate carries it into r2606 var r2 anthropic.BetaMessage607 for stream.Next() {608 if err := r2.Accumulate(stream.Current()); err != nil {609 panic(err)610 }611 }612 if err := stream.Err(); err != nil {613 panic(err)614 }615616 switch {617 case !r2.JSON.Diagnostics.Valid():618 fmt.Println("No divergence detected.")619 case !r2.Diagnostics.JSON.CacheMissReason.Valid():620 fmt.Println("Comparison still pending.")621 default:622 fmt.Printf("cache_miss_reason: %s\n", r2.Diagnostics.CacheMissReason.Type)623 }624 ```625626 ```java Java627 // Turn 2: stream, referencing the previous response id628 var params = MessageCreateParams.builder()629 .model(Model.CLAUDE_OPUS_5)630 .maxTokens(1024)631 .cacheControl(BetaCacheControlEphemeral.builder().build())632 .system(system)633 .addUserMessage("Summarize section 1.")634 .addMessage(r1)635 .addUserMessage("Now summarize section 2.")636 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())637 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)638 .build();639640 var accumulator = BetaMessageAccumulator.create();641 try (var streamResponse = client.beta().messages().createStreaming(params)) {642 streamResponse.stream()643 .peek(accumulator::accumulate)644 .flatMap(event -> event.contentBlockDelta().stream())645 .flatMap(deltaEvent -> deltaEvent.delta().text().stream())646 .forEach(textDelta -> IO.print(textDelta.text()));647 IO.println("");648 }649650 // diagnostics arrives on message_start and is carried through to the accumulated message651 var diagnostics = accumulator.message().diagnostics();652 if (diagnostics.isEmpty()) {653 IO.println("No divergence detected.");654 } else if (diagnostics.get().cacheMissReason().isEmpty()) {655 IO.println("Comparison still pending.");656 } else {657 var reason = diagnostics.get().cacheMissReason().get();658 // CacheMissReason doesn't expose a typed .type() accessor; read it from the raw JSON.659 @SuppressWarnings("unchecked")660 var json = (Map<String, JsonValue>) reason._json().orElseThrow().asObject().orElseThrow();661 IO.println("cache_miss_reason: " + json.get("type").asStringOrThrow());662 }663 ```664665 ```php PHP666 // Turn 2: stream, referencing the previous response id667 $stream = $client->beta->messages->createStream(668 model: Model::CLAUDE_OPUS_5,669 maxTokens: 1024,670 cacheControl: new BetaCacheControlEphemeral,671 system: $system,672 messages: [673 ['role' => 'user', 'content' => 'Summarize section 1.'],674 ['role' => 'assistant', 'content' => $r1->content],675 ['role' => 'user', 'content' => 'Now summarize section 2.'],676 ],677 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($r1->id),678 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],679 );680681 $diagnostics = null;682 foreach ($stream as $event) {683 switch (true) {684 case $event instanceof \Anthropic\Beta\Messages\BetaRawMessageStartEvent:685 // diagnostics arrives on the message_start event's embedded BetaMessage686 $diagnostics = $event->message->diagnostics;687 break;688 case $event instanceof \Anthropic\Beta\Messages\BetaRawContentBlockDeltaEvent:689 if ($event->delta instanceof \Anthropic\Beta\Messages\BetaTextDelta) {690 echo $event->delta->text;691 }692 break;693 }694 }695 echo PHP_EOL;696697 echo match (true) {698 $diagnostics === null => "No divergence detected.\n",699 $diagnostics->cacheMissReason === null => "Comparison still pending.\n",700 default => "cache_miss_reason: {$diagnostics->cacheMissReason->type}\n",701 };702 ```703704 ```ruby Ruby705 # Turn 2: stream, referencing the previous response id706 stream = client.beta.messages.stream(707 model: :"claude-opus-5",708 max_tokens: 1024,709 cache_control: {type: "ephemeral"},710 system_: SYSTEM,711 messages: [712 {role: "user", content: "Summarize section 1."},713 {role: "assistant", content: r1.content},714 {role: "user", content: "Now summarize section 2."}715 ],716 diagnostics: {previous_message_id: r1.id},717 betas: ["cache-diagnosis-2026-04-07"]718 )719720 stream.each do |event|721 print(event.text) if event.is_a?(Anthropic::Streaming::TextEvent)722 end723 puts724725 # diagnostics arrives on message_start and is retained on the accumulated message726 r2 = stream.accumulated_message727728 case r2.diagnostics729 in nil730 puts "No divergence detected."731 in {cache_miss_reason: nil}732 puts "Comparison still pending."733 in {cache_miss_reason: {type:}}734 puts "cache_miss_reason: #{type}"735 end736 ```737</CodeGroup>738739The `message_start` event carries the full `diagnostics` field; see [Response format](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#response-format) for the possible values.740741## Threading diagnostics through a conversation loop742743In a multi-turn conversation, carry the latest response `id` forward as `previous_message_id` on every turn. The first iteration passes `null` to opt in; each subsequent iteration passes the `id` from the previous response.744745<Tabs>746 <Tab title="cURL">747 <Info>748 This workflow doesn't translate well to a one-off shell command. See the SDK tabs for the loop pattern; the per-turn HTTP request is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).749 </Info>750 </Tab>751752 <Tab title="CLI">753 <Info>754 This workflow doesn't translate well to a one-off shell command. See the SDK tabs for the loop pattern; the per-turn CLI invocation is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).755 </Info>756 </Tab>757758 <Tab title="Python">759 ```python760 client = anthropic.Anthropic()761762 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"763764 messages = []765 prev_id = None766767 for i, user_message in enumerate(768 ["Summarize section 1.", "Now section 2.", "Now section 3."]769 ):770 messages.append({"role": "user", "content": user_message})771772 r = client.beta.messages.create(773 model="claude-opus-5",774 max_tokens=1024,775 cache_control={"type": "ephemeral"},776 system=SYSTEM,777 messages=messages,778 diagnostics={"previous_message_id": prev_id},779 betas=["cache-diagnosis-2026-04-07"],780 )781782 if r.diagnostics is not None and r.diagnostics.cache_miss_reason is not None:783 print(f"Turn {i + 1} cache_miss_reason: {r.diagnostics.cache_miss_reason.type}")784785 messages.append({"role": "assistant", "content": r.content})786 prev_id = r.id787 ```788 </Tab>789790 <Tab title="TypeScript">791 ```typescript792 const client = new Anthropic();793794 const SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>";795796 const prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];797798 const messages: BetaMessageParam[] = [];799 let prevId: string | null = null;800801 for (const [i, prompt] of prompts.entries()) {802 messages.push({ role: "user", content: prompt });803804 const r: BetaMessage = await client.beta.messages.create({805 model: "claude-opus-5",806 max_tokens: 1024,807 cache_control: { type: "ephemeral" },808 system: SYSTEM,809 messages,810 diagnostics: { previous_message_id: prevId },811 betas: ["cache-diagnosis-2026-04-07"]812 });813814 if (r.diagnostics?.cache_miss_reason) {815 console.log(`Turn ${i + 1} cache_miss_reason: ${r.diagnostics.cache_miss_reason.type}`);816 }817818 messages.push({ role: "assistant", content: r.content });819 prevId = r.id;820 }821 ```822 </Tab>823824 <Tab title="C#">825 ```csharp826 AnthropicClient client = new();827828 var system = "You are an AI assistant analyzing a large document. <document>...</document>";829830 List<BetaMessageParam> messages = [];831 string? prevId = null;832 string[] prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];833834 for (int i = 0; i < prompts.Length; i++)835 {836 messages.Add(new() { Role = Role.User, Content = prompts[i] });837838 var r = await client.Beta.Messages.Create(839 new()840 {841 Model = Messages::Model.ClaudeOpus5,842 MaxTokens = 1024,843 CacheControl = new(),844 System = system,845 Messages = messages,846 Diagnostics = new() { PreviousMessageID = prevId },847 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],848 }849 );850851 if (r.Diagnostics?.CacheMissReason is { Type: var type })852 {853 Console.WriteLine($"Turn {i + 1} cache_miss_reason: {type.GetString()}");854 }855856 messages.Add(857 new()858 {859 Role = Role.Assistant,860 Content = r.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),861 }862 );863 prevId = r.ID;864 }865 ```866 </Tab>867868 <Tab title="Go">869 ```go870 client := anthropic.NewClient()871 ctx := context.Background()872873 system := []anthropic.BetaTextBlockParam{874 {Text: "You are an AI assistant analyzing a large document. <document>...</document>"},875 }876877 prompts := []string{"Summarize section 1.", "Now section 2.", "Now section 3."}878879 var messages []anthropic.BetaMessageParam880 prevID := param.Null[string]()881882 for turn, prompt := range prompts {883 messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt)))884885 r, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{886 Model: anthropic.ModelClaudeOpus5,887 MaxTokens: 1024,888 CacheControl: anthropic.BetaCacheControlEphemeralParam{},889 System: system,890 Messages: messages,891 Diagnostics: anthropic.BetaDiagnosticsParam{892 PreviousMessageID: prevID,893 },894 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},895 })896 if err != nil {897 panic(err)898 }899900 if r.JSON.Diagnostics.Valid() && r.Diagnostics.JSON.CacheMissReason.Valid() {901 fmt.Printf("Turn %d cache_miss_reason: %s\n", turn+1, r.Diagnostics.CacheMissReason.Type)902 }903904 messages = append(messages, r.ToParam())905 prevID = anthropic.String(r.ID)906 }907 ```908 </Tab>909910 <Tab title="Java">911 ```java912 var client = AnthropicOkHttpClient.fromEnv();913914 var system = "You are an AI assistant analyzing a large document. <document>...</document>";915 var prompts = List.of("Summarize section 1.", "Now section 2.", "Now section 3.");916917 var messages = new ArrayList<BetaMessageParam>();918 String prevId = null;919920 for (var turn = 0; turn < prompts.size(); turn++) {921 messages.add(922 BetaMessageParam.builder()923 .role(BetaMessageParam.Role.USER)924 .content(prompts.get(turn))925 .build()926 );927928 var r = client.beta().messages().create(929 MessageCreateParams.builder()930 .model(Model.CLAUDE_OPUS_5)931 .maxTokens(1024)932 .cacheControl(BetaCacheControlEphemeral.builder().build())933 .system(system)934 .messages(messages)935 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(prevId).build())936 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)937 .build()938 );939940 if (r.diagnostics().isPresent() && r.diagnostics().get().cacheMissReason().isPresent()) {941 var reason = r.diagnostics().get().cacheMissReason().get();942 // CacheMissReason doesn't expose a typed .type() accessor; read it from the raw JSON.943 @SuppressWarnings("unchecked")944 var json = (Map<String, JsonValue>) reason._json().orElseThrow().asObject().orElseThrow();945 IO.println("Turn " + (turn + 1) + " cache_miss_reason: " + json.get("type").asStringOrThrow());946 }947948 messages.add(r.toParam());949 prevId = r.id();950 }951 ```952 </Tab>953954 <Tab title="PHP">955 ```php956 $client = new Client();957958 $system = 'You are an AI assistant analyzing a large document. <document>...</document>';959960 $messages = [];961 $prevId = null;962963 foreach (['Summarize section 1.', 'Now section 2.', 'Now section 3.'] as $i => $userMsg) {964 $turn = $i + 1;965 $messages[] = ['role' => 'user', 'content' => $userMsg];966967 $r = $client->beta->messages->create(968 model: Model::CLAUDE_OPUS_5,969 maxTokens: 1024,970 cacheControl: new BetaCacheControlEphemeral,971 system: $system,972 messages: $messages,973 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($prevId),974 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],975 );976977 if ($r->diagnostics?->cacheMissReason !== null) {978 echo "Turn {$turn} cache_miss_reason: {$r->diagnostics->cacheMissReason->type}\n";979 }980981 $messages[] = ['role' => 'assistant', 'content' => $r->content];982 $prevId = $r->id;983 }984 ```985 </Tab>986987 <Tab title="Ruby">988 ```ruby989 client = Anthropic::Client.new990991 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"992993 messages = []994 prev_id = nil995996 ["Summarize section 1.", "Now section 2.", "Now section 3."].each_with_index do |user_msg, i|997 messages << {role: "user", content: user_msg}998999 r = client.beta.messages.create(1000 model: :"claude-opus-5",1001 max_tokens: 1024,1002 cache_control: {type: "ephemeral"},1003 system_: SYSTEM,1004 messages: messages,1005 diagnostics: {previous_message_id: prev_id},1006 betas: ["cache-diagnosis-2026-04-07"]1007 )10081009 if (reason = r.diagnostics&.cache_miss_reason)1010 puts "Turn #{i + 1} cache_miss_reason: #{reason.type}"1011 end10121013 messages << {role: "assistant", content: r.content}1014 prev_id = r.id1015 end1016 ```1017 </Tab>1018</Tabs>10191020## Response format10211022The `diagnostics` field on the response `Message` has four possible states:10231024| Value | Meaning |1025| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1026| field absent | The request did not include `diagnostics`, or the beta header was missing. |1027| `null` | Either `previous_message_id` was `null` (first turn, nothing to compare), or a comparison ran and found no divergence. |1028| `{"cache_miss_reason": null}` | The comparison was still running when the response was serialized. This can happen when the response starts very quickly. Treat it as inconclusive and check the next turn. |1029| `{"cache_miss_reason": {...}}` | A `cache_miss_reason` is attached. For `*_changed` types this identifies the first divergence point; `previous_message_not_found` and `unavailable` are cases where no comparison was produced. |10301031When `cache_miss_reason` is non-null, it looks like this:10321033```json1034{1035 "id": "msg_01Xyz...",1036 "type": "message",1037 "role": "assistant",1038 "content": [{ "type": "text", "text": "..." }],1039 "usage": {1040 "input_tokens": 42,1041 "cache_read_input_tokens": 0,1042 "cache_creation_input_tokens": 41850,1043 "output_tokens": 2101044 },1045 "diagnostics": {1046 "cache_miss_reason": {1047 "type": "system_changed",1048 "cache_missed_input_tokens": 418501049 }1050 }1051}1052```10531054## Cache miss reason types10551056`cache_miss_reason` is a discriminated union on `type`. The response reports the earliest divergence only, so fix it first; later ones may be hidden behind it.10571058| Type | What it means | What to change |1059| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1060| `model_changed` | The `model` differs from the previous request (for example, a router, A/B test, or fallback selected a different model). The cache is per-model. | Hold the model constant within a cached conversation. |1061| `system_changed` | The `system` parameter differs. Typically a timestamp, request ID, or other per-request value was interpolated into the system prompt. | Make the system prompt a byte-stable constant and move dynamic data into the first `user` message after your cache breakpoint. |1062| `tools_changed` | The `tools` array differs: tools were added, removed, or reordered between turns, or tool `input_schema` JSON was serialized non-deterministically. | Send the same tool list on every turn in a fixed order with deterministically serialized schemas (for example, sort keys). |1063| `messages_changed` | The model, system, and tools all match, but an earlier entry in `messages` was altered, reordered, or removed rather than appended to. Typically conversation history was truncated or edited, or assistant turns and `tool_result` blocks were re-serialized differently on resend. | Treat the history as append-only; echo assistant `content` and tool results back verbatim. |1064| `previous_message_not_found` | No stored fingerprint exists for the supplied `previous_message_id`. This is not evidence that your request changed. Typically the previous request did not carry the beta header, it came from a different workspace, or too much time has passed since it was sent. | Send the beta header on every turn and keep consecutive turns close together in time. |1065| `unavailable` | Diagnostic information was not available for this request. This includes the case where `model`, `system`, and `tools` match but another prompt-affecting request parameter (`tool_choice`, `thinking`, `context_management`, `output_config`, `output_format`, or the set of active `anthropic-beta` headers) differs, and very long conversations where the divergence is beyond the comparison horizon. Your request was processed normally. | Keep the prompt-affecting request parameters constant for the lifetime of a cached conversation. If persistent, apply the manual checks under [Troubleshooting common issues](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#troubleshooting-common-issues) on the prompt caching page. |10661067<Note>1068 The four `*_changed` types also carry a `cache_missed_input_tokens` integer: an estimate of how many input tokens fell after the divergence point, giving you a sense of how much cacheable prefix was lost. It is derived from byte lengths before tokenization, so treat it as a magnitude indicator rather than a billing number. It can differ from (and occasionally exceed) `usage.input_tokens`.1069</Note>10701071## Reading diagnostics alongside usage10721073`diagnostics` answers "did my request change?" while `usage.cache_read_input_tokens` answers "did the cache hit?". Combining them tells you where to look.10741075This matrix applies to turns where you passed a real `previous_message_id`. On the first turn (`previous_message_id: null`), `diagnostics` is always `null` and `cache_read_input_tokens` is normally zero because the cache is being written, not read; no troubleshooting is needed. The matrix also does not apply when `cache_miss_reason` is `null` (the comparison is still pending; check the next turn) or when its `type` is `previous_message_not_found` or `unavailable` (no comparison was produced).10761077| Diagnostics result | Cache read tokens | Interpretation |1078| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1079| `null` | high | Working as expected. Your prefix is stable and the cache hit. |1080| `null` | low or zero | Your requests match but the cache entry was no longer available. Consider shortening gaps between turns or using the [1-hour cache TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). |1081| `cache_miss_reason` is a `*_changed` type | low or zero | Your bug. The request changed; fix the cause indicated by `type`. |1082| `cache_miss_reason` is a `*_changed` type | high | Rare. A change occurred late in the prompt but an earlier `cache_control` breakpoint still hit. Worth fixing, but low impact. |10831084## Limitations10851086* **Beta:** Field names and semantics may change while this feature is in beta.1087* **Claude API only:** Not available on Amazon Bedrock or Google Cloud.1088* **Limited retention:** Fingerprints for `previous_message_id` lookup expire after a short period. Run diagnostic comparisons between closely spaced requests.1089* **Same workspace:** The previous request must have run in the same organization and workspace. To check, compare the `anthropic-workspace-id` [response header](https://platform.claude.com/docs/en/api/overview#response-headers) on the two responses.1090* **Comparison horizon:** For very long conversations where the only change is deep in the message list, the response may be `unavailable` rather than a precise location.1091* **Best-effort:** Diagnostics never blocks or fails your request. If diagnostic information is not available, the response returns `unavailable`, or `cache_miss_reason: null` when the comparison was still running.10921093## Data retention10941095Cache diagnostics is ZDR eligible (qualified). Anthropic does not store the raw text of your prompts or Claude's outputs for this feature.10961097The fingerprint stored for each request consists only of cryptographic hashes and token-count estimates, keyed by the response `id` and scoped to your organization and workspace. Fingerprints expire after a short period and are not used for any other purpose.10981099For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).11001101## See also11021103* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)1104* [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting)1105* [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)1106