data: Array<BetaResponseItem>

A list of items used to generate this response.

One of the following:
BetaResponseInputMessageItem { id, content, role, 3 more }
id: string

The unique ID of the message input.

content: BetaResponseInputMessageContentList { , , }

A list of one or many input items to the model, containing different content types.

role: "user" | "system" | "developer"

The role of the message input. One of user, system, or developer.

One of the following:
"user"
"system"
"developer"
type: "message"

The type of the message input. Always set to message.

agent?: Agent | null

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

status?: "in_progress" | "completed" | "incomplete"

The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

One of the following:
"in_progress"
"completed"
"incomplete"
BetaResponseOutputMessage { id, content, role, 4 more }

An output message from the model.

id: string

The unique ID of the output message.

content: Array<BetaResponseOutputText { annotations, text, type, logprobs } | BetaResponseOutputRefusal { refusal, type } >

The content of the output message.

One of the following:
BetaResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<FileCitation { file_id, filename, index, type } | URLCitation { end_index, start_index, title, 2 more } | ContainerFileCitation { container_id, end_index, file_id, 3 more } | FilePath { file_id, index, type } >

The annotations of the text output.

One of the following:
FileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

The ID of the file.

filename: string

The filename of the file cited.

index: number

The index in the output text at which to insert the file citation.

type: "file_citation"

The type of the file citation. Always file_citation.

URLCitation { end_index, start_index, title, 2 more }

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

end_index: number

The index of the last character of the URL citation in the message.

start_index: number

The index of the first character of the URL citation in the message.

title: string

The title of the web resource.

type: "url_citation"

The type of the URL citation. Always url_citation.

url: string

The URL of the web resource.

formaturi
ContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

The ID of the container file.

end_index: number

The index of the last character of the container file citation in the message.

file_id: string

The ID of the file.

filename: string

The filename of the container file cited.

start_index: number

The index of the first character of the container file citation in the message.

type: "container_file_citation"

The type of the container file citation. Always container_file_citation.

FilePath { file_id, index, type }

A path to a file.

file_id: string

The ID of the file.

index: number

The index of the file in the list of files.

type: "file_path"

The type of the file path. Always file_path.

text: string

The text output from the model.

type: "output_text"

The type of the output text. Always output_text.

logprobs?: Array<Logprob>
token: string
bytes: Array<number>
logprob: number
top_logprobs: Array<TopLogprob>
token: string
bytes: Array<number>
logprob: number
BetaResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

The refusal explanation from the model.

type: "refusal"

The type of the refusal. Always refusal.

role: "assistant"

The role of the output message. Always assistant.

status: "in_progress" | "completed" | "incomplete"

The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

One of the following:
"in_progress"
"completed"
"incomplete"
type: "message"

The type of the output message. Always message.

agent?: Agent | null

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

phase?: "commentary" | "final_answer" | null

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 degrade performance. Not used for user messages.

One of the following:
"commentary"
"final_answer"
BetaResponseFileSearchToolCall { id, queries, status, 3 more }

The results of a file search tool call. See the file search guide for more information.

id: string

The unique ID of the file search tool call.

queries: Array<string>

The queries used to search for files.

status: "in_progress" | "searching" | "completed" | 2 more

The status of the file search tool call. One of in_progress, searching, incomplete or failed,

One of the following:
"in_progress"
"searching"
"completed"
"incomplete"
"failed"
type: "file_search_call"

The type of the file search tool call. Always file_search_call.

agent?: Agent | null

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

results?: Array<Result> | null

The results of the file search tool call.

attributes?: Record<string, string | number | boolean> | null

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 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.

One of the following:
string
number
boolean
file_id?: string

The unique ID of the file.

filename?: string

The name of the file.

score?: number

The relevance score of the file - a value between 0 and 1.

formatfloat
text?: string

The text that was retrieved from the file.

BetaResponseComputerToolCall { id, call_id, pending_safety_checks, 5 more }

