GET

/v1/schemas/openai/chat/responses/compact?beta=true?kind=output

Accept:

kind outputactivity chathash e3926874…extracted Nov 5, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `898eefefea6b5dc52da42f5628a64a0ffba65d850282e1cb59ab459f7e356f92` { "fetchedAt": 1793851833, "extractorVersion": "1", "verifiedAt": null }

Response body

6 properties · 5 required · 176 $defs

property	type	description	constraints
id*	string	The unique identifier for the compacted response.
object*	enum	The object type. Always `response.compaction`.	response.compaction · default: "response.compaction"
output*	BetaOutputItem[]	The compacted list of output items. This is a list of all user messages, followed by a single compaction item.
created_at*	integer	Unix timestamp (in seconds) when the compacted conversation was created.	format: unixtime
usage*	BetaResponseUsage	Token accounting for the compaction pass, including cached, reasoning, and total tokens.
image	BetaResolvedImageOptions

Types

176 $defs

BetaAdditionalToolsobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `additional_tools`.	additional_tools · default: "additional_tools"
id*	string	The unique ID of the additional tools item.
role*	enum	The role that provided the additional tools.	unknown \| user \| assistant \| system \| critic \| discriminator · +2 more
tools*	BetaTool[]	The additional tool definitions made available at this item.

BetaAgentMessageobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `agent_message`.	agent_message · default: "agent_message"
id*	string	The unique ID of the agent message.
author*	string	The sending agent identity.
recipient*	string	The destination agent identity.
content*	BetaInputTextContent \| BetaOutputTextContent \| BetaTextContent[]	Encrypted content sent between agents.

BetaAgentTagobject

agent_name*

string

The canonical name of the agent that produced this item.

BetaAnnotationFile citation | URL citation | Container file citation | …

An annotation that applies to a span of output text.

BetaApplyPatchCallOutputStatusenum

completed | failed

BetaApplyPatchCreateFileOperationobject

Instruction describing how to create a file via the apply_patch tool.

type*	enum	Create a new file with the provided diff.	create_file · default: "create_file"
path*	string	Path of the file to create.
diff*	string	Diff to apply.

BetaApplyPatchDeleteFileOperationobject

Instruction describing how to delete a file via the apply_patch tool.

type*	enum	Delete the specified file.	delete_file · default: "delete_file"
path*	string	Path of the file to delete.

BetaApplyPatchToolCallobject

A tool call that applies file diffs by creating, deleting, or updating files.

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `apply_patch_call`.	apply_patch_call · default: "apply_patch_call"
id*	string	The unique ID of the apply patch tool call. Populated when this item is returned via API.
call_id*	string	The unique ID of the apply patch tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the apply patch tool call. One of `in_progress` or `completed`.	in_progress \| completed
operation*	Apply patch create file operation \| Apply patch delete file operation \| Apply patch update file operation	One of the create_file, delete_file, or update_file operations applied via apply_patch.
created_by	string	The ID of the entity that created this tool call.

BetaApplyPatchToolCallOutputobject

The output emitted by an apply patch tool call.

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `apply_patch_call_output`.	apply_patch_call_output · default: "apply_patch_call_output"
id*	string	The unique ID of the apply patch tool call output. Populated when this item is returned via API.
call_id*	string	The unique ID of the apply patch tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the apply patch tool call output. One of `completed` or `failed`.	completed \| failed
output	string	Optional textual output returned by the apply patch tool.	nullable
created_by	string	The ID of the entity that created this tool call output.

BetaApplyPatchToolParamobject

Allows the assistant to create, delete, or update files using unified diffs.

type*	enum	The type of the tool. Always `apply_patch`.	apply_patch · default: "apply_patch"
allowed_callers	BetaCallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

BetaApplyPatchUpdateFileOperationobject

Instruction describing how to update a file via the apply_patch tool.

type*	enum	Update an existing file with the provided diff.	update_file · default: "update_file"
path*	string	Path of the file to update.
diff*	string	Diff to apply.

BetaApproximateLocationobject

type*	enum	The type of location approximation. Always `approximate`.	approximate · default: "approximate"
country	string	The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.	nullable
region	string	Free text input for the region of the user, e.g. `California`.	nullable
city	string	Free text input for the city of the user, e.g. `San Francisco`.	nullable
timezone	string	The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.	nullable

BetaAutoCodeInterpreterToolParamobject

Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

type*	enum	Always `auto`.	auto · default: "auto"
file_ids	string[]	An optional list of uploaded files to make available to your code.	items ≤ 50
memory_limit	enum	The memory limit for the code interpreter container.	1g \| 4g \| 16g \| 64g · nullable
network_policy	object \| object	Network access policy for the container.

BetaCacheWriteTokensDetailsobject

ttl_30m_tokens*	integer	The number of input tokens written with 30-minute retention.
ttl_12h_tokens*	integer	The number of input tokens written with 12-hour retention.

BetaCallableToolAllowedCallerenum

direct | programmatic

BetaClickParamobject

A click action.

type*	enum	Specifies the event type. For a click action, this property is always `click`.	click · default: "click"
button*	enum	Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.	left \| right \| wheel \| back \| forward
x*	integer	The x-coordinate where the click occurred.
y*	integer	The y-coordinate where the click occurred.
keys	string[]	The keys being held while clicking.	nullable

BetaCodeInterpreterOutputImageobject

The image output from the code interpreter.

type*	enum	The type of the output. Always `image`.	image · default: "image"
url*	string	The URL of the image output from the code interpreter.	format: uri

BetaCodeInterpreterOutputLogsobject

The logs output from the code interpreter.

type*	enum	The type of the output. Always `logs`.	logs · default: "logs"
logs*	string	The logs output from the code interpreter.

BetaCodeInterpreterToolobject

A tool that runs Python code to help generate a response to a prompt.

type*	enum	The type of the code interpreter tool. Always `code_interpreter`.	code_interpreter
container*	string \| CodeInterpreterToolAuto	The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional `memory_limit` setting.
allowed_callers	BetaCallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

BetaCodeInterpreterToolCallobject

