SPB Git

Repository Public

cache-diagnostics.md 48.0 KB 1,106 lines markdown

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
Files main
Menu

Theme