Cache diagnostics (キャッシュ診断)

Messages リクエストに diagnostics オブジェクトを含めると利用できます。プロンプトキャッシュが前のターンと一致しなかった原因を調べる場面に関わる機能です。

diagnostics オブジェクトを含むリクエストごとに、API はレスポンスの id をキーにした軽量なフィンガープリントを保存します。オブジェクトを含まないリクエストについては何も保存しません。

次のリクエストが届くと、API はそのリクエストのフィンガープリントを作り直して保存済みのものと比較し、最初に分岐した箇所を説明する diagnostics オブジェクトをレスポンスに付けます。比較の対象はリクエストの構造で、実際にキャッシュがヒットしたかどうかとは独立しています。

• POST /v1/messages のレスポンスには常に diagnostics フィールドが含まれ、リクエストに diagnostics オブジェクトが無い場合は null になります。
• ストリーミングのレスポンスでは、diagnostics は message_start イベントに含まれます。
• 診断がリクエストをブロックしたり失敗させたりすることはありません。

diagnostics の値と cache_miss_reason の種類は次のとおりです。

• diagnostics が null：リクエストに diagnostics オブジェクトが無い、previous_message_id が null だった (最初のターン)、または比較を行い分岐が見つからなかった、のいずれかです。
• {"cache_miss_reason": null}：レスポンスの組み立て時点で比較がまだ終わっていなかった状態です。結論が出ていないものとして扱い、次のターンで確認します。
• model_changed：前のリクエストとモデルが異なります。ルーター、A/B テスト、フォールバックが別のモデルを選んだ場合などが該当します。キャッシュはモデルごとです。
• system_changed：system パラメーターが異なります。タイムスタンプやリクエスト ID など、リクエストごとに変わる値が system プロンプトに埋め込まれている場合が典型です。
• tools_changed：tools 配列が異なります。ターン間でツールが追加・削除・並べ替えされた場合や、ツールの input_schema の JSON が決定的でない形で直列化された場合です。
• messages_changed：モデル・system・tools は一致していますが、messages の前のほうのエントリが末尾への追加ではなく、変更・並べ替え・削除されています。
• previous_message_not_found：指定した previous_message_id に対応するフィンガープリントが保存されていません。リクエストが変わったことを示すものではありません。
• unavailable：このリクエストでは診断情報を得られませんでした。リクエスト自体は通常どおり処理されます。

レスポンスが示すのは最も早い分岐だけです。後ろの分岐がその陰に隠れている場合があるため、最初の分岐から先に直します。cache_missed_input_tokens はトークン化前のバイト長から求めた推定値で、失われたキャッシュ可能なプレフィックスの規模の目安です。課金の数値としては扱いません。

• 比較するには、前のリクエストが同じ organization と workspace で実行されている必要があります。
• previous_message_id の参照に使うフィンガープリントは短い期間で期限が切れます。診断の比較は、間隔の近いリクエストの間で行います。
• 非常に長い会話で、変更がメッセージ一覧の深い位置にしか無い場合、正確な位置ではなく unavailable が返る場合があります。
• ベータヘッダーだけを送り diagnostics オブジェクトを含めないリクエストは受け付けられますが、フィンガープリントは保存されません。後のターンでそのリクエストを previous_message_id に指定すると previous_message_not_found が返ります。

この機能のデータの扱いは次のとおりです。

• フィンガープリントに含まれるのはハッシュとトークン数の推定値だけで、プロンプトの生の内容は含まれません。
• フィンガープリントの保持は限られた期間で、organization と workspace の範囲に限定され、ほかの目的には使われません。
• Anthropic は、この機能のためにプロンプトや Claude の出力の生のテキストを保存しません。
• フィンガープリントが保存されるのは、diagnostics オブジェクトを含むリクエストだけです。

cache-diagnosis-2026-04-07 ベータヘッダーは現在不要で、diagnostics オブジェクトを含めることが利用の申し込み (オプトイン) になります。

1. Messages リクエストのすべてのターンに diagnostics オブジェクトを含めます。API がフィンガープリントを保存するのは、このオブジェクトを含むリクエストだけです。
2. 最初のターンでは "previous_message_id": null を渡します。比較対象の前のメッセージが無い状態でオプトインします。
3. 2 ターン目以降は、直前のレスポンスの id を previous_message_id として渡します。複数ターンの会話では、最新のレスポンスの id を毎ターン引き継ぎます。