A tool call to a computer use tool. See the computer use guide for more information.

id: string

The unique ID of the computer call.

call_id: string

An identifier used when responding to the tool call with output.

pending_safety_checks: Array<PendingSafetyCheck>

The pending safety checks for the computer call.

id: string

The ID of the pending safety check.

code?: string | null

The type of the pending safety check.

message?: string | null

Details about the pending safety check.

status: "in_progress" | "completed" | "incomplete"

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

One of the following:
"in_progress"
"completed"
"incomplete"
type: "computer_call"

The type of the computer call. Always computer_call.

action?: BetaComputerAction

A click action.

actions?: BetaComputerActionList { , , , 6 more }

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

agent?: Agent | null

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

BetaResponseComputerToolCallOutputItem { id, call_id, output, 5 more }
id: string

The ID of the computer tool call output.

call_id: string

The ID of the computer tool call that produced the output.

output: BetaResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

status: "completed" | "incomplete" | "failed" | "in_progress"

The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

One of the following:
"completed"
"incomplete"
"failed"
"in_progress"
type: "computer_call_output"

The type of the computer tool call output. Always computer_call_output.

acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>

The safety checks reported by the API that have been acknowledged by the developer.

id: string

The ID of the pending safety check.

code?: string | null

The type of the pending safety check.

message?: string | null

Details about the pending safety check.

agent?: Agent | null

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

created_by?: string

The identifier of the actor that created the item.

One of the following:
One of the following:
BetaResponseFunctionToolCallItem extends BetaResponseFunctionToolCall { arguments, call_id, name, 7 more } { id, status, created_by }

A tool call to run a function. See the function calling guide for more information.

id: string

The unique ID of the function tool call.

status: "in_progress" | "completed" | "incomplete"

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

One of the following:
"in_progress"
"completed"
"incomplete"
created_by?: string

The identifier of the actor that created the item.

BetaResponseFunctionToolCallOutputItem { id, output, status, 7 more }
id: string

The unique ID of the function call tool output.

output: string | Array<BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseInputImage { detail, type, file_id, 2 more } | BetaResponseInputFile { type, detail, file_data, 4 more } >

The output from the function call generated by your code. Can be a string or an list of output content.

One of the following:
string
Array<BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseInputImage { detail, type, file_id, 2 more } | BetaResponseInputFile { type, detail, file_data, 4 more } >
BetaResponseInputText { text, type, prompt_cache_breakpoint }

A text input to the model.

text: string

The text input to the model.

type: "input_text"

The type of the input item. Always input_text.

prompt_cache_breakpoint?: PromptCacheBreakpoint { mode }

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

BetaResponseInputImage { detail, type, file_id, 2 more }

An image input to the model. Learn about image inputs.

detail: BetaImageDetail

The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

type: "input_image"

The type of the input item. Always input_image.

file_id?: string | null

The ID of the file to be sent to the model.

image_url?: string | null

The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

formaturi
prompt_cache_breakpoint?: PromptCacheBreakpoint { mode }

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

BetaResponseInputFile { type, detail, file_data, 4 more }

A file input to the model.

type: "input_file"

The type of the input item. Always input_file.

detail?: "auto" | "low" | "high"

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 render the file at higher quality. Defaults to auto.

One of the following:
"auto"
"low"
"high"
file_data?: string

The content of the file to be sent to the model.

file_id?: string | null

The ID of the file to be sent to the model.

file_url?: string

The URL of the file to be sent to the model.

formaturi
filename?: string

The name of the file to be sent to the model.

prompt_cache_breakpoint?: PromptCacheBreakpoint { mode }

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

status: "in_progress" | "completed" | "incomplete"

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

One of the following:
"in_progress"
"completed"
"incomplete"
type: "function_call_output"

The type of the function tool call output. Always function_call_output.

agent?: Agent | null

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

call_id?: string

The unique ID of the function tool call generated by the model.