A tool call to run code.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the code interpreter tool call. Always `code_interpreter_call`.	code_interpreter_call · default: "code_interpreter_call"
id*	string	The unique ID of the code interpreter tool call.
status*	enum	The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.	in_progress \| completed \| incomplete \| interpreting \| failed
container_id*	string	The ID of the container used to run the code.
code*	string	The code to run, or null if not available.	nullable
outputs*	BetaCodeInterpreterOutputLogs \| BetaCodeInterpreterOutputImage[]	The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available.	nullable

BetaCompactionBodyobject

A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact).

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `compaction`.	compaction · default: "compaction"
id*	string	The unique ID of the compaction item.
encrypted_content*	string	The encrypted content that was produced by compaction.
created_by	string	The identifier of the actor that created the item.

BetaComparisonFilterobject

A filter used to compare a specified attribute key to a given value using a defined comparison operation.

type*	enum	Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: equals - `ne`: not equal - `gt`: greater than - `gte`: greater than or equal - `lt`: less than - `lte`: less than or equal - `in`: in - `nin`: not in	eq \| ne \| gt \| gte \| lt \| lte · +2 more · default: "eq"
key*	string	The key to compare against the value.
value*	string \| number \| boolean \| …	The value to compare against the attribute key; supports string, number, or boolean types.

BetaCompoundFilterobject

Combine multiple filters using `and` or `or`.

type*	enum	Type of operation: `and` or `or`.	and \| or
filters*	BetaComparisonFilter \| any[]	Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.

BetaComputerActionClick | DoubleClick | Drag | …

BetaComputerActionListBetaComputerAction[]

Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields.

BetaComputerCallOutputStatusenum

completed | incomplete | failed

BetaComputerCallSafetyCheckParamobject

A pending safety check for the computer call.

id*	string	The ID of the pending safety check.
code	string	The type of the pending safety check.	nullable
message	string	Details about the pending safety check.	nullable

BetaComputerEnvironmentenum

windows | mac | linux | ubuntu | browser

BetaComputerScreenshotContentobject

A screenshot of a computer.

type*	enum	Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`.	computer_screenshot · default: "computer_screenshot"
image_url*	string	The URL of the screenshot image.	format: uri · nullable
file_id*	string	The identifier of an uploaded file that contains the screenshot.	nullable
detail*	enum	The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.	low \| high \| auto \| original
prompt_cache_breakpoint	BetaPromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

BetaComputerScreenshotImageobject

A computer screenshot image used with the computer use tool.

type*	enum	Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`.	computer_screenshot · default: "computer_screenshot"
image_url	string	The URL of the screenshot image.	format: uri
file_id	string	The identifier of an uploaded file that contains the screenshot.

BetaComputerToolobject

A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).

type*

enum

The type of the computer tool. Always `computer`.

computer · default: "computer"

BetaComputerToolCallobject

A tool call to a computer use tool. See the [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the computer call. Always `computer_call`.	computer_call · default: "computer_call"
id*	string	The unique ID of the computer call.
call_id*	string	An identifier used when responding to the tool call with output.
action	Click \| DoubleClick \| Drag \| …
actions	BetaComputerAction[]	Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields.
pending_safety_checks*	BetaComputerCallSafetyCheckParam[]	The pending safety checks for the computer call.
status*	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

BetaComputerToolCallOutputobject

The output of a computer tool call.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the computer tool call output. Always `computer_call_output`.	computer_call_output · default: "computer_call_output"
id	string	The ID of the computer tool call output.
call_id*	string	The ID of the computer tool call that produced the output.
acknowledged_safety_checks	BetaComputerCallSafetyCheckParam[]	The safety checks reported by the API that have been acknowledged by the developer.
output*	BetaComputerScreenshotImage	A computer screenshot image used with the computer use tool.
status	enum	The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API.	in_progress \| completed \| incomplete

BetaComputerToolCallOutputResourceComputer tool call output | object

BetaComputerUsePreviewToolobject

A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use).

type*	enum	The type of the computer use tool. Always `computer_use_preview`.	computer_use_preview · default: "computer_use_preview"
environment*	enum	The type of computer environment to control.	windows \| mac \| linux \| ubuntu \| browser
display_width*	integer	The width of the computer display.
display_height*	integer	The height of the computer display.

BetaContainerAutoParamobject

type*	enum	Automatically creates a container for this request	container_auto · default: "container_auto"
file_ids	string[]	An optional list of uploaded files to make available to your code.	items ≤ 50
memory_limit	enum	The memory limit for the container.	1g \| 4g \| 16g \| 64g · nullable
network_policy	object \| object	Network access policy for the container.
skills	BetaSkillReferenceParam \| BetaInlineSkillParam[]	An optional list of skills referenced by id or inline data.	items ≤ 200

BetaContainerFileCitationBodyobject

A citation for a container file used to generate a model response.

type*	enum	The type of the container file citation. Always `container_file_citation`.	container_file_citation · default: "container_file_citation"
container_id*	string	The ID of the container file.
file_id*	string	The ID of the file.
start_index*	integer	The index of the first character of the container file citation in the message.
end_index*	integer	The index of the last character of the container file citation in the message.
filename*	string	The filename of the container file cited.

BetaContainerNetworkPolicyAllowlistParamobject

type*	enum	Allow outbound network access only to specified domains. Always `allowlist`.	allowlist · default: "allowlist"
allowed_domains*	string[]	A list of allowed domains when type is `allowlist`.	items ≥ 1
domain_secrets	BetaContainerNetworkPolicyDomainSecretParam[]	Optional domain-scoped secrets for allowlisted domains.	items ≥ 1

BetaContainerNetworkPolicyDisabledParamobject

type*

enum

Disable outbound network access. Always `disabled`.

disabled · default: "disabled"

BetaContainerNetworkPolicyDomainSecretParamobject

domain*	string	The domain associated with the secret.	length ≥ 1
name*	string	The name of the secret to inject for the domain.	length ≥ 1
value*	string	The secret value to inject for the domain.	length ≥ 1 · length ≤ 10485760

BetaContainerReferenceParamobject

type*	enum	References a container created with the /v1/containers endpoint	container_reference · default: "container_reference"
container_id*	string	The ID of the referenced container.

BetaContainerReferenceResourceobject

