OpenAI adds Prompt Cache Diagnostics to the Responses API

OpenAI has added Prompt Cache Diagnostics to the Responses API, giving developers a way to see exactly why a request failed to reuse cached tokens instead of guessing.

What's new

The feature works by comparing a current request against a prior one. Developers set comparison_response_id inside prompt_cache_options, pointing at an earlier response to use as the diagnostic baseline. OpenAI's documentation explains the mechanism plainly: "Prompt cache diagnostics help explain why a request reused fewer tokens than expected."

The system checks what changed between the two requests — model selection, cache keys, tool definitions, request settings, or the input content itself — and reports back which of those changes broke the cache. That turns a normally opaque cost problem (a request that should have hit cache but didn't, and now costs more) into something developers can actually debug.

The capability is scoped to GPT-5.6 and later models, and ships through the Responses API rather than the older Chat Completions API. It's one of six changelog entries OpenAI shipped across just over a week: IPv6 support for api.openai.com (Sep 1), clearer 429 vs. 503 error codes to distinguish traffic spikes from model overload (Sep 2), the GPT-6 Astra release itself (Sep 3), async tool calling and mid-turn steering controls for Astra (Sep 3), and GPT Image 2.5's Sunburst and Flare models (Sep 8) — all landing the same day as this diagnostics tool.

Context

Prompt caching has been one of the more consequential but least visible cost levers on the API — a cache hit can cut input-token pricing dramatically, but a silent miss just shows up as a bigger bill with no explanation. As reasoning models like GPT-6 Astra push context windows and multi-turn agent loops longer, cache reuse matters more, and the failure modes (a changed tool schema, a different system prompt, an altered cache key) get harder to spot by eye.

This follows a broader pattern of OpenAI shipping observability tooling alongside capability releases rather than after the fact — the API error-code split two days earlier serves a similar purpose, letting developers distinguish infrastructure problems from application-level cache misses.

Why it matters

For any team running cost-sensitive agentic workloads on GPT-5.6 or GPT-6 Astra, this closes a real debugging gap. Cache-reuse failures previously required trial-and-error guessing about which part of a request changed; now that's a direct API answer. It's a small, unglamorous feature, but it's the kind of tooling that determines whether prompt caching's cost savings are actually realized in production rather than quietly eroded by unnoticed cache misses.