caller?: Direct { type } | Program { caller_id, type } | null

The execution context that produced this tool call.

One of the following:
Direct { type }
type: "direct"

The caller type. Always direct.

Program { caller_id, type }
caller_id: string

The call ID of the program item that produced this tool call.

minLength1
maxLength64
type: "program"

The caller type. Always program.

created_by?: string

The identifier of the actor that created the item.

name?: string

The name of the tool that produced the output.

namespace?: string

The namespace of the tool that produced the output.

AgentMessage { id, author, content, 3 more }
id: string

The unique ID of the agent message.

author: string

The sending agent identity.

content: Array<BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseOutputText { annotations, text, type, logprobs } | Text { text, type } | 7 more>

Encrypted content sent between agents.

One of the following:
BetaResponseInputText { text, type, prompt_cache_breakpoint }

A text input to the model.

text: string

The text input to the model.

type: "input_text"

The type of the input item. Always input_text.

prompt_cache_breakpoint?: PromptCacheBreakpoint { mode }

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

BetaResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<FileCitation { file_id, filename, index, type } | URLCitation { end_index, start_index, title, 2 more } | ContainerFileCitation { container_id, end_index, file_id, 3 more } | FilePath { file_id, index, type } >

The annotations of the text output.

One of the following:
FileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

The ID of the file.

filename: string

The filename of the file cited.

index: number

The index in the output text at which to insert the file citation.

type: "file_citation"

The type of the file citation. Always file_citation.

URLCitation { end_index, start_index, title, 2 more }

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

end_index: number

The index of the last character of the URL citation in the message.

start_index: number

The index of the first character of the URL citation in the message.

title: string

The title of the web resource.

type: "url_citation"

The type of the URL citation. Always url_citation.

url: string

The URL of the web resource.

formaturi
ContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

The ID of the container file.

end_index: number

The index of the last character of the container file citation in the message.

file_id: string

The ID of the file.

filename: string

The filename of the container file cited.

start_index: number

The index of the first character of the container file citation in the message.

type: "container_file_citation"

The type of the container file citation. Always container_file_citation.

FilePath { file_id, index, type }

A path to a file.

file_id: string

The ID of the file.

index: number

The index of the file in the list of files.

type: "file_path"

The type of the file path. Always file_path.

text: string

The text output from the model.

type: "output_text"

The type of the output text. Always output_text.

logprobs?: Array<Logprob>
token: string
bytes: Array<number>
logprob: number
top_logprobs: Array<TopLogprob>
token: string
bytes: Array<number>
logprob: number
Text { text, type }

A text content.

text: string
type: "text"
SummaryText { text, type }

A summary text from the model.

text: string

A summary of the reasoning output from the model so far.

type: "summary_text"

The type of the object. Always summary_text.

ReasoningText { text, type }

Reasoning text from the model.

text: string

The reasoning text from the model.

type: "reasoning_text"

The type of the reasoning text. Always reasoning_text.

BetaResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string

The refusal explanation from the model.

type: "refusal"

The type of the refusal. Always refusal.

BetaResponseInputImage { detail, type, file_id, 2 more }

An image input to the model. Learn about image inputs.

detail: BetaImageDetail

The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

type: "input_image"

The type of the input item. Always input_image.

file_id?: string | null

The ID of the file to be sent to the model.

image_url?: string | null

The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

formaturi
prompt_cache_breakpoint?: PromptCacheBreakpoint { mode }

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

ComputerScreenshot { detail, file_id, image_url, 2 more }

A screenshot of a computer.

detail: BetaImageDetail

The detail level of the screenshot image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

file_id: string | null

The identifier of an uploaded file that contains the screenshot.

image_url: string | null

The URL of the screenshot image.

formaturi
type: "computer_screenshot"

Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

prompt_cache_breakpoint?: PromptCacheBreakpoint { mode }

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

BetaResponseInputFile { type, detail, file_data, 4 more }