Represents a container created with /v1/containers.

type*	enum	The environment type. Always `container_reference`.	container_reference · default: "container_reference"
container_id*	string

BetaCoordParamobject

An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.

x*	integer	The x-coordinate.
y*	integer	The y-coordinate.

BetaCustomGrammarFormatParamobject

A grammar defined by the user.

type*	enum	Grammar format. Always `grammar`.	grammar · default: "grammar"
syntax*	enum	The syntax of the grammar definition. One of `lark` or `regex`.	lark \| regex
definition*	string	The grammar definition.

BetaCustomTextFormatParamobject

Unconstrained free-form text.

type*

enum

Unconstrained text format. Always `text`.

text · default: "text"

BetaCustomToolCallobject

A call to a custom tool created by the model.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the custom tool call. Always `custom_tool_call`.	custom_tool_call
id	string	The unique ID of the custom tool call in the OpenAI platform.
call_id*	string	An identifier used to map this custom tool call to a tool call output.
caller	object \| object	The execution context that produced this tool call.	nullable
namespace	string	The namespace of the custom tool being called.
name*	string	The name of the custom tool being called.
input*	string	The input for the custom tool call generated by the model.
async	boolean	Whether the custom tool call runs asynchronously.

BetaCustomToolCallOutputobject

The output of a custom tool call from your code, being sent back to the model.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the custom tool call output. Always `custom_tool_call_output`.	custom_tool_call_output
id	string	The unique ID of the custom tool call output in the OpenAI platform.
call_id*	string	The call ID, used to map this custom tool call output to a custom tool call.
caller	object \| object	The execution context that produced this tool call.	nullable
output*	string \| BetaFunctionAndCustomToolCallOutput[]	The output from the custom tool call generated by your code. Can be a string or an list of output content.

BetaCustomToolCallOutputResourceCustom tool call output | object

BetaCustomToolParamobject

A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)

type*	enum	The type of the custom tool. Always `custom`.	custom · default: "custom"
name*	string	The name of the custom tool, used to identify it in tool calls.
async	boolean	Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
description	string	Optional description of the custom tool, used to provide more context.
format	Text format \| Grammar format	The input format for the custom tool. Default is unconstrained text.
defer_loading	boolean	Whether this tool should be deferred and discovered via tool search.
allowed_callers	BetaCallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

BetaDirectToolCallCallerobject

type*

enum

direct · default: "direct"

BetaDirectToolCallCallerParamobject

type*

enum

The caller type. Always `direct`.

direct · default: "direct"

BetaDoubleClickActionobject

A double click action.

type*	enum	Specifies the event type. For a double click action, this property is always set to `double_click`.	double_click · default: "double_click"
x*	integer	The x-coordinate where the double click occurred.
y*	integer	The y-coordinate where the double click occurred.
keys*	string[]	The keys being held while double-clicking.	nullable

BetaDragParamobject

A drag action.

type*	enum	Specifies the event type. For a drag action, this property is always set to `drag`.	drag · default: "drag"
path*	BetaCoordParam[]	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 } ] ```
keys	string[]	The keys being held while dragging the mouse.	nullable

BetaEncryptedContentobject

Opaque encrypted content that Responses API decrypts inside trusted model execution.

type*	enum	The type of the input item. Always `encrypted_content`.	encrypted_content · default: "encrypted_content"
encrypted_content*	string	Opaque encrypted content.

BetaFileCitationBodyobject

A citation to a file.

type*	enum	The type of the file citation. Always `file_citation`.	file_citation · default: "file_citation"
file_id*	string	The ID of the file.
index*	integer	The index in the output text at which to insert the file citation.
filename*	string	The filename of the file cited.

BetaFilePathobject

A path to a file.

type*	enum	The type of the file path. Always `file_path`.	file_path
file_id*	string	The ID of the file.
index*	integer	The index of the file in the list of files.

BetaFileSearchToolobject

A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search).

type*	enum	The type of the file search tool. Always `file_search`.	file_search · default: "file_search"
vector_store_ids*	string[]	The IDs of the vector stores to search.
max_num_results	integer	The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options	BetaRankingOptions	Ranking options for search.
filters	Comparison Filter \| Compound Filter	A filter to apply.	nullable

BetaFileSearchToolCallobject

The results of a file search tool call. See the [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information.

agent	BetaAgentTag	The agent that produced this item.	nullable
id*	string	The unique ID of the file search tool call.
type*	enum	The type of the file search tool call. Always `file_search_call`.	file_search_call
status*	enum	The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`,	in_progress \| searching \| completed \| incomplete \| failed
queries*	string[]	The queries used to search for files.
results	object[]	The results of the file search tool call.	nullable

BetaFiltersComparison Filter | Compound Filter

BetaFunctionAndCustomToolCallOutputInput text | Input image | Input file

BetaFunctionCallOutputStatusEnumenum

in_progress | completed | incomplete

BetaFunctionShellActionobject

Execute a shell command.

commands*	string[]
timeout_ms*	integer	Optional timeout in milliseconds for the commands.	nullable
max_output_length*	integer	Optional maximum number of characters to return from each command.	nullable

BetaFunctionShellCallobject

A tool call that executes one or more shell commands in a managed environment.

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `shell_call`.	shell_call · default: "shell_call"
id*	string	The unique ID of the shell tool call. Populated when this item is returned via API.
call_id*	string	The unique ID of the shell tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
action*	BetaFunctionShellAction	The shell commands and limits that describe how to run the tool call.
status*	enum	The status of the shell call. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete
environment*	Local Environment \| Container Reference		nullable
created_by	string	The ID of the entity that created this tool call.

BetaFunctionShellCallOutputobject

The output of a shell tool call that was emitted.

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the shell call output. Always `shell_call_output`.	shell_call_output · default: "shell_call_output"
id*	string	The unique ID of the shell call output. Populated when this item is returned via API.
call_id*	string	The unique ID of the shell tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
status*	enum	The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete
output*	BetaFunctionShellCallOutputContent[]	An array of shell call output contents
max_output_length*	integer	The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output.	nullable
created_by	string	The identifier of the actor that created the item.

BetaFunctionShellCallOutputContentobject

