docs(api): update top_logprobs parameter description across chat and responses

stainless-app[bot] · stainless-app[bot] · commit f9d339fcea63 · 2026-05-06T08:58:18.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 233
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai/openai-5002c7ce1688cf372f6c268507494c5e6396f38db8d85d79029d949b7bb06fe3.yml
-openapi_spec_hash: 92713b0825f6b8760836778e6d27e837
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai/openai-578515408e7ee6ac115f3768b358ff2cd4f5699cbfb527fe58b19806e7d1f713.yml
+openapi_spec_hash: b2df68d6233a18b475590978f5682c04
 config_hash: c6cf65d9b19a16ce4313602a2204d48f
diff --git a/src/openai/resources/chat/completions/completions.py b/src/openai/resources/chat/completions/completions.py
@@ -516,8 +516,9 @@ def create(
               [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
               or [function tools](https://platform.openai.com/docs/guides/function-calling).
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
               `logprobs` must be set to `true` if this parameter is used.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
@@ -822,8 +823,9 @@ def create(
               [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
               or [function tools](https://platform.openai.com/docs/guides/function-calling).
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
               `logprobs` must be set to `true` if this parameter is used.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
@@ -1128,8 +1130,9 @@ def create(
               [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
               or [function tools](https://platform.openai.com/docs/guides/function-calling).
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
               `logprobs` must be set to `true` if this parameter is used.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
@@ -2037,8 +2040,9 @@ async def create(
               [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
               or [function tools](https://platform.openai.com/docs/guides/function-calling).
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
               `logprobs` must be set to `true` if this parameter is used.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
@@ -2343,8 +2347,9 @@ async def create(
               [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
               or [function tools](https://platform.openai.com/docs/guides/function-calling).
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
               `logprobs` must be set to `true` if this parameter is used.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
@@ -2649,8 +2654,9 @@ async def create(
               [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
               or [function tools](https://platform.openai.com/docs/guides/function-calling).
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
               `logprobs` must be set to `true` if this parameter is used.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
diff --git a/src/openai/resources/responses/responses.py b/src/openai/resources/responses/responses.py
@@ -344,8 +344,9 @@ def create(
                 [function calling](https://platform.openai.com/docs/guides/function-calling).
                 You can also use custom tools to call your own code.
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
               model considers the results of the tokens with top_p probability mass. So 0.1
@@ -593,8 +594,9 @@ def create(
                 [function calling](https://platform.openai.com/docs/guides/function-calling).
                 You can also use custom tools to call your own code.
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
               model considers the results of the tokens with top_p probability mass. So 0.1
@@ -842,8 +844,9 @@ def create(
                 [function calling](https://platform.openai.com/docs/guides/function-calling).
                 You can also use custom tools to call your own code.
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
               model considers the results of the tokens with top_p probability mass. So 0.1
@@ -2043,8 +2046,9 @@ async def create(
                 [function calling](https://platform.openai.com/docs/guides/function-calling).
                 You can also use custom tools to call your own code.
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
               model considers the results of the tokens with top_p probability mass. So 0.1
@@ -2292,8 +2296,9 @@ async def create(
                 [function calling](https://platform.openai.com/docs/guides/function-calling).
                 You can also use custom tools to call your own code.
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
               model considers the results of the tokens with top_p probability mass. So 0.1
@@ -2541,8 +2546,9 @@ async def create(
                 [function calling](https://platform.openai.com/docs/guides/function-calling).
                 You can also use custom tools to call your own code.
 
-          top_logprobs: An integer between 0 and 20 specifying the number of most likely tokens to
-              return at each token position, each with an associated log probability.
+          top_logprobs: An integer between 0 and 20 specifying the maximum number of most likely tokens
+              to return at each token position, each with an associated log probability. In
+              some cases, the number of returned tokens may be fewer than requested.
 
           top_p: An alternative to sampling with temperature, called nucleus sampling, where the
               model considers the results of the tokens with top_p probability mass. So 0.1
diff --git a/src/openai/types/admin/organization/usage_audio_speeches_response.py b/src/openai/types/admin/organization/usage_audio_speeches_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_audio_transcriptions_response.py b/src/openai/types/admin/organization/usage_audio_transcriptions_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_code_interpreter_sessions_response.py b/src/openai/types/admin/organization/usage_code_interpreter_sessions_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_completions_response.py b/src/openai/types/admin/organization/usage_completions_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_costs_response.py b/src/openai/types/admin/organization/usage_costs_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_embeddings_response.py b/src/openai/types/admin/organization/usage_embeddings_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_images_response.py b/src/openai/types/admin/organization/usage_images_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_moderations_response.py b/src/openai/types/admin/organization/usage_moderations_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/admin/organization/usage_vector_stores_response.py b/src/openai/types/admin/organization/usage_vector_stores_response.py
@@ -353,6 +353,12 @@ class DataResultOrganizationCostsResult(BaseModel):
     costs result.
     """
 
+    quantity: Optional[float] = None
+    """
+    When `group_by=line_item`, this field provides the quantity of the grouped costs
+    result.
+    """
+
 
 DataResult: TypeAlias = Annotated[
     Union[
diff --git a/src/openai/types/chat/chat_completion_token_logprob.py b/src/openai/types/chat/chat_completion_token_logprob.py
@@ -52,6 +52,5 @@ class ChatCompletionTokenLogprob(BaseModel):
     """List of the most likely tokens and their log probability, at this token
     position.
 
-    In rare cases, there may be fewer than the number of requested `top_logprobs`
-    returned.
+    The number of entries may be fewer than the requested `top_logprobs`.
     """
diff --git a/src/openai/types/chat/completion_create_params.py b/src/openai/types/chat/completion_create_params.py
@@ -311,8 +311,9 @@ class CompletionCreateParamsBase(TypedDict, total=False):
 
     top_logprobs: Optional[int]
     """
-    An integer between 0 and 20 specifying the number of most likely tokens to
-    return at each token position, each with an associated log probability.
+    An integer between 0 and 20 specifying the maximum number of most likely tokens
+    to return at each token position, each with an associated log probability. In
+    some cases, the number of returned tokens may be fewer than requested.
     `logprobs` must be set to `true` if this parameter is used.
     """
 
diff --git a/src/openai/types/responses/response.py b/src/openai/types/responses/response.py
@@ -276,8 +276,9 @@ class Response(BaseModel):
 
     top_logprobs: Optional[int] = None
     """
-    An integer between 0 and 20 specifying the number of most likely tokens to
-    return at each token position, each with an associated log probability.
+    An integer between 0 and 20 specifying the maximum number of most likely tokens
+    to return at each token position, each with an associated log probability. In
+    some cases, the number of returned tokens may be fewer than requested.
     """
 
     truncation: Optional[Literal["auto", "disabled"]] = None
diff --git a/src/openai/types/responses/response_create_params.py b/src/openai/types/responses/response_create_params.py
@@ -251,8 +251,9 @@ class ResponseCreateParamsBase(TypedDict, total=False):
 
     top_logprobs: Optional[int]
     """
-    An integer between 0 and 20 specifying the number of most likely tokens to
-    return at each token position, each with an associated log probability.
+    An integer between 0 and 20 specifying the maximum number of most likely tokens
+    to return at each token position, each with an associated log probability. In
+    some cases, the number of returned tokens may be fewer than requested.
     """
 
     top_p: Optional[float]
diff --git a/src/openai/types/responses/response_text_delta_event.py b/src/openai/types/responses/response_text_delta_event.py
@@ -30,7 +30,7 @@ class Logprob(BaseModel):
     """The log probability of this token."""
 
     top_logprobs: Optional[List[LogprobTopLogprob]] = None
-    """The log probability of the top 20 most likely tokens."""
+    """The log probabilities of up to 20 of the most likely tokens."""
 
 
 class ResponseTextDeltaEvent(BaseModel):
diff --git a/src/openai/types/responses/response_text_done_event.py b/src/openai/types/responses/response_text_done_event.py
@@ -30,7 +30,7 @@ class Logprob(BaseModel):
     """The log probability of this token."""
 
     top_logprobs: Optional[List[LogprobTopLogprob]] = None
-    """The log probability of the top 20 most likely tokens."""
+    """The log probabilities of up to 20 of the most likely tokens."""
 
 
 class ResponseTextDoneEvent(BaseModel):
diff --git a/src/openai/types/responses/responses_client_event.py b/src/openai/types/responses/responses_client_event.py
@@ -293,8 +293,9 @@ class ResponsesClientEvent(BaseModel):
 
     top_logprobs: Optional[int] = None
     """
-    An integer between 0 and 20 specifying the number of most likely tokens to
-    return at each token position, each with an associated log probability.
+    An integer between 0 and 20 specifying the maximum number of most likely tokens
+    to return at each token position, each with an associated log probability. In
+    some cases, the number of returned tokens may be fewer than requested.
     """
 
     top_p: Optional[float] = None
diff --git a/src/openai/types/responses/responses_client_event_param.py b/src/openai/types/responses/responses_client_event_param.py
@@ -294,8 +294,9 @@ class ResponsesClientEventParam(TypedDict, total=False):
 
     top_logprobs: Optional[int]
     """
-    An integer between 0 and 20 specifying the number of most likely tokens to
-    return at each token position, each with an associated log probability.
+    An integer between 0 and 20 specifying the maximum number of most likely tokens
+    to return at each token position, each with an associated log probability. In
+    some cases, the number of returned tokens may be fewer than requested.
     """
 
     top_p: Optional[float]