A file input to the model.

type: "input_file"

The type of the input item. Always input_file.

detail?: "auto" | "low" | "high"

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 render the file at higher quality. Defaults to auto.

One of the following:
"auto"
"low"
"high"
file_data?: string

The content of the file to be sent to the model.

file_id?: string | null

The ID of the file to be sent to the model.

file_url?: string

The URL of the file to be sent to the model.

formaturi
filename?: string

The name of the file to be sent to the model.

prompt_cache_breakpoint?: PromptCacheBreakpoint { mode }

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

EncryptedContent { encrypted_content, type }

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

encrypted_content: string

Opaque encrypted content.

type: "encrypted_content"

The type of the input item. Always encrypted_content.

recipient: string

The destination agent identity.

type: "agent_message"

The type of the item. Always agent_message.

agent?: Agent { agent_name }

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

MultiAgentCall { id, action, arguments, 3 more }
id: string

The unique ID of the multi-agent call item.

action: "spawn_agent" | "interrupt_agent" | "list_agents" | 3 more

The multi-agent action to execute.

One of the following:
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string

The JSON string of arguments generated for the action.

call_id: string

The unique ID linking this call to its output.

type: "multi_agent_call"

The type of the multi-agent call. Always multi_agent_call.

agent?: Agent { agent_name }

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

MultiAgentCallOutput { id, action, call_id, 3 more }
id: string

The unique ID of the multi-agent call output item.

action: "spawn_agent" | "interrupt_agent" | "list_agents" | 3 more

The multi-agent action that produced this result.

One of the following:
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string

The unique ID of the multi-agent call.

output: Array<BetaResponseOutputText { annotations, text, type, logprobs } >

Text output returned by the multi-agent action.

annotations: Array<FileCitation { file_id, filename, index, type } | URLCitation { end_index, start_index, title, 2 more } | ContainerFileCitation { container_id, end_index, file_id, 3 more } | FilePath { file_id, index, type } >

The annotations of the text output.

One of the following:
FileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string

The ID of the file.

filename: string

The filename of the file cited.

index: number

The index in the output text at which to insert the file citation.

type: "file_citation"

The type of the file citation. Always file_citation.

URLCitation { end_index, start_index, title, 2 more }

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

end_index: number

The index of the last character of the URL citation in the message.

start_index: number

The index of the first character of the URL citation in the message.

title: string

The title of the web resource.

type: "url_citation"

The type of the URL citation. Always url_citation.

url: string

The URL of the web resource.

formaturi
ContainerFileCitation { container_id, end_index, file_id, 3 more }

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

container_id: string

The ID of the container file.

end_index: number

The index of the last character of the container file citation in the message.

file_id: string

The ID of the file.

filename: string

The filename of the container file cited.

start_index: number

The index of the first character of the container file citation in the message.

type: "container_file_citation"

The type of the container file citation. Always container_file_citation.

FilePath { file_id, index, type }

A path to a file.

file_id: string

The ID of the file.

index: number

The index of the file in the list of files.

type: "file_path"

The type of the file path. Always file_path.

text: string

The text output from the model.

type: "output_text"

The type of the output text. Always output_text.

logprobs?: Array<Logprob>
token: string
bytes: Array<number>
logprob: number
top_logprobs: Array<TopLogprob>
token: string
bytes: Array<number>
logprob: number
type: "multi_agent_call_output"

The type of the multi-agent result. Always multi_agent_call_output.

agent?: Agent { agent_name }

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

BetaResponseToolSearchCall { id, arguments, call_id, 5 more }
id: string

The unique ID of the tool search call item.

arguments: unknown

Arguments used for the tool search call.

call_id: string | null

The unique ID of the tool search call generated by the model.

execution: "server" | "client"

Whether tool search was executed by the server or by the client.

One of the following:
"server"
"client"
status: "in_progress" | "completed" | "incomplete"

The status of the tool search call item that was recorded.