The content of a shell tool call output that was emitted.

stdout*	string	The standard output that was captured.
stderr*	string	The standard error output that was captured.
outcome*	Shell call timeout outcome \| Shell call exit outcome	Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk.
created_by	string	The identifier of the actor that created the item.

BetaFunctionShellCallOutputExitOutcomeobject

Indicates that the shell commands finished and returned an exit code.

type*	enum	The outcome type. Always `exit`.	exit · default: "exit"
exit_code*	integer	Exit code from the shell process.

BetaFunctionShellCallOutputStatusEnumenum

in_progress | completed | incomplete

BetaFunctionShellCallOutputTimeoutOutcomeobject

Indicates that the shell call exceeded its configured time limit.

type*

enum

The outcome type. Always `timeout`.

timeout · default: "timeout"

BetaFunctionShellCallStatusenum

in_progress | completed | incomplete

BetaFunctionShellToolParamobject

A tool that allows the model to execute shell commands.

type*	enum	The type of the shell tool. Always `shell`.	shell · default: "shell"
environment	object \| object \| object		nullable
allowed_callers	BetaCallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

BetaFunctionToolobject

Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling).

type*	enum	The type of the function tool. Always `function`.	function · default: "function"
name*	string	The name of the function to call.
async	boolean
description	string	A description of the function. Used by the model to determine whether or not to call the function.	nullable
parameters*	object	A JSON schema object describing the parameters of the function.	nullable
output_schema	object	A JSON schema object describing the JSON value encoded in string outputs for this function.	nullable
strict*	boolean	Whether strict parameter validation is enforced for this function tool.	nullable
defer_loading	boolean	Whether this function is deferred and loaded via tool search.
allowed_callers	BetaCallableToolAllowedCaller[]	The tool invocation context(s).	nullable

BetaFunctionToolCallobject

A tool call to run a function. See the [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information.

agent	BetaAgentTag	The agent that produced this item.	nullable
id	string	The unique ID of the function tool call.
type*	enum	The type of the function tool call. Always `function_call`.	function_call
call_id*	string	The unique ID of the function tool call generated by the model.
caller	object \| object	The execution context that produced this tool call.	nullable
namespace	string	The namespace of the function to run.
name*	string	The name of the function to run.
arguments*	string	A JSON string of the arguments to pass to the function.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete
async	boolean	Whether the function tool call runs asynchronously.

BetaFunctionToolCallOutputobject

The output of a function tool call.

agent	BetaAgentTag	The agent that produced this item.	nullable
id	string	The unique ID of the function tool call output. Populated when this item is returned via API.
type*	enum	The type of the function tool call output. Always `function_call_output`.	function_call_output
call_id	string	The unique ID of the function tool call generated by the model.
name	string	The name of the tool that produced the output.
namespace	string	The namespace of the tool that produced the output.
caller	object \| object	The execution context that produced this tool call.	nullable
output*	string \| BetaFunctionAndCustomToolCallOutput[]	The output from the function call generated by your code. Can be a string or an list of output content.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

BetaFunctionToolCallOutputResourceFunction tool call output | object

BetaFunctionToolParamobject

name*	string		length ≥ 1 · length ≤ 128
description	string		nullable
parameters	BetaEmptyModelParam		nullable
strict	boolean	Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise.	nullable
type*	enum		function · default: "function"
async	boolean	Whether the tool response can be returned asynchronously versus immediately returned on next response creation.
output_schema	object	A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs.	nullable
defer_loading	boolean	Whether this function should be deferred and discovered via tool search.
allowed_callers	BetaCallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable

BetaHTTPErrorobject

type*	enum	http_error · default: "http_error"
code*	integer
message*	string

BetaHybridSearchOptionsobject

embedding_weight*	number	The weight of the embedding in the reciprocal ranking fusion.
text_weight*	number	The weight of the text in the reciprocal ranking fusion.

BetaImageGenToolobject

A tool that generates images using the GPT image models.

type*	enum	The type of the image generation tool. Always `image_generation`.	image_generation
model	string \| enum
complexity	enum	Computation spent planning the image, independently of rendering quality. Overrides the outer response's `reasoning.effort` for image generation. When omitted, inherits a supported outer reasoning effort or uses the image model's configured default. For SVG ou…	low \| medium \| high
quality	enum	The quality of the generated image. The GPT image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Default: `auto`.	low \| medium \| high \| xhigh \| max \| auto · default: "auto"
size	string \| enum	The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` str…	default: "auto"
output_format	enum	The output format of the generated image. One of `png`, `webp`, `jpeg`, `gif`, or `svg`. Default: `png`. GIF and SVG output require a model that supports the selected format. GIF output does not support partial image streaming (`partial_images` greater than `0…	png \| webp \| jpeg \| gif \| svg · default: "png"
frame_count	integer	Number of GIF frames. Requires `output_format` to be `gif`. Default: 9.	2 ≤ n ≤ 16 · default: 9
frame_duration_ms	integer	Duration of each GIF frame in milliseconds, rounded to 10 ms. Requires `output_format` to be `gif`. Default: 200.	20 ≤ n ≤ 2000 · default: 200
svg	BetaSvgParam	SVG author model settings. Requires `output_format` to be `svg`. When SVG model selection is enabled, omitting this object uses the outer response model. Otherwise, the default SVG author is used and explicit model overrides are unavailable.
output_compression	integer	Compression level for the output image. Default: 100.	0 ≤ n ≤ 100 · default: 100
moderation	enum	Moderation level for the generated image. Default: `auto`.	auto \| low · default: "auto"
background	enum	Allows to set transparency for the background of the generated image(s). Must be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image.	transparent \| opaque \| auto · default: "auto"
input_fidelity	enum	Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to…	high \| low · nullable
input_image_mask	object	Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).
partial_images	integer	Number of partial images to generate in streaming mode, from 0 (default value) to 3.	0 ≤ n ≤ 3 · default: 0
action	enum	Whether to generate a new image or edit an existing image. Default: `auto`.	generate \| edit \| auto

BetaImageGenToolCallobject

