feat(api): Add prompt cache diagnostics (openai#3800)

## Summary

Expose optional prompt cache comparison diagnostics across the stable
and beta Responses APIs. Clarify how Fast and Priority service tier
requests resolve for different models.

## Changes

- Add the optional `comparison_response_id` prompt cache option to
response creation parameters and client events.
- Add `prompt_cache_diagnostics` to response models with typed cache
hit, cache miss, comparison-not-found, and unavailable outcomes.
- Expose cache miss reasons, affected token estimates, and
reusable-prefix token counts in diagnostic results.
- Include the comparison response ID in returned prompt cache options
when supplied.
- Clarify that Fast or Priority requests resolve to `fast` for models
with a dedicated Fast tier and to `priority` for other models.

Co-authored-by: apcha-oai <228803254+apcha-oai@users.noreply.github.com>

Author: apcha-oai

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 08cffa97-63b1-4ab3-b3e4-9d438f45458f
-openapi_spec_hash: fcdb9c99a509f5ea8b90d7abbf1dab2f
-openapi_transformed_spec_hash: dd244f7dd3ab9d18dc2c34970a39505f
-config_hash: 81fd1039eb373628d87269f065d30a69
-codegen_sha: fb6674883ea2eed44fa6db1f16b106ee84b4c9e5
-codegen_hash: d68cd064823d9541b5d0874c92142d2691f7943452d9142c205b4cead3798785
-public_codegen_sha: e84368fa07e999995b4ec9f8514e6c5a98be2a89
+generation_id: 50d48205-978b-4b96-83b9-e92c82968d25
+openapi_spec_hash: a5a64d9aaf4a4022898dd86685c102ab
+openapi_transformed_spec_hash: f7c7c9ee2566bcf8165ab87b4851a1e5
+config_hash: dfe8a20c64cc5d852e69c441cbd28ae7
+codegen_sha: 9cbf6087efd2a6d5a57028c17f031fea6f7f5015
+codegen_hash: 331343ebbad785fc4c6d5ce8197e5b3de60b4b989f77df08356eb00fc6e958ef
+public_codegen_sha: 0c33f635083e108a823a23805ec04f2e6d1add4d

api_reference/openapi.transformed.yml

@@ -1958,12 +1958,13 @@ def compact(
               request will be processed with the Flex Processing service tier. - To opt-in to
               [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
               `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-              Completions. The response will show `service_tier=priority` regardless of if you
-              specify `service_tier=fast` or `priority` in your request. - When not set, the
-              default behavior is 'auto'. When the `service_tier` parameter is set, the
-              response body will include the `service_tier` value based on the processing mode
-              actually used to serve the request. This response value may be different from
-              the value set in the parameter.
+              Completions. For models with a dedicated Fast tier, either value resolves to
+              `service_tier=fast`; for other models, either value resolves to
+              `service_tier=priority`. - When not set, the default behavior is 'auto'. When
+              the `service_tier` parameter is set, the response body will include the
+              `service_tier` value based on the processing mode actually used to serve the
+              request. This response value may be different from the value set in the
+              parameter.
 
           extra_headers: Send extra headers
 
@@ -3912,12 +3913,13 @@ async def compact(
               request will be processed with the Flex Processing service tier. - To opt-in to
               [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
               `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-              Completions. The response will show `service_tier=priority` regardless of if you
-              specify `service_tier=fast` or `priority` in your request. - When not set, the
-              default behavior is 'auto'. When the `service_tier` parameter is set, the
-              response body will include the `service_tier` value based on the processing mode
-              actually used to serve the request. This response value may be different from
-              the value set in the parameter.
+              Completions. For models with a dedicated Fast tier, either value resolves to
+              `service_tier=fast`; for other models, either value resolves to
+              `service_tier=priority`. - When not set, the default behavior is 'auto'. When
+              the `service_tier` parameter is set, the response body will include the
+              `service_tier` value based on the processing mode actually used to serve the
+              request. This response value may be different from the value set in the
+              parameter.
 
           extra_headers: Send extra headers
 

src/openai/resources/beta/responses/responses.py

@@ -1897,12 +1897,13 @@ def compact(
               request will be processed with the Flex Processing service tier. - To opt-in to
               [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
               `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-              Completions. The response will show `service_tier=priority` regardless of if you
-              specify `service_tier=fast` or `priority` in your request. - When not set, the
-              default behavior is 'auto'. When the `service_tier` parameter is set, the
-              response body will include the `service_tier` value based on the processing mode
-              actually used to serve the request. This response value may be different from
-              the value set in the parameter.
+              Completions. For models with a dedicated Fast tier, either value resolves to
+              `service_tier=fast`; for other models, either value resolves to
+              `service_tier=priority`. - When not set, the default behavior is 'auto'. When
+              the `service_tier` parameter is set, the response body will include the
+              `service_tier` value based on the processing mode actually used to serve the
+              request. This response value may be different from the value set in the
+              parameter.
 
           extra_headers: Send extra headers
 
@@ -3759,12 +3760,13 @@ async def compact(
               request will be processed with the Flex Processing service tier. - To opt-in to
               [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
               `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-              Completions. The response will show `service_tier=priority` regardless of if you
-              specify `service_tier=fast` or `priority` in your request. - When not set, the
-              default behavior is 'auto'. When the `service_tier` parameter is set, the
-              response body will include the `service_tier` value based on the processing mode
-              actually used to serve the request. This response value may be different from
-              the value set in the parameter.
+              Completions. For models with a dedicated Fast tier, either value resolves to
+              `service_tier=fast`; for other models, either value resolves to
+              `service_tier=priority`. - When not set, the default behavior is 'auto'. When
+              the `service_tier` parameter is set, the response body will include the
+              `service_tier` value based on the processing mode actually used to serve the
+              request. This response value may be different from the value set in the
+              parameter.
 
           extra_headers: Send extra headers
 

src/openai/resources/responses/responses.py

@@ -36,6 +36,11 @@
     "ModerationOutput",
     "ModerationOutputModerationResult",
     "ModerationOutputError",
+    "PromptCacheDiagnostics",
+    "PromptCacheDiagnosticsCacheMiss",
+    "PromptCacheDiagnosticsCacheHit",
+    "PromptCacheDiagnosticsComparisonResponseNotFound",
+    "PromptCacheDiagnosticsUnavailable",
     "PromptCacheOptions",
     "Reasoning",
 ]
@@ -185,6 +190,55 @@ class Moderation(BaseModel):
     """Moderation for the response output."""
 
 
+class PromptCacheDiagnosticsCacheMiss(BaseModel):
+    cache_missed_tokens: int
+    """
+    The estimated number of input tokens affected after the first detected
+    divergence.
+    """
+
+    reason: Literal[
+        "model_changed",
+        "prompt_cache_key_changed",
+        "tools_changed",
+        "text_format_changed",
+        "reasoning_effort_changed",
+        "verbosity_changed",
+        "context_compacted",
+        "input_changed",
+        "service_tier_changed",
+    ]
+    """The reason prompt cache reuse did not occur."""
+
+    type: Literal["cache_miss"]
+
+    comparison_reusable_tokens: Optional[int] = None
+    """The raw token count of the reusable prefix in the compared response."""
+
+
+class PromptCacheDiagnosticsCacheHit(BaseModel):
+    type: Literal["cache_hit"]
+
+
+class PromptCacheDiagnosticsComparisonResponseNotFound(BaseModel):
+    type: Literal["comparison_response_not_found"]
+
+
+class PromptCacheDiagnosticsUnavailable(BaseModel):
+    type: Literal["unavailable"]
+
+
+PromptCacheDiagnostics: TypeAlias = Annotated[
+    Union[
+        PromptCacheDiagnosticsCacheMiss,
+        PromptCacheDiagnosticsCacheHit,
+        PromptCacheDiagnosticsComparisonResponseNotFound,
+        PromptCacheDiagnosticsUnavailable,
+    ],
+    PropertyInfo(discriminator="type"),
+]
+
+
 class PromptCacheOptions(BaseModel):
     """The prompt-caching options that were applied to the response.
 
@@ -197,6 +251,9 @@ class PromptCacheOptions(BaseModel):
     ttl: Literal["30m"]
     """The minimum lifetime applied to each cache breakpoint."""
 
+    comparison_response_id: Optional[str] = None
+    """The response ID supplied as the prompt cache diagnostics comparison."""
+
 
 class Reasoning(BaseModel):
     """
@@ -514,6 +571,9 @@ class BetaResponse(BaseModel):
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
+    prompt_cache_diagnostics: Optional[PromptCacheDiagnostics] = None
+    """Prompt cache diagnostics requested for this response."""
+
     prompt_cache_key: Optional[str] = None
     """
     Used by OpenAI to cache responses for similar requests to optimize your cache

src/openai/types/beta/beta_response.py

@@ -110,6 +110,13 @@ class ResponseCreatePromptCacheOptions(BaseModel):
     Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details.
     """
 
+    comparison_response_id: Optional[str] = None
+    """The ID of a response to compare when diagnosing prompt cache reuse.
+
+    Supplying this field requests prompt cache diagnostics when the feature is
+    enabled.
+    """
+
     mode: Optional[Literal["implicit", "explicit"]] = None
     """Controls whether OpenAI automatically creates an implicit cache breakpoint.
 

src/openai/types/beta/beta_responses_client_event.py

@@ -110,6 +110,13 @@ class ResponseCreatePromptCacheOptions(TypedDict, total=False):
     Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details.
     """
 
+    comparison_response_id: Optional[str]
+    """The ID of a response to compare when diagnosing prompt cache reuse.
+
+    Supplying this field requests prompt cache diagnostics when the feature is
+    enabled.
+    """
+
     mode: Literal["implicit", "explicit"]
     """Controls whether OpenAI automatically creates an implicit cache breakpoint.
 

src/openai/types/beta/beta_responses_client_event_param.py

@@ -181,12 +181,13 @@ class ResponseCompactParams(TypedDict, total=False):
       request will be processed with the Flex Processing service tier. - To opt-in
       to [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
       `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-      Completions. The response will show `service_tier=priority` regardless of if
-      you specify `service_tier=fast` or `priority` in your request. - When not set,
-      the default behavior is 'auto'. When the `service_tier` parameter is set, the
-      response body will include the `service_tier` value based on the processing
-      mode actually used to serve the request. This response value may be different
-      from the value set in the parameter.
+      Completions. For models with a dedicated Fast tier, either value resolves to
+      `service_tier=fast`; for other models, either value resolves to
+      `service_tier=priority`. - When not set, the default behavior is 'auto'. When
+      the `service_tier` parameter is set, the response body will include the
+      `service_tier` value based on the processing mode actually used to serve the
+      request. This response value may be different from the value set in the
+      parameter.
     """
 
     betas: Annotated[List[Literal["responses_multi_agent=v1"]], PropertyInfo(alias="openai-beta")]

src/openai/types/beta/response_compact_params.py

@@ -509,6 +509,13 @@ class PromptCacheOptions(TypedDict, total=False):
     Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details.
     """
 
+    comparison_response_id: Optional[str]
+    """The ID of a response to compare when diagnosing prompt cache reuse.
+
+    Supplying this field requests prompt cache diagnostics when the feature is
+    enabled.
+    """
+
     mode: Literal["implicit", "explicit"]
     """Controls whether OpenAI automatically creates an implicit cache breakpoint.
 

src/openai/types/beta/response_create_params.py

@@ -39,6 +39,11 @@
     "ModerationOutput",
     "ModerationOutputModerationResult",
     "ModerationOutputError",
+    "PromptCacheDiagnostics",
+    "PromptCacheDiagnosticsCacheMiss",
+    "PromptCacheDiagnosticsCacheHit",
+    "PromptCacheDiagnosticsComparisonResponseNotFound",
+    "PromptCacheDiagnosticsUnavailable",
     "PromptCacheOptions",
 ]
 
@@ -187,6 +192,55 @@ class Moderation(BaseModel):
     """Moderation for the response output."""
 
 
+class PromptCacheDiagnosticsCacheMiss(BaseModel):
+    cache_missed_tokens: int
+    """
+    The estimated number of input tokens affected after the first detected
+    divergence.
+    """
+
+    reason: Literal[
+        "model_changed",
+        "prompt_cache_key_changed",
+        "tools_changed",
+        "text_format_changed",
+        "reasoning_effort_changed",
+        "verbosity_changed",
+        "context_compacted",
+        "input_changed",
+        "service_tier_changed",
+    ]
+    """The reason prompt cache reuse did not occur."""
+
+    type: Literal["cache_miss"]
+
+    comparison_reusable_tokens: Optional[int] = None
+    """The raw token count of the reusable prefix in the compared response."""
+
+
+class PromptCacheDiagnosticsCacheHit(BaseModel):
+    type: Literal["cache_hit"]
+
+
+class PromptCacheDiagnosticsComparisonResponseNotFound(BaseModel):
+    type: Literal["comparison_response_not_found"]
+
+
+class PromptCacheDiagnosticsUnavailable(BaseModel):
+    type: Literal["unavailable"]
+
+
+PromptCacheDiagnostics: TypeAlias = Annotated[
+    Union[
+        PromptCacheDiagnosticsCacheMiss,
+        PromptCacheDiagnosticsCacheHit,
+        PromptCacheDiagnosticsComparisonResponseNotFound,
+        PromptCacheDiagnosticsUnavailable,
+    ],
+    PropertyInfo(discriminator="type"),
+]
+
+
 class PromptCacheOptions(BaseModel):
     """The prompt-caching options that were applied to the response.
 
@@ -199,6 +253,9 @@ class PromptCacheOptions(BaseModel):
     ttl: Literal["30m"]
     """The minimum lifetime applied to each cache breakpoint."""
 
+    comparison_response_id: Optional[str] = None
+    """The response ID supplied as the prompt cache diagnostics comparison."""
+
 
 class Response(BaseModel):
     id: str
@@ -357,6 +414,9 @@ class Response(BaseModel):
     [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     """
 
+    prompt_cache_diagnostics: Optional[PromptCacheDiagnostics] = None
+    """Prompt cache diagnostics requested for this response."""
+
     prompt_cache_key: Optional[str] = None
     """
     Used by OpenAI to cache responses for similar requests to optimize your cache