One of the following:
"in_progress"
"completed"
"incomplete"
type: "tool_search_call"

The type of the item. Always tool_search_call.

agent?: Agent { agent_name }

The agent that produced this item.

agent_name: string

The canonical name of the agent that produced this item.

created_by?: string

The identifier of the actor that created the item.

BetaResponseToolSearchOutputItem { id, call_id, execution, 5 more }
id: string

The unique ID of the tool search output item.

call_id: string | null

The unique ID of the tool search call generated by the model.

execution: "server" | "client"

Whether tool search was executed by the server or by the client.

One of the following:
"server"
"client"
status: "in_progress" | "completed" | "incomplete"

The status of the tool search output item that was recorded.

One of the following:
"in_progress"
"completed"
"incomplete"
tools: Array<BetaTool>

The loaded tool definitions returned by tool search.

One of the following:
BetaFunctionTool { name, parameters, strict, 6 more }

Defines a function in your own code the model can choose to call. Learn more about function calling.

name: string

The name of the function to call.

parameters: Record<string, unknown> | null

A JSON schema object describing the parameters of the function.

strict: boolean | null

Whether strict parameter validation is enforced for this function tool.

type: "function"

The type of the function tool. Always function.

allowed_callers?: Array<"direct" | "programmatic"> | null

The tool invocation context(s).

One of the following:
"direct"
"programmatic"
async?: boolean
defer_loading?: boolean

Whether this function is deferred and loaded via tool search.

description?: string | null

A description of the function. Used by the model to determine whether or not to call the function.

output_schema?: Record<string, unknown> | null

A JSON schema object describing the JSON value encoded in string outputs for this function.

BetaFileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files. Learn more about the file search tool.

type: "file_search"

The type of the file search tool. Always file_search.

vector_store_ids: Array<string>

The IDs of the vector stores to search.

filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type } | null

A filter to apply.

One of the following:
ComparisonFilter { key, type, value }

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

key: string

The key to compare against the value.

type: "eq" | "ne" | "gt" | 5 more

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
One of the following:
"eq"
"ne"
"gt"
"gte"
"lt"
"lte"
"in"
"nin"
value: string | number | boolean | Array<string | number>

The value to compare against the attribute key; supports string, number, or boolean types.

One of the following:
string
number
boolean
Array<string | number>
string
number
CompoundFilter { filters, type }

Combine multiple filters using and or or.

filters: Array<ComparisonFilter { key, type, value } | unknown>

Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.

One of the following:
ComparisonFilter { key, type, value }

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

key: string

The key to compare against the value.

type: "eq" | "ne" | "gt" | 5 more

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
One of the following:
"eq"
"ne"
"gt"
"gte"
"lt"
"lte"
"in"
"nin"
value: string | number | boolean | Array<string | number>

The value to compare against the attribute key; supports string, number, or boolean types.

One of the following:
string
number
boolean
Array<string | number>
string
number
unknown
type: "and" | "or"

Type of operation: and or or.

One of the following:
"and"
"or"
max_num_results?: number

The maximum number of results to return. This number should be between 1 and 50 inclusive.

ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold }

Ranking options for search.

text_weight: number

The weight of the text in the reciprocal ranking fusion.

ranker?: "auto" | "default-2024-11-15"

The ranker to use for the file search.

One of the following:
"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.

BetaComputerTool { type }

A tool that controls a virtual computer. Learn more about the computer tool.

type: "computer"

The type of the computer tool. Always computer.

BetaComputerUsePreviewTool { display_height, display_width, environment, type }

A tool that controls a virtual computer. Learn more about the computer tool.

display_height: number

The height of the computer display.

display_width: number

The width of the computer display.

environment: "windows" | "mac" | "linux" | 2 more

The type of computer environment to control.

One of the following:
"windows"
"mac"
"linux"
"ubuntu"
"browser"
type: "computer_use_preview"

The type of the computer use tool. Always computer_use_preview.