An image generation request made by the model.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the image generation call. Always `image_generation_call`.	image_generation_call
id*	string	The unique ID of the image generation call.
status*	enum	The status of the image generation call.	in_progress \| completed \| generating \| failed
result*	string	The generated image encoded in base64.	nullable
error	BetaImageGenToolCallError	Details of a moderation failure, when available.
size	string \| enum	The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`.	nullable
quality	enum	The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`.	low \| medium \| high \| xhigh \| max \| auto · nullable
action	enum	The action used for image generation.	generate \| edit \| auto · nullable
background	enum	The background setting used for generation.	transparent \| opaque \| auto · nullable
output_format	enum	The output format used for generation.	png \| webp \| jpeg \| gif \| svg · nullable
svg_usage	BetaSvgUsage
revised_prompt	string	The prompt that was used after any model prompt rewriting.	nullable

BetaImageGenToolCallErrorobject

code*	string	The error code.	nullable
type*	string	The error type.
message*	string	A description of the error.
param*	string	The related request parameter.	nullable
moderation_details	BetaImageGenToolCallModerationDetails	Public details for a `moderation_blocked` error, when available.

BetaImageGenToolCallModerationDetailsobject

moderation_stage*	enum	The stage where moderation blocked the image generation call.	input \| output \| unknown
categories*	string[]	Public moderation categories. New category values may be added over time.

BetaInlineSkillParamobject

type*	enum	Defines an inline skill for this request.	inline · default: "inline"
name*	string	The name of the skill.
description*	string	The description of the skill.
source*	BetaInlineSkillSourceParam	Inline skill payload

BetaInlineSkillSourceParamobject

Inline skill payload

type*	enum	The type of the inline skill source. Must be `base64`.	base64 · default: "base64"
media_type*	enum	The media type of the inline skill payload. Must be `application/zip`.	application/zip · default: "application/zip"
data*	string	Base64-encoded skill zip bundle.	length ≥ 1 · length ≤ 70254592

Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to…

high | low

BetaInputFileContentobject

A file input to the model.

type*	enum	The type of the input item. Always `input_file`.	input_file · default: "input_file"
file_id	string	The ID of the file to be sent to the model.	nullable
filename	string	The name of the file to be sent to the model.
file_data	string	The content of the file to be sent to the model.
prompt_cache_breakpoint	BetaPromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.
file_url	string	The URL of the file to be sent to the model.	format: uri
detail	enum	The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to…	auto \| low \| high

BetaInputImageContentobject

An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision).

type*	enum	The type of the input item. Always `input_image`.	input_image · default: "input_image"
image_url	string	The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.	format: uri · nullable
file_id	string	The ID of the file to be sent to the model.	nullable
detail*	enum	The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.	low \| high \| auto \| original
prompt_cache_breakpoint	BetaPromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

BetaInputTextContentobject

A text input to the model.

type*	enum	The type of the input item. Always `input_text`.	input_text · default: "input_text"
text*	string	The text input to the model.
prompt_cache_breakpoint	BetaPromptCacheBreakpointConfig	Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

BetaKeyPressActionobject

A collection of keypresses the model would like to perform.

type*	enum	Specifies the event type. For a keypress action, this property is always set to `keypress`.	keypress · default: "keypress"
keys*	string[]	The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

BetaLocalEnvironmentParamobject

type*	enum	Use a local computer environment.	local · default: "local"
skills	BetaLocalSkillParam[]	An optional list of skills.	items ≤ 200

BetaLocalEnvironmentResourceobject

Represents the use of a local environment to perform shell actions.

type*

enum

The environment type. Always `local`.

local · default: "local"

BetaLocalShellExecActionobject

Execute a shell command on the server.

type*	enum	The type of the local shell action. Always `exec`.	exec · default: "exec"
command*	string[]	The command to run.
timeout_ms	integer	Optional timeout in milliseconds for the command.	nullable
working_directory	string	Optional working directory to run the command in.	nullable
env*	object	Environment variables to set for the command.
user	string	Optional user to run the command as.	nullable

BetaLocalShellToolCallobject

A tool call to run a command on the local shell.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the local shell call. Always `local_shell_call`.	local_shell_call
id*	string	The unique ID of the local shell call.
call_id*	string	The unique ID of the local shell tool call generated by the model.
action*	BetaLocalShellExecAction	Execute a shell command on the server.
status*	enum	The status of the local shell call.	in_progress \| completed \| incomplete

BetaLocalShellToolCallOutputobject

