OpenAI makes Prompt Cache Diagnostics generally available

OpenAI's Prompt Cache Diagnostics is now generally available in the Responses API, for GPT-5.6 and later supported models. If your requests share a long, stable prefix and a call ever reused fewer cached tokens than you expected, the platform can now tell you why — by comparing that request with an earlier response and naming what broke the match.

What changed

OpenAI's API changelog entry of 8 September 2026 describes the tool in one sentence: compare cache reuse against a previous response, identify the reasons for cache misses, and follow troubleshooting guidance to improve reuse. The accompanying guide states the mechanism. The diagnostics compare your current request with an earlier response to explain why an expected prefix was not reused; a prefix is the content at the beginning of a prompt, and reuse requires an exact prefix match together with compatible request settings — the model, the service tier and the tools.

What it means for you

If you followed our guide on prompt caching, you already keep the unchanging part of every request at the front. Diagnostics tell you when that stability broke, and where. The procedure has three steps. Choose a baseline: a recent completed response from your organization whose prefix the new request should reuse, such as the preceding turn of the same conversation. Setprompt_cache_options.comparison_response_idto that response's id. Then readprompt_cache_diagnostics on the new response: a cache miss comes with a reason, and usage.input_tokens_details.cached_tokensstill measures the reuse that actually happened.

Asking for a comparison changes nothing else. It does not load the earlier conversation into the request and does not alter caching behaviour; the request can still reuse matching cache entries from other requests. It costs nothing extra and is not counted separately against your rate limits, though any additional baseline or retry requests you send are billed and counted as usual.

The reasons come from a fixed list, and one of them is worth quoting because it is the easiest to cause by accident. input_changedmeans earlier input changed — instructions that carry a timestamp or a request id, or previous messages that were edited, reordered or removed — and the fix is to move the changing content after the reusable prefix and its cache breakpoint, preserving earlier messages and tool results and appending new turns.

Three limits stand. The reusable prefix must still meet the model's minimum cacheable length, which is 1,024 tokens for GPT-5.6 and later. The diagnostics are best effort and may not classify every miss; anunavailableresult is neither a hit nor a miss. And they never block or fail your request, and never change how the model generates its output. On privacy, OpenAI says the feature is compatible with Zero Data Retention: it stores no raw prompts or model outputs for it, and the diagnostic records hold configuration metadata, token-count estimates and hashes, scoped to your organization and expiring after a short period.

The source

OpenAI's API changelog, the entry of 8 September 2026, and the Prompt cache diagnostics guide, both on developers.openai.com. The background is in our guide, What Prompt Caching Is.