BetaWebSearchTool { type, external_web_access, filters, 2 more }

Search the Internet for sources related to the prompt. Learn more about the web search tool.

type: "web_search" | "web_search_2025_08_26"

The type of the web search tool. One of web_search or web_search_2025_08_26.

One of the following:
"web_search"
"web_search_2025_08_26"
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.

filters?: Filters | null

Filters for the search.

allowed_domains?: Array<string> | null

Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well.

Example: ["pubmed.ncbi.nlm.nih.gov"]

search_context_size?: "low" | "medium" | "high"

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.

user_location?: UserLocation | null

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.

Mcp { server_label, type, allowed_callers, 9 more }

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

CodeInterpreter { container, type, allowed_callers }

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

ProgrammaticToolCalling { type }
ImageGeneration { type, action, background, 9 more }

A tool that generates images using the GPT image models.

LocalShell { type }

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

BetaFunctionShellTool { type, allowed_callers, environment }

A tool that allows the model to execute shell commands.

BetaCustomTool { name, type, allowed_callers, 4 more }

A custom tool that processes input using a specified format. Learn more about custom tools

BetaNamespaceTool { description, name, tools, type }

Groups function/custom tools under a shared namespace.

BetaToolSearchTool { type, description, execution, parameters }

Hosted or BYOT tool search configuration for deferred tools.

BetaWebSearchPreviewTool { type, search_content_types, search_context_size, user_location }

This tool searches the web for relevant results to use in a response. Learn more about the web search tool.

BetaApplyPatchTool { type, allowed_callers }

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

type: "tool_search_output"

The type of the item. Always tool_search_output.

agent?: Agent { agent_name }

The agent that produced this item.

created_by?: string

The identifier of the actor that created the item.

AdditionalTools { id, role, tools, 2 more }
BetaResponseConfigurationUpdateItem { id, type, agent, reasoning }

A configuration update that applies to subsequent responses until it is replaced by another configuration update.

BetaResponseReasoningItem { id, summary, type, 4 more }

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.

Program { id, call_id, code, 3 more }
ProgramOutput { id, call_id, result, 3 more }
BetaResponseCompactionItem { id, encrypted_content, type, 2 more }

A compaction item generated by the v1/responses/compact API.

ImageGenerationCall { id, result, status, 8 more }

An image generation request made by the model.

BetaResponseCodeInterpreterToolCall { id, code, container_id, 4 more }

A tool call to run code.

LocalShellCall { id, action, call_id, 3 more }

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

LocalShellCallOutput { id, output, type, 2 more }

The output of a local shell tool call.

BetaResponseFunctionShellToolCall { id, action, call_id, 6 more }

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

BetaResponseFunctionShellToolCallOutput { id, call_id, max_output_length, 6 more }

The output of a shell tool call that was emitted.

BetaResponseApplyPatchToolCall { id, call_id, operation, 5 more }

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

BetaResponseApplyPatchToolCallOutput { id, call_id, status, 5 more }

The output emitted by an apply patch tool call.

McpListTools { id, server_label, tools, 3 more }

A list of tools available on an MCP server.

McpApprovalRequest { id, arguments, name, 3 more }

A request for human approval of a tool invocation.

McpApprovalResponse { id, approval_request_id, approve, 3 more }

A response to an MCP approval request.

McpCall { id, arguments, name, 7 more }

An invocation of a tool on an MCP server.

BetaResponseCustomToolCallItem extends BetaResponseCustomToolCall { call_id, input, name, 6 more } { id, status, created_by }

A call to a custom tool created by the model.

BetaResponseCustomToolCallOutputItem extends BetaResponseCustomToolCallOutput { call_id, output, type, 3 more } { id, status, created_by }

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

first_id: string

The ID of the first item in the list.

has_more: boolean

Whether there are more items available.

last_id: string

The ID of the last item in the list.

object: "list"

The type of object returned, must be list.