The output of a local shell tool call.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the local shell tool call output. Always `local_shell_call_output`.	local_shell_call_output
id*	string	The unique ID of the local shell tool call generated by the model.
output*	string	A JSON string of the output of the local shell tool call.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`.	in_progress \| completed \| incomplete · nullable

BetaLocalShellToolParamobject

A tool that allows the model to execute shell commands in a local environment.

type*

enum

The type of the local shell tool. Always `local_shell`.

local_shell · default: "local_shell"

BetaLocalSkillParamobject

name*	string	The name of the skill.
description*	string	The description of the skill.
path*	string	The path to the directory containing the skill.

BetaLogProbobject

The log probability of a token.

token*	string
logprob*	number
bytes*	integer[]
top_logprobs*	BetaTopLogProb[]

BetaMCPApprovalRequestobject

A request for human approval of a tool invocation.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the item. Always `mcp_approval_request`.	mcp_approval_request
id*	string	The unique ID of the approval request.
server_label*	string	The label of the MCP server making the request.
name*	string	The name of the tool to run.
arguments*	string	A JSON string of arguments for the tool.

BetaMCPApprovalResponseResourceobject

A response to an MCP approval request.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the item. Always `mcp_approval_response`.	mcp_approval_response
id*	string	The unique ID of the approval response
approval_request_id*	string	The ID of the approval request being answered.
approve*	boolean	Whether the request was approved.
reason	string	Optional reason for the decision.	nullable

BetaMCPListToolsobject

A list of tools available on an MCP server.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the item. Always `mcp_list_tools`.	mcp_list_tools
id*	string	The unique ID of the list.
server_label*	string	The label of the MCP server.
tools*	BetaMCPListToolsTool[]	The tools available on the server.
error	string	Error message if the server could not list tools.	nullable

BetaMCPListToolsToolobject

A tool available on an MCP server.

name*	string	The name of the tool.
description	string	The description of the tool.	nullable
input_schema*	object	The JSON schema describing the tool's input.
annotations	object	Additional annotations about the tool.	nullable

BetaMCPProtocolErrorobject

type*	enum	mcp_protocol_error · default: "mcp_protocol_error"
code*	integer
message*	string

BetaMCPToolobject

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).

type*	enum	The type of the MCP tool. Always `mcp`.	mcp
server_label*	string	A label for this MCP server, used to identify it in tool calls.
server_url	string	The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided.	format: uri
connector_id	enum	Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).	connector_dropbox \| connector_gmail \| connector_googlecalendar \| connector_googledrive \| connector_microsoftteams \| connector_outlookcalendar · +2 more · deprecated
tunnel_id	string	The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided.
authorization	string	An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here.
server_description	string	Optional description of the MCP server, used to provide more context.
headers	object	Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.	nullable
allowed_tools	string[] \| MCP tool filter	List of allowed tool names or a filter object.	nullable
allowed_callers	BetaCallableToolAllowedCaller[]	The tool invocation context(s).	items ≥ 1 · nullable
require_approval	MCP tool approval filter \| enum	Specify which of the MCP server's tools require approval.	default: "always" · nullable
defer_loading	boolean	Whether this MCP tool is deferred and discovered via tool search.

BetaMCPToolCallobject

An invocation of a tool on an MCP server.

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the item. Always `mcp_call`.	mcp_call
id*	string	The unique ID of the tool call.
server_label*	string	The label of the MCP server running the tool.
name*	string	The name of the tool that was run.
arguments*	string	A JSON string of the arguments passed to the tool.
output	string	The output from the tool call.	nullable
error	object \| object \| object	The error from the tool call, if any.	nullable
status	enum	The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`.	in_progress \| completed \| incomplete \| calling \| failed
approval_request_id	string	Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call.	nullable

BetaMCPToolCallErrorobject | object | object

BetaMCPToolCallStatusenum

in_progress | completed | incomplete | calling | failed

BetaMCPToolExecutionErrorobject

type*	enum		mcp_tool_execution_error · default: "mcp_tool_execution_error"
content*	any

BetaMCPToolFilterobject

A filter object to specify which tools are allowed.

tool_names	string[]	List of allowed tool names.
read_only	boolean	Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter.

BetaMessagePhaseenum

Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can deg…

commentary | final_answer

BetaMessageRoleenum

BetaMoveParamobject

A mouse move action.

type*	enum	Specifies the event type. For a move action, this property is always set to `move`.	move · default: "move"
x*	integer	The x-coordinate to move to.
y*	integer	The y-coordinate to move to.
keys	string[]	The keys being held while moving the mouse.	nullable

BetaMultiAgentActionenum

BetaMultiAgentCallobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the multi-agent call. Always `multi_agent_call`.	multi_agent_call · default: "multi_agent_call"
id*	string	The unique ID of the multi-agent call item.
call_id*	string	The unique ID linking this call to its output.
action*	enum	The multi-agent action to execute.	spawn_agent \| interrupt_agent \| list_agents \| send_message \| followup_task \| wait_agent
arguments*	string	The JSON string of arguments generated for the action.

BetaMultiAgentCallOutputobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the multi-agent result. Always `multi_agent_call_output`.	multi_agent_call_output · default: "multi_agent_call_output"
id*	string	The unique ID of the multi-agent call output item.
call_id*	string	The unique ID of the multi-agent call.
action*	enum	The multi-agent action that produced this result.	spawn_agent \| interrupt_agent \| list_agents \| send_message \| followup_task \| wait_agent
output*	BetaOutputTextContent[]	Text output returned by the multi-agent action.

BetaNamespaceToolParamobject

Groups function/custom tools under a shared namespace.

type*	enum	The type of the tool. Always `namespace`.	namespace · default: "namespace"
name*	string	The namespace name used in tool calls (for example, `crm`).	length ≥ 1
description*	string	A description of the namespace shown to the model.
tools*	BetaFunctionToolParam \| BetaCustomToolParam[]	The function/custom tools available inside this namespace.	items ≥ 1

BetaOutputItemOutput message | File search tool call | Function tool call | …

BetaOutputMessageobject

An output message from the model.

agent	BetaAgentTag	The agent that produced this item.	nullable
id*	string	The unique ID of the output message.
type*	enum	The type of the output message. Always `message`.	message
role*	enum	The role of the output message. Always `assistant`.	assistant
content*	BetaOutputMessageContent[]	The content of the output message.
phase	enum	Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can deg…	commentary \| final_answer · nullable
status*	enum	The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API.	in_progress \| completed \| incomplete

BetaOutputMessageContentOutput text | Refusal

BetaOutputTextContentobject

A text output from the model.

type*	enum	The type of the output text. Always `output_text`.	output_text · default: "output_text"
text*	string	The text output from the model.
annotations*	BetaAnnotation[]	The annotations of the text output.
logprobs	BetaLogProb[]

BetaProgramobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `program`.	program · default: "program"
id*	string	The unique ID of the program item.
call_id*	string	The stable call ID of the program item.
code*	string	The JavaScript source executed by programmatic tool calling.
fingerprint*	string	Opaque program replay fingerprint that must be round-tripped.

BetaProgrammaticToolCallingParamobject

type*

enum

The type of the tool. Always `programmatic_tool_calling`.

programmatic_tool_calling · default: "programmatic_tool_calling"

BetaProgramOutputobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `program_output`.	program_output · default: "program_output"
id*	string	The unique ID of the program output item.
call_id*	string	The call ID of the program item.
result*	string	The result produced by the program item.
status*	enum	The terminal status of the program output item.	completed \| incomplete

BetaProgramOutputStatusenum

completed | incomplete

BetaProgramToolCallCallerobject

type*	enum		program · default: "program"
caller_id*	string	The call ID of the program item that produced this tool call.

BetaProgramToolCallCallerParamobject

type*	enum	The caller type. Always `program`.	program · default: "program"
caller_id*	string	The call ID of the program item that produced this tool call.	length ≥ 1 · length ≤ 64

