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.

Compaction Body

A compaction item produced when earlier conversation context is compacted into an encrypted summary.

Field	Type	Required	Description
`type`	`enum ('compaction')`	Yes	Object type; always `compaction`. (default: compaction)
`id`	`string`	Yes	Identifier for the compaction item.
`encrypted_content`	`string`	Yes	Encrypted content for stateless multi-turn replay.
`created_by`	`string`	No	Identifier for the actor that created the item.

Compaction Summary Item Param

A compaction item produced when earlier conversation context is compacted into an encrypted summary.

Field	Type	Required	Description
`id`	`string` \| `null`	No
`type`	`enum ('compaction')`	Yes	Object type; always `compaction`. (default: compaction)
`encrypted_content`	`string`	Yes	Encrypted content for stateless multi-turn replay. (maxLength: 10485760)

Computer Action

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
`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
`status`	`FunctionCallItemStatus` \| `null`	No

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
`message`	`string` \| `null`	No

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.

Context Management Param

Field	Type	Required	Description
`type`	`string`	Yes	Context-management entry type; only `compaction` is currently supported.
`compact_threshold`	`integer` \| `null`	No

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
`top_p`	`number` \| `null`	No
`user`	`string`	No	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

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
`top_p`	`number` \| `null`	No
`user`	`string`	No	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
`previous_response_id`	`string` \| `null`	No
`model`	`string`	No	ID of the model used to generate the response.
`reasoning`	`Reasoning` \| `null`	No
`background`	`boolean` \| `null`	No
`max_tool_calls`	`integer` \| `null`	No
`text`	`ResponseTextParam`	No
`tools`	`ToolsArray`	No
`tool_choice`	`ToolChoiceParam`	No
`prompt`	`Prompt`	No
`truncation`	`enum ('auto', 'disabled')` \| `null`	No
`frequency_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from repeating tokens it has already used often, reducing verbatim repetition. (minimum: -2, maximum: 2, default: 0)
`presence_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from reusing tokens that have already appeared, encouraging it to introduce new topics. (minimum: -2, maximum: 2, default: 0)
`client_metadata`	`object` \| `null`	No
`input`	`InputParam`	No
`include`	array of `IncludeEnum` \| `null`	No
`parallel_tool_calls`	`boolean` \| `null`	No
`store`	`boolean` \| `null`	No
`instructions`	`string` \| `null`	No
`stream`	`boolean` \| `null`	No
`stream_options`	`ResponseStreamOptions`	No
`context_management`	array of `ContextManagementParam` \| `null`	No
`max_output_tokens`	`integer` \| `null`	No

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 } ]`

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
`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

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
`parameters`	`object` \| `null`	Yes
`strict`	`boolean` \| `null`	No
`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
`file_id`	`string` \| `null`	No

Input Content

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
`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
`filename`	`string` \| `null`	No
`file_data`	`string` \| `null`	No
`file_url`	`string` \| `null`	No
`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
`file_id`	`string` \| `null`	No
`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
`file_id`	`string` \| `null`	No
`detail`	`DetailEnum` \| `null`	No

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
`file_id`	`string` \| `null`	No
`fps`	`number` \| `null`	No

Item

Shared schema for items in conversation and response history (input side).

Item Reference Param

A reference to an existing item by ID.

Field	Type	Required	Description
`type`	`enum ('item_reference')` \| `null`	No
`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
`token`	`string`	Yes
`logprob`	`number` \| `null`	No
`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
`temperature`	`number` \| `null`	No
`top_p`	`number` \| `null`	No
`user`	`string`	No	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

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

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
`effort`	`ReasoningEffort`	No
`summary`	`enum ('auto', 'concise', 'detailed')` \| `null`	No
`generate_summary`	`enum ('auto', 'concise', 'detailed')` \| `null`	No

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
`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
`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
`temperature`	`number` \| `null`	Yes
`top_p`	`number` \| `null`	Yes
`user`	`string`	No	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
`previous_response_id`	`string` \| `null`	No
`model`	`string`	Yes	ID of the model used to generate the response.
`reasoning`	`Reasoning` \| `null`	No
`background`	`boolean` \| `null`	No
`max_tool_calls`	`integer` \| `null`	No
`text`	`ResponseTextParam`	No
`tools`	`ToolsArray`	Yes
`tool_choice`	`ToolChoiceParam`	Yes
`prompt`	`Prompt`	No
`truncation`	`enum ('auto', 'disabled')` \| `null`	No
`frequency_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from repeating tokens it has already used often, reducing verbatim repetition. (minimum: -2, maximum: 2, default: 0)
`presence_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from reusing tokens that have already appeared, encouraging it to introduce new topics. (minimum: -2, maximum: 2, default: 0)
`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
`error`	`ResponseError`	Yes
`incomplete_details`	`object` \| `null`	Yes
`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
`output_text`	`string` \| `null`	No
`usage`	`ResponseUsage`	No
`parallel_tool_calls`	`boolean`	Yes	Whether the model may run tool calls in parallel. (default: true)
`store`	`boolean` \| `null`	No
`conversation`	`Conversation-2` \| `null`	No
`max_output_tokens`	`integer` \| `null`	No

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', '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
`message`	`string`	Yes	Human-readable error message.
`param`	`string` \| `null`	Yes
`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 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 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
`model`	`string`	No	ID of the model used to generate the response.
`reasoning`	`Reasoning` \| `null`	No
`background`	`boolean` \| `null`	No
`max_tool_calls`	`integer` \| `null`	No
`text`	`ResponseTextParam`	No
`tools`	`ToolsArray`	No
`tool_choice`	`ToolChoiceParam`	No
`prompt`	`Prompt`	No
`truncation`	`enum ('auto', 'disabled')` \| `null`	No
`frequency_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from repeating tokens it has already used often, reducing verbatim repetition. (minimum: -2, maximum: 2, default: 0)
`presence_penalty`	`number`	No	A number between -2.0 and 2.0. Positive values discourage the model from reusing tokens that have already appeared, encouraging it to introduce new topics. (minimum: -2, maximum: 2, default: 0)

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

Response Stream Options

Type: object | null

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

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
`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
`call_id`	`string` \| `null`	No
`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

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
`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
`call_id`	`string` \| `null`	No
`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

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
`parameters`	`EmptyModelParam` \| `null`	No

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
`token`	`string`	Yes
`logprob`	`number` \| `null`	No
`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
`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