Responses schemas
The full schema and model definitions referenced by the Responses endpoints. Each endpoint page links here for the detailed shape of its request and response objects.
Schemas
Annotation
Annotation attached to a span of generated output text, such as a citation or file reference.
Type: FileCitationBody | UrlCitationBody | FilePath
Cancel Response Response
The response object returned by the cancel endpoint. Only the lifecycle fields the server populates on cancel are present, and the output array is always empty.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier for this response. |
object | enum ('response') | Yes | Object type; always response. |
status | enum ('completed', 'failed', 'in_progress', 'cancelled', 'queued', 'incomplete') | Yes | The status of the response generation. After a successful cancel of an in-progress response this is cancelled; for an already-terminal response the current terminal status is returned. |
model | string | Yes | Model ID used to generate the response. |
background | boolean | Yes | Whether the response was run in the background. |
output | array of OutputItem | Yes | An array of content items generated by the model. Always empty on a cancelled response. |
Click Button Type
Type: enum ('left', 'right', 'wheel', 'back', 'forward')
Click Param
A click action.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('click') | Yes | Specifies the event type. For a click action, this property is always click. (default: click) |
button | ClickButtonType | Yes | Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward. |
x | integer | Yes | The x-coordinate where the click occurred. |
y | integer | Yes | The y-coordinate where the click occurred. |
Computer Action
Type: ClickParam | DoubleClickAction | DragParam | KeyPressAction | MoveParam | ScreenshotParam | ScrollParam | TypeParam | WaitParam
Computer Action List
Flattened batched actions for computer_use. Each action includes an
type discriminator and action-specific fields.
Type: array of ComputerAction
Computer Call Output Item Param
The output of a computer tool call.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | null | No | The ID of the computer tool call output. |
call_id | string | Yes | The ID of the computer tool call that produced the output. (minLength: 1, maxLength: 64) |
type | enum ('computer_call_output') | Yes | The type of the computer tool call output. Always computer_call_output. (default: computer_call_output) |
output | ComputerScreenshotImage | Yes | |
acknowledged_safety_checks | array of ComputerCallSafetyCheckParam | null | No | The safety checks reported by the API that have been acknowledged by the developer. |
status | FunctionCallItemStatus | null | No | The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API. |
Computer Call Output Status
Type: enum ('completed', 'incomplete', 'failed')
Computer Call Safety Check Param
A pending safety check for the computer call.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The ID of the pending safety check. |
code | string | null | No | The type of the pending safety check. |
message | string | null | No | Details about the pending safety check. |
Computer Screenshot Image
A computer screenshot image used with the computer use tool.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('computer_screenshot') | Yes | Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot. (default: computer_screenshot) |
image_url | string (uri) | No | The URL of the screenshot image. |
file_id | string | No | The identifier of an uploaded file that contains the screenshot. |
detail | enum ('original') | No | The detail level of the screenshot. Always original when provided. |
Computer Tool
A tool that controls a virtual computer.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('computer') | Yes | The type of the computer tool. Always computer. (default: computer) |
Computer Tool Call
A tool call to a computer use tool. See the computer use guide for more information.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('computer_call') | Yes | The type of the computer call. Always computer_call. (default: computer_call) |
id | string | Yes | The unique ID of the computer call. |
call_id | string | Yes | An identifier used when responding to the tool call with output. |
action | ComputerAction | No | |
actions | ComputerActionList | No | |
pending_safety_checks | array of ComputerCallSafetyCheckParam | Yes | The pending safety checks for the computer call. |
meta_safety_replay_receipt | string | No | An opaque Meta wire extension containing a time-bounded receipt for the accepted native-computer safety replay prefix through this call. Stateless clients must copy it unchanged from response.output into the corresponding item under input on the next request; the matching call output still requires a fresh acknowledgement. (minLength: 1, maxLength: 8192) |
status | enum ('in_progress', 'completed', 'incomplete') | Yes | Item status. One of in_progress, completed, or incomplete. Populated when items are returned via API. |
Computer Tool Call Output
The output of a computer tool call.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('computer_call_output') | Yes | The type of the computer tool call output. Always computer_call_output. (default: computer_call_output) |
id | string | No | The ID of the computer tool call output. |
call_id | string | Yes | The ID of the computer tool call that produced the output. |
acknowledged_safety_checks | array of ComputerCallSafetyCheckParam | No | The safety checks reported by the API that have been acknowledged by the developer. |
output | ComputerScreenshotImage | Yes | |
status | enum ('in_progress', 'completed', 'incomplete') | No | The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API. |
Computer Tool Call Output Resource
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('computer_call_output') | Yes | The type of the computer tool call output. Always computer_call_output. (default: computer_call_output) |
id | string | Yes | The unique ID of the computer call tool output. |
call_id | string | Yes | The ID of the computer tool call that produced the output. |
acknowledged_safety_checks | array of ComputerCallSafetyCheckParam | No | The safety checks reported by the API that have been acknowledged by the developer. |
output | ComputerScreenshotImage | Yes | |
status | ComputerCallOutputStatus | Yes | The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API. |
created_by | string | No | Identifier for the actor that created the item. |
Conversation-2
The conversation this response belonged to. Its input and output items were added to that conversation automatically.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier of the conversation this response belongs to. |
Coord Param
An x/y coordinate pair, e.g. { x: 100, y: 200 }.
| Field | Type | Required | Description |
|---|---|---|---|
x | integer | Yes | The x-coordinate. |
y | integer | Yes | The y-coordinate. |
Create Model Response Properties
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | No | |
top_logprobs | integer | No | An integer between 0 and 20 giving the number of top alternative tokens to return at each position, each with its log probability. (minimum: 0, maximum: 20) |
temperature | number | null | No | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | No | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No | The retention policy for the prompt cache. |
Create Response
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | No | |
top_logprobs | integer | No | An integer between 0 and 20 giving the number of top alternative tokens to return at each position, each with its log probability. (minimum: 0, maximum: 20) |
temperature | number | null | No | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | No | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No | The retention policy for the prompt cache. |
previous_response_id | string | null | No | Identifier of a previous response to continue from. Use this to build multi-turn conversations with server-managed state. Cannot be combined with conversation. |
model | string | No | ID of the model used to generate the response. |
reasoning | Reasoning | null | No | |
background | boolean | null | No | Whether to run the response asynchronously in the background. Cannot be combined with stream. (default: false) |
max_tool_calls | integer | null | No | Maximum number of built-in tool calls allowed while generating a response, counted across all built-in tools rather than per tool. The model ignores any calls beyond this limit. (minimum: 1) |
text | ResponseTextParam | No | |
tools | ToolsArray | No | |
tool_choice | ToolChoiceParam | No | |
prompt | Prompt | No | |
truncation | enum ('auto', 'disabled') | null | No | Truncation strategy for the request. Only disabled (the default) is supported: if the input plus requested output tokens exceed the model's context window, the request fails with a 400 error. The auto strategy is not supported. (default: disabled) |
client_metadata | object | null | No | Optional client-provided request metadata. Accepted for compatibility and ignored. |
input | InputParam | No | |
include | array of IncludeEnum | null | No | Additional output data to return in the response. Use message.output_text.logprobs to return token-level log probabilities on output text (set together with top_logprobs and a reasoning.effort of none), and reasoning.encrypted_content to return encrypted reasoning items for stateless multi-turn replay. |
parallel_tool_calls | boolean | null | No | Whether the model may issue multiple tool calls in a single turn. (default: true) |
store | boolean | null | No | Whether to persist the generated response so it can be retrieved later and chained from previous_response_id. (default: true) |
instructions | string | null | No | Developer-level instructions inserted at the top of the model's context. When previous_response_id is set, instructions from the prior response are not carried forward, so you can change them on each turn. Top-level image models place these instructions immediately before the current user message instead, and also honor developer or system input messages that come before the first user message or after the most recent image_generation_call; those from earlier turns, and those stored with a previous response, are not carried forward. Top-level image models accept at most 12,000 characters across this field and those messages, returning a 400 error when the combined limit is exceeded. |
stream | boolean | null | No | If true, the response is streamed to the client as server-sent events as it is generated. Cannot be combined with background. (default: false) |
stream_options | ResponseStreamOptions | No | |
max_output_tokens | integer | null | No | Upper bound on the number of tokens generated for the response, counting both visible output and reasoning tokens. Minimum is 16; values above the model's configured maximum, or that exceed the remaining context window, return a 400 error. (minimum: 16) |
Delete Response Response
Returned by the delete-response endpoint to confirm a response was deleted.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier of the deleted response. |
object | enum ('response.deleted') | Yes | Object type; always response.deleted. |
deleted | boolean | Yes | Always true when the response was deleted. |
Detail Enum
Type: enum ('low', 'high', 'auto', 'original')
Double Click Action
A double click action.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('double_click') | Yes | Specifies the event type. For a double click action, this property is always set to double_click. (default: double_click) |
x | integer | Yes | The x-coordinate where the double click occurred. |
y | integer | Yes | The y-coordinate where the double click occurred. |
Drag Param
A drag action.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('drag') | Yes | Specifies the event type. For a drag action, this property is always set to drag. (default: drag) |
path | array of CoordParam | Yes | An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg [ { x: 100, y: 200 }, { x: 200, y: 300 } ] |
Easy Input Message
A message in a Responses input or replayed history. The developer and system roles carry instructions (developer takes precedence); user carries the caller's prompt; assistant replays prior model output.
| Field | Type | Required | Description |
|---|---|---|---|
role | enum ('user', 'assistant', 'system', 'developer') | Yes | Role of the message author. One of user, assistant, system, or developer. |
content | string | InputMessageContentList | Yes | Message content. Either plain text or an array of content parts (text, image, file, or video). Can replay previous assistant output. |
phase | MessagePhase | null | No | |
type | enum ('message') | No | Object type; always message. |
Empty Model Param
Type: object
File Citation Body
Citation that points to an uploaded file used to ground the response.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('file_citation') | Yes | Annotation type; always file_citation. (default: file_citation) |
file_id | string | Yes | Identifier of the cited file. |
index | integer | Yes | Position of the cited file in the list of files. |
filename | string | Yes | Name of the cited file. |
File Detail Enum
Type: enum ('low', 'high')
File Input Detail
Type: enum ('low', 'high')
File Path
File path annotation attached to a span of output text.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('file_path') | Yes | Annotation type; always file_path. |
file_id | string | Yes | Identifier of the referenced file. |
index | integer | Yes | Position of the referenced file in the list of files. |
Function And Custom Tool Call Output
Type: InputTextContent | InputImageContent | InputFileContent
Function Call Item Status
Type: enum ('in_progress', 'completed', 'incomplete')
Function Call Output Content List Param
The function tool call output as content parts (text, image, or file).
Type: array of InputTextContentParam | InputImageContentParamAutoParam | InputFileContentParam
Function Call Output Item Param
The output your code returns for a function tool call.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | null | No | Identifier for this function tool call output; set when the item is returned by the API. |
call_id | string | Yes | Identifier of the function tool call this output answers. (minLength: 1, maxLength: 64) |
type | enum ('function_call_output') | Yes | Item type; always function_call_output. (default: function_call_output) |
output | FunctionCallOutputTextParam | FunctionCallOutputContentListParam | Yes | The function tool call output, as text or content parts. |
status | FunctionCallItemStatus | null | No | Item status: in_progress, completed, or incomplete. Set when the item is returned by the API. |
Function Call Output Status Enum
Type: enum ('in_progress', 'completed', 'incomplete')
Function Call Output Text Param
The function tool call output as a JSON string.
Type: string
Function Call Status
Type: enum ('in_progress', 'completed', 'incomplete')
Function Tool
Defines a function in your own code the model can choose to call.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('function') | Yes | The tool type; always function. (default: function) |
name | string | Yes | Name of the function the model can call. |
description | string | null | No | Describes the function so the model can decide whether to call it. |
parameters | object | null | Yes | JSON Schema object that defines the function's parameters. |
strict | boolean | null | No | Whether the model must produce arguments that match the parameters schema exactly. Defaults to true. |
defer_loading | boolean | No | When true, defers this function so it is discovered on demand through tool search. |
Function Tool Call
A tool call to run a function.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Identifier for this function tool call. |
type | enum ('function_call') | Yes | Item type; always function_call. |
call_id | string | Yes | Identifier the model assigned to this function tool call. (minLength: 1, maxLength: 64) |
namespace | string | No | Namespace of the function to run. |
name | string | Yes | Name of the function to run. |
arguments | string | Yes | Arguments to pass to the function, as a JSON string. |
status | enum ('in_progress', 'completed', 'incomplete') | No | Item status: in_progress, completed, or incomplete. Set when the item is returned by the API. |
Function Tool Call Output
The output your code returns for a function tool call.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Identifier for this function tool call output; set when the item is returned by the API. |
type | enum ('function_call_output') | Yes | Output item type; always function_call_output. |
call_id | string | Yes | Identifier of the function tool call this output answers. |
output | string | array of FunctionAndCustomToolCallOutput | Yes | The result your code produces for the function call, as a string or a list of output content. |
status | enum ('in_progress', 'completed', 'incomplete') | No | Item status: in_progress, completed, or incomplete. Set when the item is returned by the API. |
Function Tool Call Output Resource
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier for this function call output. |
type | enum ('function_call_output') | Yes | Output item type; always function_call_output. |
call_id | string | Yes | Identifier of the function tool call this output answers. |
output | string | array of FunctionAndCustomToolCallOutput | Yes | The result your code produces for the function call, as a string or a list of output content. |
status | FunctionCallOutputStatusEnum | Yes | Item status: in_progress, completed, or incomplete. Set when the item is returned by the API. |
created_by | string | No | Identifier of the actor that created the item. |
Image Detail
Type: enum ('low', 'high', 'auto', 'original')
Include Enum
Specify additional output data to include in the model response. Currently supported values are:
web_search_call.action.sources: Include the sources of the web search tool call.code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items.computer_call_output.output.image_url: Include image urls from the computer call output.file_search_call.results: Include the search results of the file search tool call.message.input_image.image_url: Include image urls from the input message.message.output_text.logprobs: Include logprobs with assistant messages.reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using encrypted reasoning replay.
Type: enum ('file_search_call.results', 'web_search_call.results', 'web_search_call.action.sources', 'message.input_image.image_url', 'computer_call_output.output.image_url', 'code_interpreter_call.outputs', 'reasoning.encrypted_content', 'message.output_text.logprobs')
Input Audio Content
Audio input to the model. Provide inline base64 data, a URL or base64 data URI, or an uploaded file ID.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_audio') | Yes | Content-part type; always input_audio. (default: input_audio) |
input_audio | object | No | Inline base64-encoded audio and its format. |
input_audio.data | string | Yes | Base64-encoded audio data. |
input_audio.format | enum ('wav', 'mp3') | Yes | The format of the encoded audio data. Supports wav and mp3. |
audio_url | string | null | No | URL of the audio to send to the model. Fully qualified URL or base64-encoded data URL. |
file_id | string | null | No | Identifier for the uploaded audio file to send to the model. |
Input Content
Type: InputTextContent | InputImageContent | InputFileContent | InputVideoContent | InputAudioContent | OutputTextContent | RefusalContent
Input File Content
A file provided as input to the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_file') | Yes | Content-part type; always input_file. (default: input_file) |
file_id | string | null | No | Identifier for the file to send to the model. |
filename | string | No | Name of the file passed to the model. |
file_data | string | No | Contents of the file passed to the model. |
file_url | string | No | URL of the file passed to the model. |
detail | FileInputDetail | No | Render detail for the file: low for default rendering, high for higher quality. Defaults to low. |
Input File Content Param
A file provided as input to the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_file') | Yes | Content-part type; always input_file. (default: input_file) |
file_id | string | null | No | Identifier for the file to send to the model. |
filename | string | null | No | Name of the file to send to the model. |
file_data | string | null | No | Base64-encoded file data to send to the model. (maxLength: 73400320) |
file_url | string | null | No | URL of the file to send to the model. |
detail | FileDetailEnum | No | Render detail for the file: low for default rendering, high for higher quality. Defaults to low. |
Input Image Content
An image input to the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_image') | Yes | Content-part type; always input_image. (default: input_image) |
image_url | string | null | No | URL of the image to send to the model. Fully qualified URL or base64-encoded data URL. |
file_id | string | null | No | Identifier for the file to send to the model. |
detail | ImageDetail | No | Render detail for the image: one of high, low, auto, or original. Defaults to auto. |
Input Image Content Param Auto Param
An image input to the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_image') | Yes | Content-part type; always input_image. (default: input_image) |
image_url | string | null | No | URL of the image to send to the model. Fully qualified URL or base64-encoded data URL. (maxLength: 20971520) |
file_id | string | null | No | Identifier for the file to send to the model. |
detail | DetailEnum | null | No | Image detail level. One of high, low, auto, or original. Defaults to auto. |
Input Item
Type: EasyInputMessage | Item | ItemReferenceParam
Input Message
A message provided as input, tagged with a role. developer and system instructions take precedence over user instructions.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('message') | No | Item type; always message. |
role | enum ('user', 'system', 'developer') | Yes | Author role: one of user, system, or developer. |
status | enum ('in_progress', 'completed', 'incomplete') | No | Item status: in_progress, completed, or incomplete. Set when the item is returned by the API. |
content | InputMessageContentList | Yes |
Input Message Content List
An ordered list of input content parts of varying types.
Type: array of InputContent
Input Param
Text, image, or file inputs to the model, used to generate a response.
Type: string | array of InputItem
Input Text Content
Text provided as input to the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_text') | Yes | Content-part type; always input_text. (default: input_text) |
text | string | Yes | The input text. |
Input Text Content Param
Text provided as input to the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_text') | Yes | Content-part type; always input_text. (default: input_text) |
text | string | Yes | The input text. (maxLength: 10485760) |
Input Video Content
Video input to the model. Provide as URL, base64 data URI, or uploaded file ID.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('input_video') | Yes | Object type; always input_video. (default: input_video) |
video_url | string | null | No | URL of the video to send to the model. Fully qualified URL or base64-encoded data URL. |
file_id | string | null | No | Identifier for the file to send to the model. |
fps | number | null | No | Frames per second for video sampling. Defaults to backend-chosen rate. |
Item
Shared schema for items in conversation and response history (input side).
Type: InputMessage | OutputMessage | ComputerToolCall | ComputerCallOutputItemParam | WebSearchToolCallParam | FunctionToolCall | FunctionCallOutputItemParam | ToolSearchCallItemParam | ToolSearchOutputItemParam | ReasoningItemParam
Item Reference Param
A reference to an existing item by ID.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('item_reference') | null | No | Object type; always item_reference. (default: item_reference) |
id | string | Yes | Identifier of the item to reference. |
Key Press Action
A collection of keypresses the model would like to perform.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('keypress') | Yes | Specifies the event type. For a keypress action, this property is always set to keypress. (default: keypress) |
keys | array of string | Yes | The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. |
Log Prob
The log probability of a token.
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | |
logprob | number | null | No | Log probability of this token. May be null when the backend omits the value. |
bytes | array of integer | Yes | |
top_logprobs | array of TopLogProb | Yes |
Message Phase
Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer). When sending follow-up requests, preserve and resend phase on all assistant messages, dropping it can degrade performance. Not used for user messages.
Type: enum ('commentary', 'final_answer')
Metadata
Type: object | null
Model Response Properties
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | No | |
top_logprobs | integer | null | No | 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. (minimum: 0, maximum: 20) |
temperature | number | null | No | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | No | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No | The retention policy for the prompt cache. |
Move Param
A mouse move action.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('move') | Yes | Specifies the event type. For a move action, this property is always set to move. (default: move) |
x | integer | Yes | The x-coordinate to move to. |
y | integer | Yes | The y-coordinate to move to. |
Output Content
Type: OutputTextContent | RefusalContent | ReasoningTextContent
Output Item
Type: OutputMessage | FunctionToolCall | FunctionToolCallOutputResource | WebSearchToolCall | ComputerToolCall | ComputerToolCallOutputResource | ReasoningItem | ToolSearchCall | ToolSearchOutput
Output Message
A message generated by the model.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Identifier for this output message. |
type | enum ('message') | Yes | Item type; always message. |
role | enum ('assistant') | Yes | Author role; always assistant. |
content | array of OutputMessageContent | Yes | The output message content. |
phase | MessagePhase | null | No | |
status | enum ('in_progress', 'completed', 'incomplete') | No | Item status: in_progress, completed, or incomplete. Set when the item is returned by the API. |
Output Message Content
Type: OutputTextContent | RefusalContent
Output Text Content
Text generated by the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('output_text') | Yes | Content-part type; always output_text. (default: output_text) |
text | string | Yes | The generated text. |
annotations | array of Annotation | No | Annotations attached to the text output. |
logprobs | array of LogProb | No |
Prompt
Type: object | null
Reasoning
Configuration options for reasoning.
| Field | Type | Required | Description |
|---|---|---|---|
effort | ReasoningEffort | No | |
summary | enum ('auto', 'concise', 'detailed') | null | No | A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed. |
generate_summary | enum ('auto', 'concise', 'detailed') | null | No | Deprecated: use summary instead. A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed. |
Reasoning Effort
Type: enum ('none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max') | null
Reasoning Item
A record of the model's chain of thought for a turn. When you manage context manually, include these items in input on later turns so the model retains its reasoning.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('reasoning') | Yes | Item type; always reasoning. |
id | string | Yes | Identifier for this reasoning item. |
encrypted_content | string | null | No | Opaque encrypted content for stateless multi-turn replay. Populated when a response is generated with reasoning.encrypted_content in the include parameter. |
summary | array of SummaryTextContent | Yes | Summarized reasoning content. |
content | array of ReasoningTextContent | No | Reasoning text content. |
status | enum ('in_progress', 'completed', 'incomplete') | No | Item status: in_progress, completed, or incomplete. Set when the item is returned by the API. |
Reasoning Item Param
Input form for a reasoning item. The id is optional on input and required on output. The encrypted_content field carries opaque reasoning state for stateless multi-turn replay.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('reasoning') | Yes | Object type; always reasoning. |
id | string | No | Identifier for this reasoning item. Optional on input; required on output. |
encrypted_content | string | null | No | Opaque encrypted content for stateless multi-turn replay. Populated when a response is generated with reasoning.encrypted_content in the include parameter. |
summary | array of SummaryTextContent | Yes | Summarized reasoning content. |
content | array of ReasoningTextContent | No | Reasoning text content. |
status | enum ('in_progress', 'completed', 'incomplete') | No | The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API. |
Reasoning Text Content
Reasoning text emitted by the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('reasoning_text') | Yes | Content-part type; always reasoning_text. (default: reasoning_text) |
text | string | Yes | The reasoning text. |
Refusal Content
A refusal from the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('refusal') | Yes | Object type; always refusal. (default: refusal) |
refusal | string | Yes | The refusal explanation from the model. |
Response
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | Yes | |
top_logprobs | integer | null | No | 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. (minimum: 0, maximum: 20) |
temperature | number | null | Yes | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | Yes | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No | The retention policy for the prompt cache. |
previous_response_id | string | null | No | Identifier of a previous response to continue from. Use this to build multi-turn conversations with server-managed state. Cannot be combined with conversation. |
model | string | Yes | ID of the model used to generate the response. |
reasoning | Reasoning | null | No | |
background | boolean | null | No | Whether to run the response asynchronously in the background. Cannot be combined with stream. (default: false) |
max_tool_calls | integer | null | No | Maximum number of built-in tool calls allowed while generating a response, counted across all built-in tools rather than per tool. The model ignores any calls beyond this limit. (minimum: 1) |
text | ResponseTextParam | No | |
tools | ToolsArray | Yes | |
tool_choice | ToolChoiceParam | Yes | |
prompt | Prompt | No | |
truncation | enum ('auto', 'disabled') | null | No | Truncation strategy for the request. Only disabled (the default) is supported: if the input plus requested output tokens exceed the model's context window, the request fails with a 400 error. The auto strategy is not supported. (default: disabled) |
id | string | Yes | Identifier for this response. |
object | enum ('response') | Yes | Object type; always response. |
status | enum ('completed', 'failed', 'in_progress', 'cancelled', 'queued', 'incomplete') | No | Generation status: one of completed, failed, in_progress, cancelled, queued, or incomplete. |
created_at | number (unixtime) | Yes | Unix timestamp (seconds) for when the response was created. |
completed_at | number (unixtime) | null | No | Unix timestamp (in seconds) when the response completed. Set only when status is completed. |
error | ResponseError | Yes | |
incomplete_details | object | null | Yes | Explains why the response is incomplete. |
output | array of OutputItem | Yes | The items the model generated. Their number and order depend on the response; where SDKs expose it, prefer the output_text helper over indexing into this array. |
instructions | string | array of InputItem | null | Yes | Developer-level instructions inserted at the top of the model's context. When previous_response_id is set, instructions from the prior response are not carried forward, so you can change them on each turn. |
output_text | string | null | No | SDK-only helper that concatenates the text from all output_text items in output. Available in the Python and JavaScript SDKs. |
usage | ResponseUsage | No | |
parallel_tool_calls | boolean | Yes | Whether the model may run tool calls in parallel. (default: true) |
store | boolean | null | No | Whether to persist the generated response so it can be retrieved later and chained from previous_response_id. (default: true) |
conversation | Conversation-2 | null | No | (default: null) |
max_output_tokens | integer | null | No | Upper bound on the number of tokens generated for the response, counting both visible output and reasoning tokens. |
Response Completed Event
Signals that the response has finished and all output is final.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.completed') | Yes | Event type; always response.completed. |
response | Response | Yes | The finished response object. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Content Part Added Event
Signals that a new content part has started within an output item.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.content_part.added') | Yes | Event type; always response.content_part.added. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the content part within the output item. |
part | OutputContent | Yes | The newly opened content part. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Content Part Done Event
Signals that a content part has finished streaming.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.content_part.done') | Yes | Event type; always response.content_part.done. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the content part within the output item. |
sequence_number | integer | Yes | This event's position in the stream. |
part | OutputContent | Yes | The finished content part. |
Response Created Event
Signals that the response has been created and streaming has begun.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.created') | Yes | Event type; always response.created. |
response | Response | Yes | The newly created response object. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Error
Type: object | null
Response Error Code
Error code for the response.
Type: enum ('server_error', 'rate_limit_exceeded', 'container_allocation_disabled', 'invalid_prompt', 'vector_store_timeout', 'invalid_image', 'invalid_image_format', 'invalid_base64_image', 'invalid_image_url', 'image_too_large', 'image_too_small', 'image_parse_error', 'image_content_policy_violation', 'invalid_image_mode', 'image_file_too_large', 'unsupported_image_media_type', 'empty_image_file', 'failed_to_download_image', 'image_file_not_found')
Response Error Event
Reports an error that interrupted the stream.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('error') | Yes | Event type; always error. |
code | string | null | Yes | Machine-readable error code, or null when none applies. |
message | string | Yes | Human-readable error message. |
param | string | null | Yes | Name of the request parameter that caused the error, when applicable. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Failed Event
Signals that the response terminated with a failure.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.failed') | Yes | Event type; always response.failed. |
sequence_number | integer | Yes | This event's position in the stream. |
response | Response | Yes | The response object in its failed state. |
Response Format Json Object
JSON mode: forces the output to be valid JSON. Prefer json_schema where supported. The model only emits JSON if a system or user message instructs it to.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('json_object') | Yes | Response-format type; always json_object. |
Response Format Json Schema Schema
The response-format schema, expressed as a JSON Schema object. See the JSON Schema reference (opens in a new tab) for the format.
Type: object
Response Format Text
Plain-text response format (the default).
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('text') | Yes | Response-format type; always text. |
Response Function Call Arguments Delta Event
Carries an incremental chunk of a function call's argument string.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.function_call_arguments.delta') | Yes | Event type; always response.function_call_arguments.delta. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
sequence_number | integer | Yes | This event's position in the stream. |
delta | string | Yes | The argument-string fragment in this chunk. |
Response Function Call Arguments Done Event
Signals that a function call's arguments are complete.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.function_call_arguments.done') | Yes | |
item_id | string | Yes | Identifier of the related output item. |
name | string | Yes | Name of the called function. |
output_index | integer | Yes | Position of the related output item in the response output array. |
sequence_number | integer | Yes | This event's position in the stream. |
arguments | string | Yes | The complete argument string, as JSON. |
Response In Progress Event
Reports that the response is still being generated.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.in_progress') | Yes | Event type; always response.in_progress. |
response | Response | Yes | The response object as generated so far. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Incomplete Event
Signals that the response ended in an incomplete state.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.incomplete') | Yes | Event type; always response.incomplete. |
response | Response | Yes | The response object in its incomplete state. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Keepalive Event
A transport heartbeat during an idle Responses stream. It carries no model content or token usage.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('keepalive') | Yes | Event type; always keepalive. (default: keepalive) |
sequence_number | integer (int32) | Yes | This event's position in the current SSE connection, not a stored response cursor. |
Response Log Prob
The log probability the model assigned to a token at a position. Higher (less negative) values indicate greater confidence in that choice.
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | A candidate text token. |
logprob | number | Yes | Log probability of this token. |
top_logprobs | array of object | No | The most likely alternative tokens at this position with their log probabilities, up to the number set by top_logprobs (maximum 20). |
top_logprobs[].token | string | No | A candidate text token. |
top_logprobs[].logprob | number | No | Log probability of this token. |
Response Output Item Added Event
Signals that a new output item has started.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.output_item.added') | Yes | Event type; always response.output_item.added. |
output_index | integer | Yes | Position of the related output item in the response output array. |
sequence_number | integer | Yes | This event's position in the stream. |
item | OutputItem | Yes | The newly opened output item. |
Response Output Item Done Event
Signals that an output item has finished streaming.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.output_item.done') | Yes | Event type; always response.output_item.done. |
output_index | integer | Yes | Position of the related output item in the response output array. |
sequence_number | integer | Yes | This event's position in the stream. |
item | OutputItem | Yes | The finished output item. |
Response Output Text Annotation Added Event
Carries an annotation, such as a citation, attached to streamed output text.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.output_text.annotation.added') | Yes | Event type; always response.output_text.annotation.added. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the content part within the output item. |
annotation_index | integer | Yes | Position of this annotation within the content part. |
sequence_number | integer | Yes | This event's position in the stream. |
annotation | object | Yes | The annotation being attached to the output text. |
Response Prompt Variables
Type: object | null
Response Properties
| Field | Type | Required | Description |
|---|---|---|---|
previous_response_id | string | null | No | Identifier of a previous response to continue from. Use this to build multi-turn conversations with server-managed state. Cannot be combined with conversation. |
model | string | No | ID of the model used to generate the response. |
reasoning | Reasoning | null | No | |
background | boolean | null | No | Whether to run the response asynchronously in the background. Cannot be combined with stream. (default: false) |
max_tool_calls | integer | null | No | Maximum number of built-in tool calls allowed while generating a response, counted across all built-in tools rather than per tool. The model ignores any calls beyond this limit. (minimum: 1) |
text | ResponseTextParam | No | |
tools | ToolsArray | No | |
tool_choice | ToolChoiceParam | No | |
prompt | Prompt | No | |
truncation | enum ('auto', 'disabled') | null | No | Truncation strategy for the request. Only disabled (the default) is supported: if the input plus requested output tokens exceed the model's context window, the request fails with a 400 error. The auto strategy is not supported. (default: disabled) |
Response Queued Event
Signals that the response is queued and awaiting processing.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.queued') | Yes | Event type; always response.queued. |
response | Response | Yes | The queued response object. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Reasoning Summary Part Added Event
Signals that a new reasoning-summary part has started.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.reasoning_summary_part.added') | Yes | Event type; always response.reasoning_summary_part.added. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
summary_index | integer | Yes | Position of this summary part within the reasoning summary. |
sequence_number | integer | Yes | This event's position in the stream. |
part | object | Yes | The newly opened summary part. |
part.type | enum ('summary_text') | Yes | Summary-part type; always summary_text. |
part.text | string | Yes | The summary-part text. |
Response Reasoning Summary Part Done Event
Signals that a reasoning-summary part has finished.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.reasoning_summary_part.done') | Yes | Event type; always response.reasoning_summary_part.done. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
summary_index | integer | Yes | Position of this summary part within the reasoning summary. |
sequence_number | integer | Yes | This event's position in the stream. |
part | object | Yes | The finished summary part. |
part.type | enum ('summary_text') | Yes | Summary-part type; always summary_text. |
part.text | string | Yes | The summary-part text. |
Response Reasoning Summary Text Delta Event
Carries an incremental chunk of reasoning-summary text.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.reasoning_summary_text.delta') | Yes | Event type; always response.reasoning_summary_text.delta. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
summary_index | integer | Yes | Position of this summary part within the reasoning summary. |
delta | string | Yes | The summary-text fragment in this chunk. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Reasoning Summary Text Done Event
Signals that a reasoning-summary text block is complete.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.reasoning_summary_text.done') | Yes | Event type; always response.reasoning_summary_text.done. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
summary_index | integer | Yes | Position of this summary part within the reasoning summary. |
text | string | Yes | The complete reasoning-summary text. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Reasoning Text Delta Event
Carries an incremental chunk of reasoning text.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.reasoning_text.delta') | Yes | Event type; always response.reasoning_text.delta. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the reasoning content part within the output item. |
delta | string | Yes | The reasoning-text fragment in this chunk. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Reasoning Text Done Event
Signals that a reasoning text block is complete.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.reasoning_text.done') | Yes | Event type; always response.reasoning_text.done. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the reasoning content part within the output item. |
text | string | Yes | The complete reasoning text. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Refusal Delta Event
Carries an incremental chunk of refusal text.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.refusal.delta') | Yes | Event type; always response.refusal.delta. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the content part within the output item. |
delta | string | Yes | The refusal-text fragment in this chunk. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Refusal Done Event
Signals that the refusal text is complete.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.refusal.done') | Yes | Event type; always response.refusal.done. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the content part within the output item. |
refusal | string | Yes | The complete refusal text. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Stream Event
Type: ResponseCompletedEvent | ResponseContentPartAddedEvent | ResponseContentPartDoneEvent | ResponseCreatedEvent | ResponseErrorEvent | ResponseFunctionCallArgumentsDeltaEvent | ResponseFunctionCallArgumentsDoneEvent | ResponseInProgressEvent | ResponseFailedEvent | ResponseIncompleteEvent | ResponseOutputItemAddedEvent | ResponseOutputItemDoneEvent | ResponseReasoningSummaryPartAddedEvent | ResponseReasoningSummaryPartDoneEvent | ResponseReasoningSummaryTextDeltaEvent | ResponseReasoningSummaryTextDoneEvent | ResponseReasoningTextDeltaEvent | ResponseReasoningTextDoneEvent | ResponseRefusalDeltaEvent | ResponseRefusalDoneEvent | ResponseTextDeltaEvent | ResponseTextDoneEvent | ResponseWebSearchCallCompletedEvent | ResponseWebSearchCallInProgressEvent | ResponseWebSearchCallSearchingEvent | ResponseOutputTextAnnotationAddedEvent | ResponseQueuedEvent
Response Stream Options
Type: object | null
Response Stream Wire Event
A response event or transport heartbeat delivered over a Responses SSE connection.
Type: ResponseCompletedEvent | ResponseContentPartAddedEvent | ResponseContentPartDoneEvent | ResponseCreatedEvent | ResponseErrorEvent | ResponseFunctionCallArgumentsDeltaEvent | ResponseFunctionCallArgumentsDoneEvent | ResponseInProgressEvent | ResponseFailedEvent | ResponseIncompleteEvent | ResponseOutputItemAddedEvent | ResponseOutputItemDoneEvent | ResponseReasoningSummaryPartAddedEvent | ResponseReasoningSummaryPartDoneEvent | ResponseReasoningSummaryTextDeltaEvent | ResponseReasoningSummaryTextDoneEvent | ResponseReasoningTextDeltaEvent | ResponseReasoningTextDoneEvent | ResponseRefusalDeltaEvent | ResponseRefusalDoneEvent | ResponseTextDeltaEvent | ResponseTextDoneEvent | ResponseWebSearchCallCompletedEvent | ResponseWebSearchCallInProgressEvent | ResponseWebSearchCallSearchingEvent | ResponseOutputTextAnnotationAddedEvent | ResponseQueuedEvent | ResponseKeepaliveEvent
Response Text Delta Event
Carries an incremental chunk of output text.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.output_text.delta') | Yes | Event type; always response.output_text.delta. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the content part within the output item. |
delta | string | Yes | The output-text fragment in this chunk. |
sequence_number | integer | Yes | This event's position in the stream. |
logprobs | array of ResponseLogProb | Yes | Log probabilities for the tokens in this chunk. |
Response Text Done Event
Signals that a block of output text is complete.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.output_text.done') | Yes | Event type; always response.output_text.done. |
item_id | string | Yes | Identifier of the related output item. |
output_index | integer | Yes | Position of the related output item in the response output array. |
content_index | integer | Yes | Position of the content part within the output item. |
text | string | Yes | The complete output text. |
sequence_number | integer | Yes | This event's position in the stream. |
logprobs | array of ResponseLogProb | Yes | Log probabilities for the tokens in this chunk. |
Response Text Param
Configuration options for a text response from the model. Can be plain text or structured JSON data.
| Field | Type | Required | Description |
|---|---|---|---|
format | TextResponseFormatConfiguration | No |
Response Usage
Token usage for the response: input tokens, output tokens (with a breakdown), and the total.
| Field | Type | Required | Description |
|---|---|---|---|
input_tokens | integer | Yes | Number of input tokens. For responses that run hosted tools, this is the sum of the reported input-token count for each model iteration, with accounting adjustments applied per iteration. |
input_tokens_details | object | Yes | Breakdown of the input tokens. |
input_tokens_details.cached_tokens | integer | Yes | Input tokens served from cache. |
output_tokens | integer | Yes | Number of output tokens. |
output_tokens_details | object | Yes | Breakdown of the output tokens. |
output_tokens_details.reasoning_tokens | integer | Yes | Number of reasoning tokens, counted within the output token total. |
total_tokens | integer | Yes | Total tokens used. |
video_frames_processed | integer | No | Number of video frames processed for this segmentation request. Present only for video segmentation responses; used for per-frame billing. |
images_processed | integer | No | Number of images processed for this segmentation request. Present only for image segmentation responses; used for per-image billing. |
Response Web Search Call Completed Event
Signals that a web search call has finished.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.web_search_call.completed') | Yes | Event type; always response.web_search_call.completed. |
output_index | integer | Yes | Position of the related output item in the response output array. |
item_id | string | Yes | Identifier of the related output item. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Web Search Call In Progress Event
Signals that a web search call has started.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.web_search_call.in_progress') | Yes | Event type; always response.web_search_call.in_progress. |
output_index | integer | Yes | Position of the related output item in the response output array. |
item_id | string | Yes | Identifier of the related output item. |
sequence_number | integer | Yes | This event's position in the stream. |
Response Web Search Call Searching Event
Signals that a web search call is actively searching.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('response.web_search_call.searching') | Yes | Event type; always response.web_search_call.searching. |
output_index | integer | Yes | Position of the related output item in the response output array. |
item_id | string | Yes | Identifier of the related output item. |
sequence_number | integer | Yes | This event's position in the stream. |
Screenshot Param
A screenshot action.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('screenshot') | Yes | Specifies the event type. For a screenshot action, this property is always set to screenshot. (default: screenshot) |
Scroll Param
A scroll action.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('scroll') | Yes | Specifies the event type. For a scroll action, this property is always set to scroll. (default: scroll) |
x | integer | Yes | The x-coordinate where the scroll occurred. |
y | integer | Yes | The y-coordinate where the scroll occurred. |
scroll_x | integer | Yes | The horizontal scroll distance. |
scroll_y | integer | Yes | The vertical scroll distance. |
Service Tier
Type: enum ('auto', 'default', 'flex', 'scale', 'priority') | null
Summary Text Content
A summary text from the model.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('summary_text') | Yes | Object type; always summary_text. (default: summary_text) |
text | string | Yes | A summary of the reasoning output from the model so far. |
Text Response Format Configuration
Constrains the model's text output format. Use { "type": "json_schema" } for Structured Outputs (matches your JSON schema); the default is { "type": "text" }. { "type": "json_object" } selects the older JSON mode. Prefer json_schema.
Type: ResponseFormatText | TextResponseFormatJsonSchema | ResponseFormatJsonObject
Text Response Format Json Schema
JSON Schema response format. Used to generate structured JSON responses.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('json_schema') | Yes | Response-format type; always json_schema. |
description | string | No | Describes what the format is for; the model uses it to decide how to respond. |
name | string | Yes | Name of the response format. Allowed characters: a-z, A-Z, 0-9, underscores, and dashes, up to 64 characters. |
schema | ResponseFormatJsonSchemaSchema | Yes | |
strict | boolean | null | No | When true, the model must produce output that strictly conforms to the JSON Schema in the schema field. Only a subset of JSON Schema is supported in this mode. (default: false) |
Token Counts Body
| Field | Type | Required | Description |
|---|---|---|---|
metadata | Metadata | No | |
top_logprobs | integer | No | An integer between 0 and 20 giving the number of top alternative tokens to return at each position, each with its log probability. (minimum: 0, maximum: 20) |
temperature | number | null | No | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. (minimum: 0, maximum: 2, default: 1) |
top_p | number | null | No | Nucleus sampling: only tokens whose cumulative probability is at most this value are considered. Must be greater than 0; values <= 0 return HTTP 400. Set this or temperature, not both. (minimum: 0, maximum: 1, default: 1) |
user | string | No | Deprecated. Being replaced by safety_identifier and prompt_cache_key; use prompt_cache_key to retain caching benefits. A stable end-user identifier used to improve cache hit rates and help detect abuse. |
safety_identifier | string | No | A stable identifier that helps detect users who may be violating usage policies. Use a string that uniquely identifies each user, up to 64 characters; hash a username or email so you do not send identifying information. (maxLength: 64) |
prompt_cache_key | string | No | Groups similar requests to improve cache hit rates. Replaces the user field. |
service_tier | ServiceTier | No | |
prompt_cache_retention | enum ('in_memory', '24h') | null | No | The retention policy for the prompt cache. |
previous_response_id | string | null | No | Identifier of a previous response to continue from. Use this to build multi-turn conversations with server-managed state. Cannot be combined with conversation. |
model | string | No | ID of the model used to generate the response. |
reasoning | Reasoning | null | No | |
background | boolean | null | No | Whether to run the response asynchronously in the background. Cannot be combined with stream. (default: false) |
max_tool_calls | integer | null | No | Maximum number of built-in tool calls allowed while generating a response, counted across all built-in tools rather than per tool. The model ignores any calls beyond this limit. (minimum: 1) |
text | ResponseTextParam | No | |
tools | ToolsArray | No | |
tool_choice | ToolChoiceParam | No | |
prompt | Prompt | No | |
truncation | enum ('auto', 'disabled') | null | No | Truncation strategy for the request. Only disabled (the default) is supported: if the input plus requested output tokens exceed the model's context window, the request fails with a 400 error. The auto strategy is not supported. (default: disabled) |
client_metadata | object | null | No | Optional client-provided request metadata. Accepted for compatibility and ignored. |
input | InputParam | No | |
include | array of IncludeEnum | null | No | Additional output data to return in the response. Use message.output_text.logprobs to return token-level log probabilities on output text (set together with top_logprobs and a reasoning.effort of none), and reasoning.encrypted_content to return encrypted reasoning items for stateless multi-turn replay. |
parallel_tool_calls | boolean | null | No | Whether the model may issue multiple tool calls in a single turn. (default: true) |
store | boolean | null | No | Whether to persist the generated response so it can be retrieved later and chained from previous_response_id. (default: true) |
instructions | string | null | No | Developer-level instructions inserted at the top of the model's context. When previous_response_id is set, instructions from the prior response are not carried forward, so you can change them on each turn. |
stream | boolean | null | No | If true, the response is streamed to the client as server-sent events as it is generated. Cannot be combined with background. (default: false) |
stream_options | ResponseStreamOptions | No | |
max_output_tokens | integer | null | No | Upper bound on the number of tokens generated for the response, counting both visible output and reasoning tokens. Minimum is 16; values above the model's configured maximum, or that exceed the remaining context window, return a 400 error. (minimum: 16) |
Token Counts Resource
| Field | Type | Required | Description |
|---|---|---|---|
object | enum ('response.input_tokens') | Yes | (default: response.input_tokens) |
input_tokens | integer | Yes | Tokens in the fully rendered model input, including resolved history and server prompt scaffolding. This is a context-size measurement, not cumulative response usage. |
Tool
A tool the model can use while generating a response.
Type: FunctionTool | ComputerTool | WebSearchTool | ToolSearchToolParam
Tool Choice Options
auto lets the model choose between replying with a message and making one or more tool calls.
Type: enum ('auto')
Tool Choice Param
How the model selects tools while generating a response. See tools for how to declare the tools it may call.
Type: ToolChoiceOptions
Tool Search Call
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('tool_search_call') | Yes | The type of the item. Always tool_search_call. (default: tool_search_call) |
id | string | Yes | The unique ID of the tool search call item. |
call_id | string | null | Yes | The unique ID of the tool search call generated by the model. |
execution | ToolSearchExecutionType | Yes | Whether tool search was executed by the server or by the client. |
arguments | Yes | Arguments used for the tool search call. | |
status | FunctionCallStatus | Yes | The status of the tool search call item that was recorded. |
created_by | string | No | The identifier of the actor that created the item. |
Tool Search Call Item Param
| Field | Type | Required | Description |
|---|---|---|---|
id | string | null | No | The unique ID of this tool search call. |
call_id | string | null | No | The unique ID of the tool search call generated by the model. (minLength: 1, maxLength: 64) |
type | enum ('tool_search_call') | Yes | The item type. Always tool_search_call. (default: tool_search_call) |
execution | ToolSearchExecutionType | No | Whether tool search was executed by the server or by the client. |
arguments | EmptyModelParam | Yes | The arguments supplied to the tool search call. |
status | FunctionCallItemStatus | null | No | The status of the tool search call. |
Tool Search Execution Type
Type: enum ('server', 'client')
Tool Search Output
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('tool_search_output') | Yes | The type of the item. Always tool_search_output. (default: tool_search_output) |
id | string | Yes | The unique ID of the tool search output item. |
call_id | string | null | Yes | The unique ID of the tool search call generated by the model. |
execution | ToolSearchExecutionType | Yes | Whether tool search was executed by the server or by the client. |
tools | array of Tool | Yes | The loaded tool definitions returned by tool search. |
status | FunctionCallOutputStatusEnum | Yes | The status of the tool search output item that was recorded. |
created_by | string | No | The identifier of the actor that created the item. |
Tool Search Output Item Param
| Field | Type | Required | Description |
|---|---|---|---|
id | string | null | No | The unique ID of this tool search output. |
call_id | string | null | No | The unique ID of the tool search call generated by the model. (minLength: 1, maxLength: 64) |
type | enum ('tool_search_output') | Yes | The item type. Always tool_search_output. (default: tool_search_output) |
execution | ToolSearchExecutionType | No | Whether tool search was executed by the server or by the client. |
tools | array of Tool | Yes | The loaded tool definitions returned by the tool search output. |
status | FunctionCallItemStatus | null | No | The status of the tool search output. |
Tool Search Tool Param
Hosted or BYOT tool search configuration for deferred tools.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('tool_search') | Yes | The type of the tool. Always tool_search. (default: tool_search) |
execution | ToolSearchExecutionType | No | Whether tool search is executed by the server or by the client. |
description | string | null | No | Description shown to the model for a client-executed tool search tool. |
parameters | EmptyModelParam | null | No | Parameter schema for a client-executed tool search tool. |
Tools Array
An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. We support the following categories of tools: - Built-in tools: Tools that extend the model's capabilities, such as web search. - Function calls (custom tools): Functions that you define, enabling the model to call your own code with strongly typed arguments and outputs.
Type: array of Tool
Top Log Prob
The top log probability of a token.
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | |
logprob | number | null | No | Log probability of this token. May be null when the backend omits the value. |
bytes | array of integer | Yes |
Type Param
An action to type in text.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('type') | Yes | Specifies the event type. For a type action, this property is always set to type. (default: type) |
text | string | Yes | The text to type. |
Url Citation Body
Citation that points to a web resource used to ground the response.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('url_citation') | Yes | Annotation type; always url_citation. (default: url_citation) |
url | string | Yes | URL of the cited web resource. |
start_index | integer | Yes | Character offset where the cited span begins in the output text. |
end_index | integer | Yes | Character offset where the cited span ends in the output text. |
title | string | Yes | Title of the cited web resource. |
Wait Param
A wait action.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('wait') | Yes | Specifies the event type. For a wait action, this property is always set to wait. (default: wait) |
Web Search Action Find
A find_in_page action: the model searches for a pattern within an opened page.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('find_in_page') | Yes | Action type; always find_in_page. |
url | string (uri) | Yes | URL of the page that was searched. |
pattern | string | Yes | Text pattern searched for within the page. |
Web Search Action Open Page
An open_page action: opens a specific URL from the search results.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('open_page') | Yes | Action type; always open_page. |
url | string (uri) | null | No | URL the model opened. |
Web Search Action Search
A search action: runs one or more web search queries.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('search') | Yes | Action type; always search. |
query | string | Yes | [DEPRECATED] The search query. Use queries instead. |
queries | array of string | No | The search queries issued in this action. |
sources | array of object | No | Sources consulted during the search. |
sources[].type | enum ('url') | Yes | Source type; always url. |
sources[].url | string (uri) | Yes | URL of the source. |
downstream_request_id | string | No | Identifier for the downstream search request, surfaced for debugging. |
Web Search Approximate Location
Type: object | null
Web Search Result Item
One result returned by a web search tool call.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | No | The result type. |
title | string | No | Title of the result. |
url | string | No | URL of the result. |
snippet | string | No | Text snippet excerpted from the result. |
Web Search Tool
Search the Internet for sources related to the prompt.
| Field | Type | Required | Description |
|---|---|---|---|
type | enum ('web_search', 'web_search_2025_08_26') | Yes | The tool type; one of web_search or web_search_2025_08_26. (default: web_search) |
filters | object | null | No | Filters that narrow the search. |
user_location | WebSearchApproximateLocation | No | |
search_context_size | enum ('low', 'medium', 'high') | No | How much context window space the search may use; one of low, medium, or high, defaulting to medium. (default: medium) |
Web Search Tool Call
The results of a web search tool call.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Identifier for this web search tool call. |
type | enum ('web_search_call') | Yes | Item type; always web_search_call. |
status | enum ('in_progress', 'searching', 'completed', 'failed') | Yes | Status of the web search tool call. |
action | WebSearchActionSearch | WebSearchActionOpenPage | WebSearchActionFind | Yes | The specific action taken in this web search call, such as search, open_page, or find_in_page. |
results | array of WebSearchResultItem | null | No | Results from the web search tool call. Populated only when the request's include array contains web_search_call.results. |
Web Search Tool Call Param
A web search tool call replayed back as input. Identical to the response-side item except that id may be omitted: a stateless client replaying a prior hosted-search turn did not receive one to send back.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Identifier for this web search tool call. Optional on input; omit it when replaying a turn for which no identifier was issued. |
type | enum ('web_search_call') | Yes | Item type; always web_search_call. |
status | enum ('in_progress', 'searching', 'completed', 'failed') | Yes | Status of the web search tool call. |
action | WebSearchActionSearch | WebSearchActionOpenPage | WebSearchActionFind | Yes | The specific action taken in this web search call, such as search, open_page, or find_in_page. |
results | array of WebSearchResultItem | null | No | Results from the web search tool call. Populated only when the request's include array contains web_search_call.results. |
Mirrored from dev.meta.ai/docs/api-reference/responses/schemas (synced Oct 30, 2026). Text and examples © Meta. Live demos run on Muse Muse's key.