BetaPromptCacheBreakpointConfigobject

Marks the exact end of a reusable prompt prefix. When `ttl` is omitted, the breakpoint inherits the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block.

mode*	enum	The breakpoint mode. Always `explicit`.	explicit · default: "explicit"
ttl	enum	The minimum lifetime of this cache breakpoint. Defaults to the request TTL.	30m \| 12h

BetaRankerVersionTypeenum

auto | default-2024-11-15

BetaRankingOptionsobject

ranker	enum	The ranker to use for the file search.	auto \| default-2024-11-15
score_threshold	number	The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.
hybrid_search	BetaHybridSearchOptions	Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

BetaReasoningEffortEnumenum

BetaReasoningItemobject

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://developers.op…

agent	BetaAgentTag	The agent that produced this item.	nullable
type*	enum	The type of the object. Always `reasoning`.	reasoning
id*	string	The unique identifier of the reasoning content.
encrypted_content	string	The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests.	nullable
summary*	BetaSummaryTextContent[]	Reasoning summary content.
content	BetaReasoningTextContent[]	Reasoning text content.
status	enum	The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.	in_progress \| completed \| incomplete

BetaReasoningTextContentobject

Reasoning text from the model.

type*	enum	The type of the reasoning text. Always `reasoning_text`.	reasoning_text · default: "reasoning_text"
text*	string	The reasoning text from the model.

BetaRefusalContentobject

A refusal from the model.

type*	enum	The type of the refusal. Always `refusal`.	refusal · default: "refusal"
refusal*	string	The refusal explanation from the model.

BetaResolvedImageContextCompressionEnumenum

enabled | disabled

BetaResolvedImageOptionsobject

context_compression*

enum

Effective image context optimization policy.

enabled | disabled

BetaResponseUsageobject

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

input_tokens*	integer	The number of input tokens.
input_tokens_details*	object	A detailed breakdown of the input tokens.
output_tokens*	integer	The number of output tokens.
output_tokens_details*	object	A detailed breakdown of the output tokens.
total_tokens*	integer	The total number of tokens used.

BetaScreenshotParamobject

A screenshot action.

type*

enum

Specifies the event type. For a screenshot action, this property is always set to `screenshot`.

screenshot · default: "screenshot"

BetaScrollParamobject

A scroll action.

type*	enum	Specifies the event type. For a scroll action, this property is always set to `scroll`.	scroll · default: "scroll"
x*	integer	The x-coordinate where the scroll occurred.
y*	integer	The y-coordinate where the scroll occurred.
scroll_x*	integer	The horizontal scroll distance.
scroll_y*	integer	The vertical scroll distance.
keys	string[]	The keys being held while scrolling.	nullable

BetaSearchContentTypeenum

text | image

BetaSearchContextSizeenum

low | medium | high

BetaSkillReferenceParamobject

type*	enum	References a skill created with the /v1/skills endpoint.	skill_reference · default: "skill_reference"
skill_id*	string	The ID of the referenced skill.	length ≥ 1 · length ≤ 64
version	string	Optional skill version. Use a positive integer or 'latest'. Omit for default.

BetaSummaryTextContentobject

A summary text from the model.

type*	enum	The type of the object. Always `summary_text`.	summary_text · default: "summary_text"
text*	string	A summary of the reasoning output from the model so far.

BetaSvgParamobject

model	string		length ≥ 1
reasoning	BetaSvgReasoningParam	Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.	nullable

BetaSvgReasoningParamobject

Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.

effort

enum

Controls how much effort the model should spend on reasoning for this request.

BetaSvgUsageobject

model*	string
input_tokens*	integer
output_tokens*	integer
total_tokens*	integer
reasoning_tokens*	integer

BetaTextContentobject

A text content.

type*	enum		text · default: "text"
text*	string

BetaToolFunction | File search | Computer | …

A tool that can be used to generate a response.

BetaToolCallCallerobject | object

The execution context that produced this tool call.

BetaToolCallCallerParamobject | object

The execution context that produced this tool call.

BetaToolSearchCallobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `tool_search_call`.	tool_search_call · default: "tool_search_call"
id*	string	The unique ID of the tool search call item.
call_id*	string	The unique ID of the tool search call generated by the model.	nullable
execution*	enum	Whether tool search was executed by the server or by the client.	server \| client
arguments*	any	Arguments used for the tool search call.
status*	enum	The status of the tool search call item that was recorded.	in_progress \| completed \| incomplete
created_by	string	The identifier of the actor that created the item.

BetaToolSearchExecutionTypeenum

server | client

BetaToolSearchOutputobject

agent	BetaAgentTag	The agent that produced this item.
type*	enum	The type of the item. Always `tool_search_output`.	tool_search_output · default: "tool_search_output"
id*	string	The unique ID of the tool search output item.
call_id*	string	The unique ID of the tool search call generated by the model.	nullable
execution*	enum	Whether tool search was executed by the server or by the client.	server \| client
tools*	BetaTool[]	The loaded tool definitions returned by tool search.
status*	enum	The status of the tool search output item that was recorded.	in_progress \| completed \| incomplete
created_by	string	The identifier of the actor that created the item.

BetaToolSearchToolParamobject

Hosted or BYOT tool search configuration for deferred tools.

type*	enum	The type of the tool. Always `tool_search`.	tool_search · default: "tool_search"
execution	enum	Whether tool search is executed by the server or by the client.	server \| client
description	string	Description shown to the model for a client-executed tool search tool.	nullable
parameters	BetaEmptyModelParam	Parameter schema for a client-executed tool search tool.	nullable

BetaTopLogProbobject

The top log probability of a token.

token*	string
logprob*	number
bytes*	integer[]

BetaTypeParamobject

An action to type in text.

type*	enum	Specifies the event type. For a type action, this property is always set to `type`.	type · default: "type"
text*	string	The text to type.

BetaUrlCitationBodyobject

A citation for a web resource used to generate a model response.

type*	enum	The type of the URL citation. Always `url_citation`.	url_citation · default: "url_citation"
url*	string	The URL of the web resource.	format: uri
start_index*	integer	The index of the first character of the URL citation in the message.
end_index*	integer	The index of the last character of the URL citation in the message.
title*	string	The title of the web resource.

BetaVectorStoreFileAttributesobject

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characte…

nullable

BetaWaitParamobject

A wait action.

type*

enum

Specifies the event type. For a wait action, this property is always set to `wait`.

wait · default: "wait"

BetaWebSearchActionFindobject

Action type "find_in_page": Searches for a pattern within a loaded page.

type*	enum	The action type.	find_in_page
url*	string	The URL of the page searched for the pattern.	format: uri
pattern*	string	The pattern or text to search for within the page.

BetaWebSearchActionOpenPageobject

Action type "open_page" - Opens a specific URL from search results.

type*	enum	The action type.	open_page
url	string	The URL opened by the model.	format: uri · nullable

BetaWebSearchActionSearchobject

Action type "search" - Performs a web search query.

type*	enum	The action type.	search
query	string	The search query.	deprecated
queries	string[]	The search queries.
sources	Web search source[]	The sources used in the search.

BetaWebSearchApproximateLocationobject

The approximate location of the user.

type	enum	The type of location approximation. Always `approximate`.	approximate · default: "approximate"
country	string	The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.	nullable
region	string	Free text input for the region of the user, e.g. `California`.	nullable
city	string	Free text input for the city of the user, e.g. `San Francisco`.	nullable
timezone	string	The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.	nullable

BetaWebSearchCallStatusenum

in_progress | searching | completed | failed | incomplete

BetaWebSearchPreviewToolobject

This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).

type*	enum	The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.	web_search_preview \| web_search_preview_2025_03_11 · default: "web_search_preview"
user_location	BetaApproximateLocation	The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass `{"type": "approximate"}` without location fields. To localize results, provide the relevant location fields.	nullable
search_context_size	enum	High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.	low \| medium \| high
search_content_types	BetaSearchContentType[]

BetaWebSearchToolobject

Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).

type*	enum	The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.	web_search \| web_search_2025_08_26 · default: "web_search"
external_web_access	boolean	Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.	default: true
filters	object	Filters for the search.	nullable
user_location	object	The approximate location of the user.	nullable
search_context_size	enum	High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.	low \| medium \| high · default: "medium"

BetaWebSearchToolCallobject

The results of a web search tool call. See the [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information.

agent	BetaAgentTag	The agent that produced this item.	nullable
id*	string	The unique ID of the web search tool call.
type*	enum	The type of the web search tool call. Always `web_search_call`.	web_search_call
status*	enum	The status of the web search tool call.	in_progress \| searching \| completed \| failed \| incomplete
action*	Search action \| Open page action \| Find action	An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page).

ComparisonFilterValueItemsstring | number

Validate a payload

before you spend tokens

shell

$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"openai","endpointId":"responses/compact?beta=true","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}

/v1/schemas/openai/chat/responses/compact?beta=true?kind=output

Response body

Types

BetaAdditionalToolsobject

BetaAgentMessageobject

BetaAgentTagobject

BetaAnnotationFile citation | URL citation | Container file citation | …

BetaApplyPatchCallOutputStatusenum

BetaApplyPatchCallStatusenum

BetaApplyPatchCreateFileOperationobject

BetaApplyPatchDeleteFileOperationobject

BetaApplyPatchToolCallobject

BetaApplyPatchToolCallOutputobject

BetaApplyPatchToolParamobject

BetaApplyPatchUpdateFileOperationobject

BetaApproximateLocationobject

BetaAutoCodeInterpreterToolParamobject

BetaCacheWriteTokensDetailsobject

BetaCallableToolAllowedCallerenum

BetaClickButtonTypeenum

BetaClickParamobject

BetaCodeInterpreterOutputImageobject

BetaCodeInterpreterOutputLogsobject

BetaCodeInterpreterToolobject

BetaCodeInterpreterToolCallobject

BetaCompactionBodyobject

BetaComparisonFilterobject

BetaCompoundFilterobject

BetaComputerActionClick | DoubleClick | Drag | …

BetaComputerActionListBetaComputerAction[]

BetaComputerCallOutputStatusenum

BetaComputerCallSafetyCheckParamobject

BetaComputerEnvironmentenum

BetaComputerScreenshotContentobject

BetaComputerScreenshotImageobject

BetaComputerToolobject

BetaComputerToolCallobject

BetaComputerToolCallOutputobject

BetaComputerToolCallOutputResourceComputer tool call output | object

BetaComputerUsePreviewToolobject

BetaContainerAutoParamobject

BetaContainerFileCitationBodyobject

BetaContainerMemoryLimitenum

BetaContainerNetworkPolicyAllowlistParamobject

BetaContainerNetworkPolicyDisabledParamobject

BetaContainerNetworkPolicyDomainSecretParamobject

BetaContainerReferenceParamobject

BetaContainerReferenceResourceobject

BetaCoordParamobject

BetaCustomGrammarFormatParamobject

BetaCustomTextFormatParamobject

BetaCustomToolCallobject

BetaCustomToolCallOutputobject

BetaCustomToolCallOutputResourceCustom tool call output | object

BetaCustomToolParamobject

BetaDirectToolCallCallerobject

BetaDirectToolCallCallerParamobject

BetaDoubleClickActionobject

BetaDragParamobject

BetaEmptyModelParamobject

BetaEncryptedContentobject

BetaFileCitationBodyobject

BetaFileInputDetailenum

BetaFilePathobject

BetaFileSearchToolobject

BetaFileSearchToolCallobject

BetaFiltersComparison Filter | Compound Filter

BetaFunctionAndCustomToolCallOutputInput text | Input image | Input file

BetaFunctionCallOutputStatusEnumenum

BetaFunctionCallStatusenum

BetaFunctionShellActionobject

BetaFunctionShellCallobject

BetaFunctionShellCallOutputobject

BetaFunctionShellCallOutputContentobject

BetaFunctionShellCallOutputExitOutcomeobject

BetaFunctionShellCallOutputStatusEnumenum

BetaFunctionShellCallOutputTimeoutOutcomeobject

BetaFunctionShellCallStatusenum

BetaFunctionShellToolParamobject

BetaFunctionToolobject