## Compact a response `beta.responses.compact(**kwargs) -> BetaCompactedResponse` **post** `/responses/compact?beta=true` Compact a response ### Parameters - `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - `:"gpt-5.6-sol"` - `:"gpt-5.6-terra"` - `:"gpt-5.6-luna"` - `:"gpt-5.4"` - `:"gpt-5.4-mini"` - `:"gpt-5.4-nano"` - `:"gpt-5.4-mini-2026-03-17"` - `:"gpt-5.4-nano-2026-03-17"` - `:"gpt-5.3-chat-latest"` - `:"gpt-5.2"` - `:"gpt-5.2-2025-12-11"` - `:"gpt-5.2-chat-latest"` - `:"gpt-5.2-pro"` - `:"gpt-5.2-pro-2025-12-11"` - `:"gpt-5.1"` - `:"gpt-5.1-2025-11-13"` - `:"gpt-5.1-codex"` - `:"gpt-5.1-mini"` - `:"gpt-5.1-chat-latest"` - `:"gpt-5"` - `:"gpt-5-mini"` - `:"gpt-5-nano"` - `:"gpt-5-2025-08-07"` - `:"gpt-5-mini-2025-08-07"` - `:"gpt-5-nano-2025-08-07"` - `:"gpt-5-chat-latest"` - `:"gpt-4.1"` - `:"gpt-4.1-mini"` - `:"gpt-4.1-nano"` - `:"gpt-4.1-2025-04-14"` - `:"gpt-4.1-mini-2025-04-14"` - `:"gpt-4.1-nano-2025-04-14"` - `:"o4-mini"` - `:"o4-mini-2025-04-16"` - `:o3` - `:"o3-2025-04-16"` - `:"o3-mini"` - `:"o3-mini-2025-01-31"` - `:o1` - `:"o1-2024-12-17"` - `:"o1-preview"` - `:"o1-preview-2024-09-12"` - `:"o1-mini"` - `:"o1-mini-2024-09-12"` - `:"gpt-4o"` - `:"gpt-4o-2024-11-20"` - `:"gpt-4o-2024-08-06"` - `:"gpt-4o-2024-05-13"` - `:"gpt-4o-audio-preview"` - `:"gpt-4o-audio-preview-2024-10-01"` - `:"gpt-4o-audio-preview-2024-12-17"` - `:"gpt-4o-audio-preview-2025-06-03"` - `:"gpt-4o-mini-audio-preview"` - `:"gpt-4o-mini-audio-preview-2024-12-17"` - `:"gpt-4o-search-preview"` - `:"gpt-4o-mini-search-preview"` - `:"gpt-4o-search-preview-2025-03-11"` - `:"gpt-4o-mini-search-preview-2025-03-11"` - `:"chatgpt-4o-latest"` - `:"codex-mini-latest"` - `:"gpt-4o-mini"` - `:"gpt-4o-mini-2024-07-18"` - `:"gpt-4-turbo"` - `:"gpt-4-turbo-2024-04-09"` - `:"gpt-4-0125-preview"` - `:"gpt-4-turbo-preview"` - `:"gpt-4-1106-preview"` - `:"gpt-4-vision-preview"` - `:"gpt-4"` - `:"gpt-4-0314"` - `:"gpt-4-0613"` - `:"gpt-4-32k"` - `:"gpt-4-32k-0314"` - `:"gpt-4-32k-0613"` - `:"gpt-3.5-turbo"` - `:"gpt-3.5-turbo-16k"` - `:"gpt-3.5-turbo-0301"` - `:"gpt-3.5-turbo-0613"` - `:"gpt-3.5-turbo-1106"` - `:"gpt-3.5-turbo-0125"` - `:"gpt-3.5-turbo-16k-0613"` - `:"o1-pro"` - `:"o1-pro-2025-03-19"` - `:"o3-pro"` - `:"o3-pro-2025-06-10"` - `:"o3-deep-research"` - `:"o3-deep-research-2025-06-26"` - `:"o4-mini-deep-research"` - `:"o4-mini-deep-research-2025-06-26"` - `:"computer-use-preview"` - `:"computer-use-preview-2025-03-11"` - `:"gpt-5-codex"` - `:"gpt-5-pro"` - `:"gpt-5-pro-2025-10-06"` - `:"gpt-5.1-codex-max"` - `String = String` - `input: String | Array[BetaResponseInputItem]` Text, image, or file inputs to the model, used to generate a response - `String = String` A text input to the model, equivalent to a text input with the `user` role. - `UnionMember1 = Array[BetaResponseInputItem]` A list of one or many input items to the model, containing different content types. - `class BetaEasyInputMessage` A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. Messages with the `assistant` role are presumed to have been generated by the model in previous interactions. - `content: String | BetaResponseInputMessageContentList` Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - `String = String` A text input to the model. - `BetaResponseInputMessageContentList = Array[BetaResponseInputContent]` A list of one or many input items to the model, containing different content types. - `class BetaResponseInputText` 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`. - `: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`. - `:explicit` - `class BetaResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: :low | :high | :auto | :original` 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` - `type: :input_image` The type of the input item. Always `input_image`. - `:input_image` - `file_id: String` The ID of the file to be sent to the model. - `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. - `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`. - `:explicit` - `class BetaResponseInputFile` A file input to the model. - `type: :input_file` The type of the input item. Always `input_file`. - `: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`. - `:auto` - `:low` - `:high` - `file_data: String` The content of the file to be sent to the model. - `file_id: String` 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. - `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`. - `:explicit` - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `:user` - `:assistant` - `:system` - `:developer` - `phase: :commentary` 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. - `:commentary` - `type: :message` The type of the message input. Always `message`. - `:message` - `class Message` A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. - `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`. - `:user` - `:system` - `:developer` - `agent: Agent{ agent_name}` 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. - `:in_progress` - `:completed` - `:incomplete` - `type: :message` The type of the message input. Always set to `message`. - `:message` - `class BetaResponseOutputMessage` An output message from the model. - `id: String` The unique ID of the output message. - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` The content of the output message. - `class BetaResponseOutputText` 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. - `class FileCitation` A citation to a file. - `file_id: String` The ID of the file. - `filename: String` The filename of the file cited. - `index: Integer` The index of the file in the list of files. - `type: :file_citation` The type of the file citation. Always `file_citation`. - `:file_citation` - `class URLCitation` A citation for a web resource used to generate a model response. - `end_index: Integer` The index of the last character of the URL citation in the message. - `start_index: Integer` 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_citation` - `url: String` The URL of the web resource. - `class ContainerFileCitation` A citation for a container file used to generate a model response. - `container_id: String` The ID of the container file. - `end_index: Integer` 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: Integer` 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`. - `:container_file_citation` - `class FilePath` A path to a file. - `file_id: String` The ID of the file. - `index: Integer` The index of the file in the list of files. - `type: :file_path` The type of the file path. Always `file_path`. - `:file_path` - `text: String` The text output from the model. - `type: :output_text` The type of the output text. Always `output_text`. - `:output_text` - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - `token: String` - `bytes: Array[Integer]` - `logprob: Float` - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - `token: String` - `bytes: Array[Integer]` - `logprob: Float` - `class BetaResponseOutputRefusal` A refusal from the model. - `refusal: String` The refusal explanation from the model. - `type: :refusal` The type of the refusal. Always `refusal`. - `:refusal` - `role: :assistant` The role of the output message. Always `assistant`. - `: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. - `:in_progress` - `:completed` - `:incomplete` - `type: :message` The type of the output message. Always `message`. - `:message` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `phase: :commentary` 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. - `:commentary` - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) 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`, - `:in_progress` - `:searching` - `:completed` - `:incomplete` - `:failed` - `type: :file_search_call` The type of the file search tool call. Always `file_search_call`. - `:file_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. - `results: Array[Result{ attributes, file_id, filename, 2 more}]` The results of the file search tool call. - `attributes: Hash[Symbol, String | Float | bool]` 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. - `String = String` - `Float = Float` - `UnionMember2 = bool` - `file_id: String` The unique ID of the file. - `filename: String` The name of the file. - `score: Float` The relevance score of the file - a value between 0 and 1. - `text: String` The text that was retrieved from the file. - `class BetaResponseComputerToolCall` A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) 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{ id, code, message}]` The pending safety checks for the computer call. - `id: String` The ID of the pending safety check. - `code: String` The type of the pending safety check. - `message: String` 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. - `:in_progress` - `:completed` - `:incomplete` - `type: :computer_call` The type of the computer call. Always `computer_call`. - `:computer_call` - `action: BetaComputerAction` A click action. - `class Click` A click action. - `button: :left | :right | :wheel | 2 more` Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - `:left` - `:right` - `:wheel` - `:back` - `:forward` - `type: :click` Specifies the event type. For a click action, this property is always `click`. - `:click` - `x: Integer` The x-coordinate where the click occurred. - `y_: Integer` The y-coordinate where the click occurred. - `keys: Array[String]` The keys being held while clicking. - `class DoubleClick` A double click action. - `keys: Array[String]` The keys being held while double-clicking. - `type: :double_click` Specifies the event type. For a double click action, this property is always set to `double_click`. - `:double_click` - `x: Integer` The x-coordinate where the double click occurred. - `y_: Integer` The y-coordinate where the double click occurred. - `class Drag` A drag action. - `path: Array[Path{ x, y_}]` 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 } ] ``` - `x: Integer` The x-coordinate. - `y_: Integer` The y-coordinate. - `type: :drag` Specifies the event type. For a drag action, this property is always set to `drag`. - `:drag` - `keys: Array[String]` The keys being held while dragging the mouse. - `class Keypress` A collection of keypresses the model would like to perform. - `keys: Array[String]` The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `type: :keypress` Specifies the event type. For a keypress action, this property is always set to `keypress`. - `:keypress` - `class Move` A mouse move action. - `type: :move` Specifies the event type. For a move action, this property is always set to `move`. - `:move` - `x: Integer` The x-coordinate to move to. - `y_: Integer` The y-coordinate to move to. - `keys: Array[String]` The keys being held while moving the mouse. - `class Screenshot` A screenshot action. - `type: :screenshot` Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - `:screenshot` - `class Scroll` A scroll action. - `scroll_x: Integer` The horizontal scroll distance. - `scroll_y: Integer` The vertical scroll distance. - `type: :scroll` Specifies the event type. For a scroll action, this property is always set to `scroll`. - `:scroll` - `x: Integer` The x-coordinate where the scroll occurred. - `y_: Integer` The y-coordinate where the scroll occurred. - `keys: Array[String]` The keys being held while scrolling. - `class Type` An action to type in text. - `text: String` The text to type. - `type: :type` Specifies the event type. For a type action, this property is always set to `type`. - `:type` - `class Wait` A wait action. - `type: :wait` Specifies the event type. For a wait action, this property is always set to `wait`. - `:wait` - `actions: BetaComputerActionList` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - `class Click` A click action. - `class DoubleClick` A double click action. - `class Drag` A drag action. - `class Keypress` A collection of keypresses the model would like to perform. - `class Move` A mouse move action. - `class Screenshot` A screenshot action. - `class Scroll` A scroll action. - `class Type` An action to type in text. - `class Wait` A wait action. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class ComputerCallOutput` The output of a computer tool call. - `call_id: String` The ID of the computer tool call that produced the output. - `output: BetaResponseComputerToolCallOutputScreenshot` A computer screenshot image used with the computer use tool. - `type: :computer_screenshot` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `:computer_screenshot` - `file_id: String` The identifier of an uploaded file that contains the screenshot. - `image_url: String` The URL of the screenshot image. - `type: :computer_call_output` The type of the computer tool call output. Always `computer_call_output`. - `:computer_call_output` - `id: String` The ID of the computer tool call output. - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` 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` The type of the pending safety check. - `message: String` Details about the pending safety check. - `agent: Agent{ agent_name}` 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 the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `:in_progress` - `:completed` - `:incomplete` - `class BetaResponseFunctionWebSearch` The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: String` The unique ID of the web search tool call. - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` 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). - `class Search` Action type "search" - Performs a web search query. - `type: :search` The action type. - `:search` - `queries: Array[String]` The search queries. - `query: String` The search query. - `sources: Array[Source{ type, url}]` The sources used in the search. - `type: :url` The type of source. Always `url`. - `:url` - `url: String` The URL of the source. - `class OpenPage` Action type "open_page" - Opens a specific URL from search results. - `type: :open_page` The action type. - `:open_page` - `url: String` The URL opened by the model. - `class FindInPage` Action type "find_in_page": Searches for a pattern within a loaded page. - `pattern: String` The pattern or text to search for within the page. - `type: :find_in_page` The action type. - `:find_in_page` - `url: String` The URL of the page searched for the pattern. - `status: :in_progress | :searching | :completed | :failed` The status of the web search tool call. - `:in_progress` - `:searching` - `:completed` - `:failed` - `type: :web_search_call` The type of the web search tool call. Always `web_search_call`. - `:web_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. - `class BetaResponseFunctionToolCall` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: String` A JSON string of the arguments to pass to the function. - `call_id: String` The unique ID of the function tool call generated by the model. - `name: String` The name of the function to run. - `type: :function_call` The type of the function tool call. Always `function_call`. - `:function_call` - `id: String` The unique ID of the function tool call. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `namespace: String` The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` - `:completed` - `:incomplete` - `class FunctionCallOutput` The output of a function tool call. - `call_id: String` The unique ID of the function tool call generated by the model. - `output: String | BetaResponseFunctionCallOutputItemList` Text, image, or file output of the function tool call. - `String = String` A JSON string of the output of the function tool call. - `BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]` An array of content outputs (text, image, file) for the function tool call. - `class BetaResponseInputTextContent` 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`. - `: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`. - `:explicit` - `class BetaResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: :input_image` The type of the input item. Always `input_image`. - `:input_image` - `detail: :low | :high | :auto | :original` 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` - `file_id: String` The ID of the file to be sent to the model. - `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. - `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`. - `:explicit` - `class BetaResponseInputFileContent` A file input to the model. - `type: :input_file` The type of the input item. Always `input_file`. - `: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`. - `:auto` - `:low` - `:high` - `file_data: String` The base64-encoded data of the file to be sent to the model. - `file_id: String` 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. - `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`. - `:explicit` - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. - `:function_call_output` - `id: String` The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` The caller type. Always `direct`. - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` The caller type. Always `program`. - `:program` - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` - `:completed` - `:incomplete` - `class AgentMessage` A message routed between agents. - `author: String` The sending agent identity. - `content: Array[BetaResponseInputTextContent | BetaResponseInputImageContent | EncryptedContent{ encrypted_content, type}]` Plaintext, image, or encrypted content sent between agents. - `class BetaResponseInputTextContent` A text input to the model. - `class BetaResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `class EncryptedContent` 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`. - `:encrypted_content` - `recipient: String` The destination agent identity. - `type: :agent_message` The item type. Always `agent_message`. - `:agent_message` - `id: String` The unique ID of this agent message item. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class MultiAgentCall` - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` The multi-agent action that was executed. - `:spawn_agent` - `:interrupt_agent` - `:list_agents` - `:send_message` - `:followup_task` - `:wait_agent` - `arguments: String` The action arguments as a JSON string. - `call_id: String` The unique ID linking this call to its output. - `type: :multi_agent_call` The item type. Always `multi_agent_call`. - `:multi_agent_call` - `id: String` The unique ID of this 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. - `class MultiAgentCallOutput` - `action: :spawn_agent | :interrupt_agent | :list_agents | 3 more` The multi-agent action that produced this result. - `: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[Output{ text, type, annotations}]` Text output returned by the multi-agent action. - `text: String` The text content. - `type: :output_text` The content type. Always `output_text`. - `:output_text` - `annotations: Array[UnionMember0{ file_id, filename, index, type}] | Array[UnionMember1{ end_index, start_index, title, 2 more}] | Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` Citations associated with the text content. - `UnionMember0 = Array[UnionMember0{ file_id, filename, index, type}]` - `file_id: String` The ID of the file. - `filename: String` The filename of the file cited. - `index: Integer` The index of the file in the list of files. - `type: :file_citation` The citation type. Always `file_citation`. - `:file_citation` - `UnionMember1 = Array[UnionMember1{ end_index, start_index, title, 2 more}]` - `end_index: Integer` The index of the last character of the citation in the message. - `start_index: Integer` The index of the first character of the citation in the message. - `title: String` The title of the cited resource. - `type: :url_citation` The citation type. Always `url_citation`. - `:url_citation` - `url: String` The URL of the cited resource. - `UnionMember2 = Array[UnionMember2{ container_id, end_index, file_id, 3 more}]` - `container_id: String` The ID of the container. - `end_index: Integer` The index of the last character of the citation in the message. - `file_id: String` The ID of the container file. - `filename: String` The filename of the container file cited. - `start_index: Integer` The index of the first character of the citation in the message. - `type: :container_file_citation` The citation type. Always `container_file_citation`. - `:container_file_citation` - `type: :multi_agent_call_output` The item type. Always `multi_agent_call_output`. - `:multi_agent_call_output` - `id: String` The unique ID of this 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. - `class ToolSearchCall` - `arguments: untyped` The arguments supplied to the tool search call. - `type: :tool_search_call` The item type. Always `tool_search_call`. - `:tool_search_call` - `id: String` The unique ID of this 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. - `call_id: String` 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. - `:server` - `:client` - `status: :in_progress | :completed | :incomplete` The status of the tool search call. - `:in_progress` - `:completed` - `:incomplete` - `class BetaResponseToolSearchOutputItemParam` - `tools: Array[BetaTool]` The loaded tool definitions returned by the tool search output. - `class BetaFunctionTool` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `name: String` The name of the function to call. - `parameters: Hash[Symbol, untyped]` A JSON schema object describing the parameters of the function. - `strict: bool` Whether strict parameter validation is enforced for this function tool. - `type: :function` The type of the function tool. Always `function`. - `:function` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `defer_loading: bool` Whether this function is deferred and loaded via tool search. - `description: String` A description of the function. Used by the model to determine whether or not to call the function. - `output_schema: Hash[Symbol, untyped]` A JSON schema object describing the JSON value encoded in string outputs for this function. - `class BetaFileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `type: :file_search` The type of the file search tool. Always `file_search`. - `:file_search` - `vector_store_ids: Array[String]` The IDs of the vector stores to search. - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` A filter to apply. - `class ComparisonFilter` 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 - `:eq` - `:ne` - `:gt` - `:gte` - `:lt` - `:lte` - `:in` - `:nin` - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. - `String = String` - `Float = Float` - `UnionMember2 = bool` - `UnionMember3 = Array[untyped]` - `class CompoundFilter` Combine multiple filters using `and` or `or`. - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - `class ComparisonFilter` 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 - `:eq` - `:ne` - `:gt` - `:gte` - `:lt` - `:lte` - `:in` - `:nin` - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. - `String = String` - `Float = Float` - `UnionMember2 = bool` - `UnionMember3 = Array[untyped]` - `UnionMember1 = untyped` - `type: :and | :or` Type of operation: `and` or `or`. - `:and` - `:or` - `max_num_results: Integer` 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. - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - `embedding_weight: Float` The weight of the embedding in the reciprocal ranking fusion. - `text_weight: Float` The weight of the text in the reciprocal ranking fusion. - `ranker: :auto | :"default-2024-11-15"` The ranker to use for the file search. - `:auto` - `:"default-2024-11-15"` - `score_threshold: Float` 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. - `class BetaComputerTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type: :computer` The type of the computer tool. Always `computer`. - `:computer` - `class BetaComputerUsePreviewTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height: Integer` The height of the computer display. - `display_width: Integer` The width of the computer display. - `environment: :windows | :mac | :linux | 2 more` The type of computer environment to control. - `:windows` - `:mac` - `:linux` - `:ubuntu` - `:browser` - `type: :computer_use_preview` The type of the computer use tool. Always `computer_use_preview`. - `:computer_use_preview` - `class BetaWebSearchTool` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `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`. - `:web_search` - `:web_search_2025_08_26` - `filters: Filters{ allowed_domains}` Filters for the search. - `allowed_domains: Array[String]` 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. - `:low` - `:medium` - `:high` - `user_location: UserLocation{ city, country, region, 2 more}` The approximate location of the user. - `city: String` Free text input for the city of the user, e.g. `San Francisco`. - `country: String` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region: String` Free text input for the region of the user, e.g. `California`. - `timezone: String` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type: :approximate` The type of location approximation. Always `approximate`. - `:approximate` - `class Mcp` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: String` A label for this MCP server, used to identify it in tool calls. - `type: :mcp` The type of the MCP tool. Always `mcp`. - `:mcp` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. - `McpAllowedTools = Array[String]` A string array of allowed tool names - `class McpToolFilter` A filter object to specify which tools are allowed. - `read_only: bool` 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. - `tool_names: Array[String]` List of allowed tool names. - `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. - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` 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://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - Google Calendar: `connector_googlecalendar` - Google Drive: `connector_googledrive` - Microsoft Teams: `connector_microsoftteams` - Outlook Calendar: `connector_outlookcalendar` - Outlook Email: `connector_outlookemail` - SharePoint: `connector_sharepoint` - `:connector_dropbox` - `:connector_gmail` - `:connector_googlecalendar` - `:connector_googledrive` - `:connector_microsoftteams` - `:connector_outlookcalendar` - `:connector_outlookemail` - `:connector_sharepoint` - `defer_loading: bool` Whether this MCP tool is deferred and discovered via tool search. - `headers: Hash[Symbol, String]` Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` Specify which of the MCP server's tools require approval. - `class McpToolApprovalFilter` Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval. - `always: Always{ read_only, tool_names}` A filter object to specify which tools are allowed. - `read_only: bool` 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. - `tool_names: Array[String]` List of allowed tool names. - `never: Never{ read_only, tool_names}` A filter object to specify which tools are allowed. - `read_only: bool` 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. - `tool_names: Array[String]` List of allowed tool names. - `McpToolApprovalSetting = :always | :never` Specify a single approval policy for all tools. One of `always` or `never`. When set to `always`, all tools will require approval. When set to `never`, all tools will not require approval. - `:always` - `:never` - `server_description: String` Optional description of the MCP server, used to provide more context. - `server_url: String` The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `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. - `class CodeInterpreter` A tool that runs Python code to help generate a response to a prompt. - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` 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. - `String = String` The container ID. - `class CodeInterpreterToolAuto` Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `type: :auto` Always `auto`. - `:auto` - `file_ids: Array[String]` An optional list of uploaded files to make available to your code. - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` The memory limit for the code interpreter container. - `:"1g"` - `:"4g"` - `:"16g"` - `:"64g"` - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled` - `type: :disabled` Disable outbound network access. Always `disabled`. - `:disabled` - `class BetaContainerNetworkPolicyAllowlist` - `allowed_domains: Array[String]` A list of allowed domains when type is `allowlist`. - `type: :allowlist` Allow outbound network access only to specified domains. Always `allowlist`. - `:allowlist` - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` Optional domain-scoped secrets for allowlisted domains. - `domain: String` The domain associated with the secret. - `name: String` The name of the secret to inject for the domain. - `value: String` The secret value to inject for the domain. - `type: :code_interpreter` The type of the code interpreter tool. Always `code_interpreter`. - `:code_interpreter` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `class ProgrammaticToolCalling` - `type: :programmatic_tool_calling` The type of the tool. Always `programmatic_tool_calling`. - `:programmatic_tool_calling` - `class ImageGeneration` A tool that generates images using the GPT image models. - `type: :image_generation` The type of the image generation tool. Always `image_generation`. - `:image_generation` - `action: :generate | :edit | :auto` Whether to generate a new image or edit an existing image. Default: `auto`. - `:generate` - `:edit` - `:auto` - `background: :transparent | :opaque | :auto` Allows to set transparency for the background of the generated image(s). This parameter is only supported for GPT image models that support transparent backgrounds. 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. `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds. Requests with `background` set to `transparent` will return an error for these models; use `opaque` or `auto` instead. If `transparent`, the output format needs to support transparency, so it should be set to either `png` (default value) or `webp`. - `:transparent` - `:opaque` - `:auto` - `input_fidelity: :high | :low` Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - `:high` - `:low` - `input_image_mask: InputImageMask{ file_id, image_url}` Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). - `file_id: String` File ID for the mask image. - `image_url: String` Base64-encoded mask image. - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` The image generation model to use. Default: `gpt-image-1`. - `String = String` - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` The image generation model to use. Default: `gpt-image-1`. - `:"gpt-image-1"` - `:"gpt-image-1-mini"` - `:"gpt-image-2"` - `:"gpt-image-2-2026-04-21"` - `:"gpt-image-1.5"` - `:"chatgpt-image-latest"` - `moderation: :auto | :low` Moderation level for the generated image. Default: `auto`. - `:auto` - `:low` - `output_compression: Integer` Compression level for the output image. Default: 100. - `output_format: :png | :webp | :jpeg` The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. - `:png` - `:webp` - `:jpeg` - `partial_images: Integer` Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `quality: :low | :medium | :high | :auto` The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. Default: `auto`. - `:low` - `:medium` - `:high` - `:auto` - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - `String = String` - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - `:"1024x1024"` - `:"1024x1536"` - `:"1536x1024"` - `:auto` - `class LocalShell` A tool that allows the model to execute shell commands in a local environment. - `type: :local_shell` The type of the local shell tool. Always `local_shell`. - `:local_shell` - `class BetaFunctionShellTool` A tool that allows the model to execute shell commands. - `type: :shell` The type of the shell tool. Always `shell`. - `:shell` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - `class BetaContainerAuto` - `type: :container_auto` Automatically creates a container for this request - `:container_auto` - `file_ids: Array[String]` An optional list of uploaded files to make available to your code. - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` The memory limit for the container. - `:"1g"` - `:"4g"` - `:"16g"` - `:"64g"` - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled` - `class BetaContainerNetworkPolicyAllowlist` - `skills: Array[BetaSkillReference | BetaInlineSkill]` An optional list of skills referenced by id or inline data. - `class BetaSkillReference` - `skill_id: String` The ID of the referenced skill. - `type: :skill_reference` References a skill created with the /v1/skills endpoint. - `:skill_reference` - `version: String` Optional skill version. Use a positive integer or 'latest'. Omit for default. - `class BetaInlineSkill` - `description: String` The description of the skill. - `name: String` The name of the skill. - `source: BetaInlineSkillSource` Inline skill payload - `data: String` Base64-encoded skill zip bundle. - `media_type: :"application/zip"` The media type of the inline skill payload. Must be `application/zip`. - `:"application/zip"` - `type: :base64` The type of the inline skill source. Must be `base64`. - `:base64` - `type: :inline` Defines an inline skill for this request. - `:inline` - `class BetaLocalEnvironment` - `type: :local` Use a local computer environment. - `:local` - `skills: Array[BetaLocalSkill]` An optional list of skills. - `description: String` The description of the skill. - `name: String` The name of the skill. - `path: String` The path to the directory containing the skill. - `class BetaContainerReference` - `container_id: String` The ID of the referenced container. - `type: :container_reference` References a container created with the /v1/containers endpoint - `:container_reference` - `class BetaCustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: String` The name of the custom tool, used to identify it in tool calls. - `type: :custom` The type of the custom tool. Always `custom`. - `:custom` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. - `description: String` Optional description of the custom tool, used to provide more context. - `format_: Text{ type} | Grammar{ definition, syntax, type}` The input format for the custom tool. Default is unconstrained text. - `class Text` Unconstrained free-form text. - `type: :text` Unconstrained text format. Always `text`. - `:text` - `class Grammar` A grammar defined by the user. - `definition: String` The grammar definition. - `syntax: :lark | :regex` The syntax of the grammar definition. One of `lark` or `regex`. - `:lark` - `:regex` - `type: :grammar` Grammar format. Always `grammar`. - `:grammar` - `class BetaNamespaceTool` Groups function/custom tools under a shared namespace. - `description: String` A description of the namespace shown to the model. - `name: String` The namespace name used in tool calls (for example, `crm`). - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` The function/custom tools available inside this namespace. - `class Function` - `name: String` - `type: :function` - `:function` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` - `output_schema: Hash[Symbol, untyped]` A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - `parameters: untyped` - `strict: bool` 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. - `class BetaCustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `type: :namespace` The type of the tool. Always `namespace`. - `:namespace` - `class BetaToolSearchTool` Hosted or BYOT tool search configuration for deferred tools. - `type: :tool_search` The type of the tool. Always `tool_search`. - `:tool_search` - `description: String` Description shown to the model for a client-executed tool search tool. - `execution: :server | :client` Whether tool search is executed by the server or by the client. - `:server` - `:client` - `parameters: untyped` Parameter schema for a client-executed tool search tool. - `class BetaWebSearchPreviewTool` This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: :web_search_preview | :web_search_preview_2025_03_11` 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` - `search_content_types: Array[:text | :image]` - `:text` - `:image` - `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. - `:low` - `:medium` - `:high` - `user_location: UserLocation{ type, city, country, 2 more}` The user's location. - `type: :approximate` The type of location approximation. Always `approximate`. - `:approximate` - `city: String` Free text input for the city of the user, e.g. `San Francisco`. - `country: String` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region: String` Free text input for the region of the user, e.g. `California`. - `timezone: String` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `class BetaApplyPatchTool` Allows the assistant to create, delete, or update files using unified diffs. - `type: :apply_patch` The type of the tool. Always `apply_patch`. - `:apply_patch` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `type: :tool_search_output` The item type. Always `tool_search_output`. - `:tool_search_output` - `id: String` The unique ID of this tool search output. - `agent: Agent{ agent_name}` 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 tool search call generated by the model. - `execution: :server | :client` Whether tool search was executed by the server or by the client. - `:server` - `:client` - `status: :in_progress | :completed | :incomplete` The status of the tool search output. - `:in_progress` - `:completed` - `:incomplete` - `class AdditionalTools` - `role: :developer` The role that provided the additional tools. Only `developer` is supported. - `:developer` - `tools: Array[BetaTool]` A list of additional tools made available at this item. - `class BetaFunctionTool` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `class BetaFileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `class BetaComputerTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `class BetaComputerUsePreviewTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `class BetaWebSearchTool` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `class Mcp` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `class CodeInterpreter` A tool that runs Python code to help generate a response to a prompt. - `class ProgrammaticToolCalling` - `class ImageGeneration` A tool that generates images using the GPT image models. - `class LocalShell` A tool that allows the model to execute shell commands in a local environment. - `class BetaFunctionShellTool` A tool that allows the model to execute shell commands. - `class BetaCustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `class BetaNamespaceTool` Groups function/custom tools under a shared namespace. - `class BetaToolSearchTool` Hosted or BYOT tool search configuration for deferred tools. - `class BetaWebSearchPreviewTool` This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `class BetaApplyPatchTool` Allows the assistant to create, delete, or update files using unified diffs. - `type: :additional_tools` The item type. Always `additional_tools`. - `:additional_tools` - `id: String` The unique ID of this additional tools item. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class BetaResponseReasoningItem` 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://platform.openai.com/docs/guides/conversation-state). - `id: String` The unique identifier of the reasoning content. - `summary: Array[Summary{ text, type}]` Reasoning summary content. - `text: String` A summary of the reasoning output from the model so far. - `type: :summary_text` The type of the object. Always `summary_text`. - `:summary_text` - `type: :reasoning` The type of the object. Always `reasoning`. - `:reasoning` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `content: Array[Content{ text, type}]` Reasoning text content. - `text: String` The reasoning text from the model. - `type: :reasoning_text` The type of the reasoning text. Always `reasoning_text`. - `:reasoning_text` - `encrypted_content: String` The encrypted content of the reasoning item - populated when a response is generated with `reasoning.encrypted_content` in the `include` parameter. - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` - `:completed` - `:incomplete` - `class BetaResponseCompactionItemParam` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: String` The encrypted content of the compaction summary. - `type: :compaction` The type of the item. Always `compaction`. - `:compaction` - `id: String` The ID of the compaction item. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class ImageGenerationCall` An image generation request made by the model. - `id: String` The unique ID of the image generation call. - `result: String` The generated image encoded in base64. - `status: :in_progress | :completed | :generating | :failed` The status of the image generation call. - `:in_progress` - `:completed` - `:generating` - `:failed` - `type: :image_generation_call` The type of the image generation call. Always `image_generation_call`. - `:image_generation_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class BetaResponseCodeInterpreterToolCall` A tool call to run code. - `id: String` The unique ID of the code interpreter tool call. - `code: String` The code to run, or null if not available. - `container_id: String` The ID of the container used to run the code. - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - `class Logs` The logs output from the code interpreter. - `logs: String` The logs output from the code interpreter. - `type: :logs` The type of the output. Always `logs`. - `:logs` - `class Image` The image output from the code interpreter. - `type: :image` The type of the output. Always `image`. - `:image` - `url: String` The URL of the image output from the code interpreter. - `status: :in_progress | :completed | :incomplete | 2 more` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `:in_progress` - `:completed` - `:incomplete` - `:interpreting` - `:failed` - `type: :code_interpreter_call` The type of the code interpreter tool call. Always `code_interpreter_call`. - `:code_interpreter_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class LocalShellCall` A tool call to run a command on the local shell. - `id: String` The unique ID of the local shell call. - `action: Action{ command, env, type, 3 more}` Execute a shell command on the server. - `command: Array[String]` The command to run. - `env: Hash[Symbol, String]` Environment variables to set for the command. - `type: :exec` The type of the local shell action. Always `exec`. - `:exec` - `timeout_ms: Integer` Optional timeout in milliseconds for the command. - `user: String` Optional user to run the command as. - `working_directory: String` Optional working directory to run the command in. - `call_id: String` The unique ID of the local shell tool call generated by the model. - `status: :in_progress | :completed | :incomplete` The status of the local shell call. - `:in_progress` - `:completed` - `:incomplete` - `type: :local_shell_call` The type of the local shell call. Always `local_shell_call`. - `:local_shell_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class LocalShellCallOutput` The output of a local shell tool call. - `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. - `type: :local_shell_call_output` The type of the local shell tool call output. Always `local_shell_call_output`. - `:local_shell_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. - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` - `:completed` - `:incomplete` - `class ShellCall` A tool representing a request to execute one or more shell commands. - `action: Action{ commands, max_output_length, timeout_ms}` The shell commands and limits that describe how to run the tool call. - `commands: Array[String]` Ordered shell commands for the execution environment to run. - `max_output_length: Integer` Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `timeout_ms: Integer` Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: String` The unique ID of the shell tool call generated by the model. - `type: :shell_call` The type of the item. Always `shell_call`. - `:shell_call` - `id: String` The unique ID of the shell tool call. Populated when this item is returned via API. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` The caller type. Always `direct`. - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` The caller type. Always `program`. - `:program` - `environment: BetaLocalEnvironment | BetaContainerReference` The environment to execute the shell commands in. - `class BetaLocalEnvironment` - `class BetaContainerReference` - `status: :in_progress | :completed | :incomplete` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` - `:completed` - `:incomplete` - `class ShellCallOutput` The streamed output items emitted by a shell tool call. - `call_id: String` The unique ID of the shell tool call generated by the model. - `output: Array[BetaResponseFunctionShellCallOutputContent]` Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: Timeout{ type} | Exit{ exit_code, type}` The exit or timeout outcome associated with this shell call. - `class Timeout` Indicates that the shell call exceeded its configured time limit. - `type: :timeout` The outcome type. Always `timeout`. - `:timeout` - `class Exit` Indicates that the shell commands finished and returned an exit code. - `exit_code: Integer` The exit code returned by the shell process. - `type: :exit` The outcome type. Always `exit`. - `:exit` - `stderr: String` Captured stderr output for the shell call. - `stdout: String` Captured stdout output for the shell call. - `type: :shell_call_output` The type of the item. Always `shell_call_output`. - `:shell_call_output` - `id: String` The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` The caller type. Always `direct`. - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` The caller type. Always `program`. - `:program` - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. - `status: :in_progress | :completed | :incomplete` The status of the shell call output. - `:in_progress` - `:completed` - `:incomplete` - `class ApplyPatchCall` A tool call representing a request to create, delete, or update files using diff patches. - `call_id: String` The unique ID of the apply patch tool call generated by the model. - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` The specific create, delete, or update instruction for the apply_patch tool call. - `class CreateFile` Instruction for creating a new file via the apply_patch tool. - `diff: String` Unified diff content to apply when creating the file. - `path: String` Path of the file to create relative to the workspace root. - `type: :create_file` The operation type. Always `create_file`. - `:create_file` - `class DeleteFile` Instruction for deleting an existing file via the apply_patch tool. - `path: String` Path of the file to delete relative to the workspace root. - `type: :delete_file` The operation type. Always `delete_file`. - `:delete_file` - `class UpdateFile` Instruction for updating an existing file via the apply_patch tool. - `diff: String` Unified diff content to apply to the existing file. - `path: String` Path of the file to update relative to the workspace root. - `type: :update_file` The operation type. Always `update_file`. - `:update_file` - `status: :in_progress | :completed` The status of the apply patch tool call. One of `in_progress` or `completed`. - `:in_progress` - `:completed` - `type: :apply_patch_call` The type of the item. Always `apply_patch_call`. - `:apply_patch_call` - `id: String` The unique ID of the apply patch tool call. Populated when this item is returned via API. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` The caller type. Always `direct`. - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` The caller type. Always `program`. - `:program` - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. - `call_id: String` The unique ID of the apply patch tool call generated by the model. - `status: :completed | :failed` The status of the apply patch tool call output. One of `completed` or `failed`. - `:completed` - `:failed` - `type: :apply_patch_call_output` The type of the item. Always `apply_patch_call_output`. - `:apply_patch_call_output` - `id: String` The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` The caller type. Always `direct`. - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` The caller type. Always `program`. - `:program` - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `class McpListTools` A list of tools available on an MCP server. - `id: String` The unique ID of the list. - `server_label: String` The label of the MCP server. - `tools: Array[Tool{ input_schema, name, annotations, description}]` The tools available on the server. - `input_schema: untyped` The JSON schema describing the tool's input. - `name: String` The name of the tool. - `annotations: untyped` Additional annotations about the tool. - `description: String` The description of the tool. - `type: :mcp_list_tools` The type of the item. Always `mcp_list_tools`. - `:mcp_list_tools` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `error: String` Error message if the server could not list tools. - `class McpApprovalRequest` A request for human approval of a tool invocation. - `id: String` The unique ID of the approval request. - `arguments: String` A JSON string of arguments for the tool. - `name: String` The name of the tool to run. - `server_label: String` The label of the MCP server making the request. - `type: :mcp_approval_request` The type of the item. Always `mcp_approval_request`. - `:mcp_approval_request` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class McpApprovalResponse` A response to an MCP approval request. - `approval_request_id: String` The ID of the approval request being answered. - `approve: bool` Whether the request was approved. - `type: :mcp_approval_response` The type of the item. Always `mcp_approval_response`. - `:mcp_approval_response` - `id: String` The unique ID of the approval response - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `reason: String` Optional reason for the decision. - `class McpCall` An invocation of a tool on an MCP server. - `id: String` The unique ID of the tool call. - `arguments: String` A JSON string of the arguments passed to the tool. - `name: String` The name of the tool that was run. - `server_label: String` The label of the MCP server running the tool. - `type: :mcp_call` The type of the item. Always `mcp_call`. - `:mcp_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `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. - `error: String` The error from the tool call, if any. - `output: String` The output from the tool call. - `status: :in_progress | :completed | :incomplete | 2 more` The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `:in_progress` - `:completed` - `:incomplete` - `:calling` - `:failed` - `class BetaResponseCustomToolCallOutput` The output of a custom tool call from your code, being sent back to the model. - `call_id: String` The call ID, used to map this custom tool call output to a custom tool call. - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` The output from the custom tool call generated by your code. Can be a string or an list of output content. - `String = String` A string of the output of the custom tool call. - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` Text, image, or file output of the custom tool call. - `class BetaResponseInputText` A text input to the model. - `class BetaResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `class BetaResponseInputFile` A file input to the model. - `type: :custom_tool_call_output` 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. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` The caller type. Always `direct`. - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` The caller type. Always `program`. - `:program` - `class BetaResponseCustomToolCall` A call to a custom tool created by the model. - `call_id: String` An identifier used to map this custom tool call to a tool call output. - `input: String` The input for the custom tool call generated by the model. - `name: String` The name of the custom tool being called. - `type: :custom_tool_call` 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. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `namespace: String` The namespace of the custom tool being called. - `class CompactionTrigger` Compacts the current context. Must be the final input item. - `type: :compaction_trigger` The type of the item. Always `compaction_trigger`. - `:compaction_trigger` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class ItemReference` An internal identifier for an item to reference. - `id: String` The ID of the item to reference. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `type: :item_reference` The type of item to reference. Always `item_reference`. - `:item_reference` - `class Program` - `id: String` The unique ID of this 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. - `type: :program` The item type. Always `program`. - `:program` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class ProgramOutput` - `id: String` The unique ID of this program output item. - `call_id: String` The call ID of the program item. - `result: String` The result produced by the program item. - `status: :completed | :incomplete` The terminal status of the program output. - `:completed` - `:incomplete` - `type: :program_output` The item type. Always `program_output`. - `:program_output` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `instructions: String` A system (or developer) message inserted into the model's context. When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - `previous_response_id: String` The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `prompt_cache_key: String` A key to use when reading from or writing to the prompt cache. - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. - `mode: :implicit | :explicit` Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - `:implicit` - `:explicit` - `ttl: :"30m"` The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - `:"30m"` - `prompt_cache_retention: :in_memory | :"24h"` How long to retain a prompt cache entry created by this request. - `:in_memory` - `:"24h"` - `service_tier: :auto | :default | :flex | :priority` The service tier to use for this request. - `:auto` - `:default` - `:flex` - `:priority` - `betas: Array[:"responses_multi_agent=v1"]` - `:"responses_multi_agent=v1"` ### Returns - `class BetaCompactedResponse` - `id: String` The unique identifier for the compacted response. - `created_at: Integer` Unix timestamp (in seconds) when the compacted conversation was created. - `object: :"response.compaction"` The object type. Always `response.compaction`. - `:"response.compaction"` - `output: Array[BetaResponseOutputItem]` The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - `class BetaResponseOutputMessage` An output message from the model. - `id: String` The unique ID of the output message. - `content: Array[BetaResponseOutputText | BetaResponseOutputRefusal]` The content of the output message. - `class BetaResponseOutputText` 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. - `class FileCitation` A citation to a file. - `file_id: String` The ID of the file. - `filename: String` The filename of the file cited. - `index: Integer` The index of the file in the list of files. - `type: :file_citation` The type of the file citation. Always `file_citation`. - `:file_citation` - `class URLCitation` A citation for a web resource used to generate a model response. - `end_index: Integer` The index of the last character of the URL citation in the message. - `start_index: Integer` 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_citation` - `url: String` The URL of the web resource. - `class ContainerFileCitation` A citation for a container file used to generate a model response. - `container_id: String` The ID of the container file. - `end_index: Integer` 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: Integer` 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`. - `:container_file_citation` - `class FilePath` A path to a file. - `file_id: String` The ID of the file. - `index: Integer` The index of the file in the list of files. - `type: :file_path` The type of the file path. Always `file_path`. - `:file_path` - `text: String` The text output from the model. - `type: :output_text` The type of the output text. Always `output_text`. - `:output_text` - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - `token: String` - `bytes: Array[Integer]` - `logprob: Float` - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]` - `token: String` - `bytes: Array[Integer]` - `logprob: Float` - `class BetaResponseOutputRefusal` A refusal from the model. - `refusal: String` The refusal explanation from the model. - `type: :refusal` The type of the refusal. Always `refusal`. - `:refusal` - `role: :assistant` The role of the output message. Always `assistant`. - `: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. - `:in_progress` - `:completed` - `:incomplete` - `type: :message` The type of the output message. Always `message`. - `:message` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `phase: :commentary` 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. - `:commentary` - `class BetaResponseFileSearchToolCall` The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) 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`, - `:in_progress` - `:searching` - `:completed` - `:incomplete` - `:failed` - `type: :file_search_call` The type of the file search tool call. Always `file_search_call`. - `:file_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. - `results: Array[Result{ attributes, file_id, filename, 2 more}]` The results of the file search tool call. - `attributes: Hash[Symbol, String | Float | bool]` 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. - `String = String` - `Float = Float` - `UnionMember2 = bool` - `file_id: String` The unique ID of the file. - `filename: String` The name of the file. - `score: Float` The relevance score of the file - a value between 0 and 1. - `text: String` The text that was retrieved from the file. - `class BetaResponseFunctionToolCall` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: String` A JSON string of the arguments to pass to the function. - `call_id: String` The unique ID of the function tool call generated by the model. - `name: String` The name of the function to run. - `type: :function_call` The type of the function tool call. Always `function_call`. - `:function_call` - `id: String` The unique ID of the function tool call. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `namespace: String` The namespace of the function to run. - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` - `:completed` - `:incomplete` - `class BetaResponseFunctionToolCallOutputItem` - `id: String` The unique ID of the function call tool output. - `call_id: String` The unique ID of the function tool call generated by the model. - `output: String | Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` The output from the function call generated by your code. Can be a string or an list of output content. - `String = String` A string of the output of the function call. - `OutputContentList = Array[BetaResponseInputText | BetaResponseInputImage | BetaResponseInputFile]` Text, image, or file output of the function call. - `class BetaResponseInputText` 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`. - `: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`. - `:explicit` - `class BetaResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: :low | :high | :auto | :original` 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` - `type: :input_image` The type of the input item. Always `input_image`. - `:input_image` - `file_id: String` The ID of the file to be sent to the model. - `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. - `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`. - `:explicit` - `class BetaResponseInputFile` A file input to the model. - `type: :input_file` The type of the input item. Always `input_file`. - `: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`. - `:auto` - `:low` - `:high` - `file_data: String` The content of the file to be sent to the model. - `file_id: String` 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. - `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`. - `: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. - `:in_progress` - `:completed` - `:incomplete` - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. - `:function_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. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` The caller type. Always `direct`. - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` The caller type. Always `program`. - `:program` - `created_by: String` The identifier of the actor that created the item. - `class AgentMessage` - `id: String` The unique ID of the agent message. - `author: String` The sending agent identity. - `content: Array[BetaResponseInputText | BetaResponseOutputText | Text{ text, type} | 7 more]` Encrypted content sent between agents. - `class BetaResponseInputText` A text input to the model. - `class BetaResponseOutputText` A text output from the model. - `class Text` A text content. - `text: String` - `type: :text` - `:text` - `class SummaryText` 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`. - `:summary_text` - `class ReasoningText` 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`. - `:reasoning_text` - `class BetaResponseOutputRefusal` A refusal from the model. - `class BetaResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `class ComputerScreenshot` A screenshot of a computer. - `detail: :low | :high | :auto | :original` 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` - `file_id: String` The identifier of an uploaded file that contains the screenshot. - `image_url: String` The URL of the screenshot image. - `type: :computer_screenshot` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `: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`. - `:explicit` - `class BetaResponseInputFile` A file input to the model. - `class EncryptedContent` 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`. - `:encrypted_content` - `recipient: String` The destination agent identity. - `type: :agent_message` The type of the item. Always `agent_message`. - `: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. - `class MultiAgentCall` - `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. - `: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`. - `: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. - `class MultiAgentCallOutput` - `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. - `: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]` 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. - `text: String` The text output from the model. - `type: :output_text` The type of the output text. Always `output_text`. - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]` - `type: :multi_agent_call_output` The type of the multi-agent result. Always `multi_agent_call_output`. - `: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. - `class BetaResponseFunctionWebSearch` The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: String` The unique ID of the web search tool call. - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}` 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). - `class Search` Action type "search" - Performs a web search query. - `type: :search` The action type. - `:search` - `queries: Array[String]` The search queries. - `query: String` The search query. - `sources: Array[Source{ type, url}]` The sources used in the search. - `type: :url` The type of source. Always `url`. - `:url` - `url: String` The URL of the source. - `class OpenPage` Action type "open_page" - Opens a specific URL from search results. - `type: :open_page` The action type. - `:open_page` - `url: String` The URL opened by the model. - `class FindInPage` Action type "find_in_page": Searches for a pattern within a loaded page. - `pattern: String` The pattern or text to search for within the page. - `type: :find_in_page` The action type. - `:find_in_page` - `url: String` The URL of the page searched for the pattern. - `status: :in_progress | :searching | :completed | :failed` The status of the web search tool call. - `:in_progress` - `:searching` - `:completed` - `:failed` - `type: :web_search_call` The type of the web search tool call. Always `web_search_call`. - `:web_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. - `class BetaResponseComputerToolCall` A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) 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{ id, code, message}]` The pending safety checks for the computer call. - `id: String` The ID of the pending safety check. - `code: String` The type of the pending safety check. - `message: String` 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. - `:in_progress` - `:completed` - `:incomplete` - `type: :computer_call` The type of the computer call. Always `computer_call`. - `:computer_call` - `action: BetaComputerAction` A click action. - `class Click` A click action. - `button: :left | :right | :wheel | 2 more` Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - `:left` - `:right` - `:wheel` - `:back` - `:forward` - `type: :click` Specifies the event type. For a click action, this property is always `click`. - `:click` - `x: Integer` The x-coordinate where the click occurred. - `y_: Integer` The y-coordinate where the click occurred. - `keys: Array[String]` The keys being held while clicking. - `class DoubleClick` A double click action. - `keys: Array[String]` The keys being held while double-clicking. - `type: :double_click` Specifies the event type. For a double click action, this property is always set to `double_click`. - `:double_click` - `x: Integer` The x-coordinate where the double click occurred. - `y_: Integer` The y-coordinate where the double click occurred. - `class Drag` A drag action. - `path: Array[Path{ x, y_}]` 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 } ] ``` - `x: Integer` The x-coordinate. - `y_: Integer` The y-coordinate. - `type: :drag` Specifies the event type. For a drag action, this property is always set to `drag`. - `:drag` - `keys: Array[String]` The keys being held while dragging the mouse. - `class Keypress` A collection of keypresses the model would like to perform. - `keys: Array[String]` The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `type: :keypress` Specifies the event type. For a keypress action, this property is always set to `keypress`. - `:keypress` - `class Move` A mouse move action. - `type: :move` Specifies the event type. For a move action, this property is always set to `move`. - `:move` - `x: Integer` The x-coordinate to move to. - `y_: Integer` The y-coordinate to move to. - `keys: Array[String]` The keys being held while moving the mouse. - `class Screenshot` A screenshot action. - `type: :screenshot` Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - `:screenshot` - `class Scroll` A scroll action. - `scroll_x: Integer` The horizontal scroll distance. - `scroll_y: Integer` The vertical scroll distance. - `type: :scroll` Specifies the event type. For a scroll action, this property is always set to `scroll`. - `:scroll` - `x: Integer` The x-coordinate where the scroll occurred. - `y_: Integer` The y-coordinate where the scroll occurred. - `keys: Array[String]` The keys being held while scrolling. - `class Type` An action to type in text. - `text: String` The text to type. - `type: :type` Specifies the event type. For a type action, this property is always set to `type`. - `:type` - `class Wait` A wait action. - `type: :wait` Specifies the event type. For a wait action, this property is always set to `wait`. - `:wait` - `actions: BetaComputerActionList` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - `class Click` A click action. - `class DoubleClick` A double click action. - `class Drag` A drag action. - `class Keypress` A collection of keypresses the model would like to perform. - `class Move` A mouse move action. - `class Screenshot` A screenshot action. - `class Scroll` A scroll action. - `class Type` An action to type in text. - `class Wait` A wait action. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class BetaResponseComputerToolCallOutputItem` - `id: String` The unique ID of the computer call tool output. - `call_id: String` The ID of the computer tool call that produced the output. - `output: BetaResponseComputerToolCallOutputScreenshot` A computer screenshot image used with the computer use tool. - `type: :computer_screenshot` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `:computer_screenshot` - `file_id: String` The identifier of an uploaded file that contains the screenshot. - `image_url: String` The URL of the screenshot image. - `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. - `:completed` - `:incomplete` - `:failed` - `:in_progress` - `type: :computer_call_output` The type of the computer tool call output. Always `computer_call_output`. - `:computer_call_output` - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]` 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` The type of the pending safety check. - `message: String` Details about the pending safety check. - `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. - `class BetaResponseReasoningItem` 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://platform.openai.com/docs/guides/conversation-state). - `id: String` The unique identifier of the reasoning content. - `summary: Array[Summary{ text, type}]` Reasoning summary content. - `text: String` A summary of the reasoning output from the model so far. - `type: :summary_text` The type of the object. Always `summary_text`. - `:summary_text` - `type: :reasoning` The type of the object. Always `reasoning`. - `:reasoning` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `content: Array[Content{ text, type}]` Reasoning text content. - `text: String` The reasoning text from the model. - `type: :reasoning_text` The type of the reasoning text. Always `reasoning_text`. - `:reasoning_text` - `encrypted_content: String` The encrypted content of the reasoning item - populated when a response is generated with `reasoning.encrypted_content` in the `include` parameter. - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` - `:completed` - `:incomplete` - `class 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. - `type: :program` The type of the item. Always `program`. - `:program` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class ProgramOutput` - `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: :completed | :incomplete` The terminal status of the program output item. - `:completed` - `:incomplete` - `type: :program_output` The type of the item. Always `program_output`. - `:program_output` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class BetaResponseToolSearchCall` - `id: String` The unique ID of the tool search call item. - `arguments: untyped` Arguments used for the tool search call. - `call_id: String` 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. - `:server` - `:client` - `status: :in_progress | :completed | :incomplete` The status of the tool search call item that was recorded. - `:in_progress` - `:completed` - `:incomplete` - `type: :tool_search_call` The type of the item. Always `tool_search_call`. - `: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. - `class BetaResponseToolSearchOutputItem` - `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. - `execution: :server | :client` Whether tool search was executed by the server or by the client. - `:server` - `:client` - `status: :in_progress | :completed | :incomplete` The status of the tool search output item that was recorded. - `:in_progress` - `:completed` - `:incomplete` - `tools: Array[BetaTool]` The loaded tool definitions returned by tool search. - `class BetaFunctionTool` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `name: String` The name of the function to call. - `parameters: Hash[Symbol, untyped]` A JSON schema object describing the parameters of the function. - `strict: bool` Whether strict parameter validation is enforced for this function tool. - `type: :function` The type of the function tool. Always `function`. - `:function` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `defer_loading: bool` Whether this function is deferred and loaded via tool search. - `description: String` A description of the function. Used by the model to determine whether or not to call the function. - `output_schema: Hash[Symbol, untyped]` A JSON schema object describing the JSON value encoded in string outputs for this function. - `class BetaFileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `type: :file_search` The type of the file search tool. Always `file_search`. - `:file_search` - `vector_store_ids: Array[String]` The IDs of the vector stores to search. - `filters: ComparisonFilter{ key, type, value} | CompoundFilter{ filters, type}` A filter to apply. - `class ComparisonFilter` 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 - `:eq` - `:ne` - `:gt` - `:gte` - `:lt` - `:lte` - `:in` - `:nin` - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. - `String = String` - `Float = Float` - `UnionMember2 = bool` - `UnionMember3 = Array[untyped]` - `class CompoundFilter` Combine multiple filters using `and` or `or`. - `filters: Array[ComparisonFilter{ key, type, value} | untyped]` Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - `class ComparisonFilter` 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 - `:eq` - `:ne` - `:gt` - `:gte` - `:lt` - `:lte` - `:in` - `:nin` - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. - `String = String` - `Float = Float` - `UnionMember2 = bool` - `UnionMember3 = Array[untyped]` - `UnionMember1 = untyped` - `type: :and | :or` Type of operation: `and` or `or`. - `:and` - `:or` - `max_num_results: Integer` 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. - `hybrid_search: HybridSearch{ embedding_weight, text_weight}` Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - `embedding_weight: Float` The weight of the embedding in the reciprocal ranking fusion. - `text_weight: Float` The weight of the text in the reciprocal ranking fusion. - `ranker: :auto | :"default-2024-11-15"` The ranker to use for the file search. - `:auto` - `:"default-2024-11-15"` - `score_threshold: Float` 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. - `class BetaComputerTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `type: :computer` The type of the computer tool. Always `computer`. - `:computer` - `class BetaComputerUsePreviewTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `display_height: Integer` The height of the computer display. - `display_width: Integer` The width of the computer display. - `environment: :windows | :mac | :linux | 2 more` The type of computer environment to control. - `:windows` - `:mac` - `:linux` - `:ubuntu` - `:browser` - `type: :computer_use_preview` The type of the computer use tool. Always `computer_use_preview`. - `:computer_use_preview` - `class BetaWebSearchTool` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `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`. - `:web_search` - `:web_search_2025_08_26` - `filters: Filters{ allowed_domains}` Filters for the search. - `allowed_domains: Array[String]` 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. - `:low` - `:medium` - `:high` - `user_location: UserLocation{ city, country, region, 2 more}` The approximate location of the user. - `city: String` Free text input for the city of the user, e.g. `San Francisco`. - `country: String` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region: String` Free text input for the region of the user, e.g. `California`. - `timezone: String` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `type: :approximate` The type of location approximation. Always `approximate`. - `:approximate` - `class Mcp` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: String` A label for this MCP server, used to identify it in tool calls. - `type: :mcp` The type of the MCP tool. Always `mcp`. - `:mcp` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. - `McpAllowedTools = Array[String]` A string array of allowed tool names - `class McpToolFilter` A filter object to specify which tools are allowed. - `read_only: bool` 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. - `tool_names: Array[String]` List of allowed tool names. - `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. - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more` 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://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - Google Calendar: `connector_googlecalendar` - Google Drive: `connector_googledrive` - Microsoft Teams: `connector_microsoftteams` - Outlook Calendar: `connector_outlookcalendar` - Outlook Email: `connector_outlookemail` - SharePoint: `connector_sharepoint` - `:connector_dropbox` - `:connector_gmail` - `:connector_googlecalendar` - `:connector_googledrive` - `:connector_microsoftteams` - `:connector_outlookcalendar` - `:connector_outlookemail` - `:connector_sharepoint` - `defer_loading: bool` Whether this MCP tool is deferred and discovered via tool search. - `headers: Hash[Symbol, String]` Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never` Specify which of the MCP server's tools require approval. - `class McpToolApprovalFilter` Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval. - `always: Always{ read_only, tool_names}` A filter object to specify which tools are allowed. - `read_only: bool` 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. - `tool_names: Array[String]` List of allowed tool names. - `never: Never{ read_only, tool_names}` A filter object to specify which tools are allowed. - `read_only: bool` 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. - `tool_names: Array[String]` List of allowed tool names. - `McpToolApprovalSetting = :always | :never` Specify a single approval policy for all tools. One of `always` or `never`. When set to `always`, all tools will require approval. When set to `never`, all tools will not require approval. - `:always` - `:never` - `server_description: String` Optional description of the MCP server, used to provide more context. - `server_url: String` The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `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. - `class CodeInterpreter` A tool that runs Python code to help generate a response to a prompt. - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}` 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. - `String = String` The container ID. - `class CodeInterpreterToolAuto` Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `type: :auto` Always `auto`. - `:auto` - `file_ids: Array[String]` An optional list of uploaded files to make available to your code. - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` The memory limit for the code interpreter container. - `:"1g"` - `:"4g"` - `:"16g"` - `:"64g"` - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled` - `type: :disabled` Disable outbound network access. Always `disabled`. - `:disabled` - `class BetaContainerNetworkPolicyAllowlist` - `allowed_domains: Array[String]` A list of allowed domains when type is `allowlist`. - `type: :allowlist` Allow outbound network access only to specified domains. Always `allowlist`. - `:allowlist` - `domain_secrets: Array[BetaContainerNetworkPolicyDomainSecret]` Optional domain-scoped secrets for allowlisted domains. - `domain: String` The domain associated with the secret. - `name: String` The name of the secret to inject for the domain. - `value: String` The secret value to inject for the domain. - `type: :code_interpreter` The type of the code interpreter tool. Always `code_interpreter`. - `:code_interpreter` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `class ProgrammaticToolCalling` - `type: :programmatic_tool_calling` The type of the tool. Always `programmatic_tool_calling`. - `:programmatic_tool_calling` - `class ImageGeneration` A tool that generates images using the GPT image models. - `type: :image_generation` The type of the image generation tool. Always `image_generation`. - `:image_generation` - `action: :generate | :edit | :auto` Whether to generate a new image or edit an existing image. Default: `auto`. - `:generate` - `:edit` - `:auto` - `background: :transparent | :opaque | :auto` Allows to set transparency for the background of the generated image(s). This parameter is only supported for GPT image models that support transparent backgrounds. 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. `gpt-image-2` and `gpt-image-2-2026-04-21` do not support transparent backgrounds. Requests with `background` set to `transparent` will return an error for these models; use `opaque` or `auto` instead. If `transparent`, the output format needs to support transparency, so it should be set to either `png` (default value) or `webp`. - `:transparent` - `:opaque` - `:auto` - `input_fidelity: :high | :low` Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - `:high` - `:low` - `input_image_mask: InputImageMask{ file_id, image_url}` Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). - `file_id: String` File ID for the mask image. - `image_url: String` Base64-encoded mask image. - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` The image generation model to use. Default: `gpt-image-1`. - `String = String` - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more` The image generation model to use. Default: `gpt-image-1`. - `:"gpt-image-1"` - `:"gpt-image-1-mini"` - `:"gpt-image-2"` - `:"gpt-image-2-2026-04-21"` - `:"gpt-image-1.5"` - `:"chatgpt-image-latest"` - `moderation: :auto | :low` Moderation level for the generated image. Default: `auto`. - `:auto` - `:low` - `output_compression: Integer` Compression level for the output image. Default: 100. - `output_format: :png | :webp | :jpeg` The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. - `:png` - `:webp` - `:jpeg` - `partial_images: Integer` Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `quality: :low | :medium | :high | :auto` The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. Default: `auto`. - `:low` - `:medium` - `:high` - `:auto` - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - `String = String` - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto` The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - `:"1024x1024"` - `:"1024x1536"` - `:"1536x1024"` - `:auto` - `class LocalShell` A tool that allows the model to execute shell commands in a local environment. - `type: :local_shell` The type of the local shell tool. Always `local_shell`. - `:local_shell` - `class BetaFunctionShellTool` A tool that allows the model to execute shell commands. - `type: :shell` The type of the shell tool. Always `shell`. - `:shell` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `environment: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference` - `class BetaContainerAuto` - `type: :container_auto` Automatically creates a container for this request - `:container_auto` - `file_ids: Array[String]` An optional list of uploaded files to make available to your code. - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"` The memory limit for the container. - `:"1g"` - `:"4g"` - `:"16g"` - `:"64g"` - `network_policy: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled` - `class BetaContainerNetworkPolicyAllowlist` - `skills: Array[BetaSkillReference | BetaInlineSkill]` An optional list of skills referenced by id or inline data. - `class BetaSkillReference` - `skill_id: String` The ID of the referenced skill. - `type: :skill_reference` References a skill created with the /v1/skills endpoint. - `:skill_reference` - `version: String` Optional skill version. Use a positive integer or 'latest'. Omit for default. - `class BetaInlineSkill` - `description: String` The description of the skill. - `name: String` The name of the skill. - `source: BetaInlineSkillSource` Inline skill payload - `data: String` Base64-encoded skill zip bundle. - `media_type: :"application/zip"` The media type of the inline skill payload. Must be `application/zip`. - `:"application/zip"` - `type: :base64` The type of the inline skill source. Must be `base64`. - `:base64` - `type: :inline` Defines an inline skill for this request. - `:inline` - `class BetaLocalEnvironment` - `type: :local` Use a local computer environment. - `:local` - `skills: Array[BetaLocalSkill]` An optional list of skills. - `description: String` The description of the skill. - `name: String` The name of the skill. - `path: String` The path to the directory containing the skill. - `class BetaContainerReference` - `container_id: String` The ID of the referenced container. - `type: :container_reference` References a container created with the /v1/containers endpoint - `:container_reference` - `class BetaCustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: String` The name of the custom tool, used to identify it in tool calls. - `type: :custom` The type of the custom tool. Always `custom`. - `:custom` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. - `description: String` Optional description of the custom tool, used to provide more context. - `format_: Text{ type} | Grammar{ definition, syntax, type}` The input format for the custom tool. Default is unconstrained text. - `class Text` Unconstrained free-form text. - `type: :text` Unconstrained text format. Always `text`. - `:text` - `class Grammar` A grammar defined by the user. - `definition: String` The grammar definition. - `syntax: :lark | :regex` The syntax of the grammar definition. One of `lark` or `regex`. - `:lark` - `:regex` - `type: :grammar` Grammar format. Always `grammar`. - `:grammar` - `class BetaNamespaceTool` Groups function/custom tools under a shared namespace. - `description: String` A description of the namespace shown to the model. - `name: String` The namespace name used in tool calls (for example, `crm`). - `tools: Array[Function{ name, type, allowed_callers, 5 more} | BetaCustomTool]` The function/custom tools available inside this namespace. - `class Function` - `name: String` - `type: :function` - `:function` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` - `output_schema: Hash[Symbol, untyped]` A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - `parameters: untyped` - `strict: bool` 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. - `class BetaCustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `type: :namespace` The type of the tool. Always `namespace`. - `:namespace` - `class BetaToolSearchTool` Hosted or BYOT tool search configuration for deferred tools. - `type: :tool_search` The type of the tool. Always `tool_search`. - `:tool_search` - `description: String` Description shown to the model for a client-executed tool search tool. - `execution: :server | :client` Whether tool search is executed by the server or by the client. - `:server` - `:client` - `parameters: untyped` Parameter schema for a client-executed tool search tool. - `class BetaWebSearchPreviewTool` This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: :web_search_preview | :web_search_preview_2025_03_11` 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` - `search_content_types: Array[:text | :image]` - `:text` - `:image` - `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. - `:low` - `:medium` - `:high` - `user_location: UserLocation{ type, city, country, 2 more}` The user's location. - `type: :approximate` The type of location approximation. Always `approximate`. - `:approximate` - `city: String` Free text input for the city of the user, e.g. `San Francisco`. - `country: String` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region: String` Free text input for the region of the user, e.g. `California`. - `timezone: String` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `class BetaApplyPatchTool` Allows the assistant to create, delete, or update files using unified diffs. - `type: :apply_patch` The type of the tool. Always `apply_patch`. - `:apply_patch` - `allowed_callers: Array[:direct | :programmatic]` The tool invocation context(s). - `:direct` - `:programmatic` - `type: :tool_search_output` The type of the item. Always `tool_search_output`. - `:tool_search_output` - `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. - `class AdditionalTools` - `id: String` The unique ID of the additional tools item. - `role: :unknown | :user | :assistant | 5 more` The role that provided the additional tools. - `:unknown` - `:user` - `:assistant` - `:system` - `:critic` - `:discriminator` - `:developer` - `:tool` - `tools: Array[BetaTool]` The additional tool definitions made available at this item. - `class BetaFunctionTool` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `class BetaFileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - `class BetaComputerTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `class BetaComputerUsePreviewTool` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - `class BetaWebSearchTool` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `class Mcp` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `class CodeInterpreter` A tool that runs Python code to help generate a response to a prompt. - `class ProgrammaticToolCalling` - `class ImageGeneration` A tool that generates images using the GPT image models. - `class LocalShell` A tool that allows the model to execute shell commands in a local environment. - `class BetaFunctionShellTool` A tool that allows the model to execute shell commands. - `class BetaCustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `class BetaNamespaceTool` Groups function/custom tools under a shared namespace. - `class BetaToolSearchTool` Hosted or BYOT tool search configuration for deferred tools. - `class BetaWebSearchPreviewTool` This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `class BetaApplyPatchTool` Allows the assistant to create, delete, or update files using unified diffs. - `type: :additional_tools` The type of the item. Always `additional_tools`. - `:additional_tools` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class BetaResponseCompactionItem` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: String` The unique ID of the compaction item. - `encrypted_content: String` The encrypted content that was produced by compaction. - `type: :compaction` The type of the item. Always `compaction`. - `:compaction` - `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. - `class ImageGenerationCall` An image generation request made by the model. - `id: String` The unique ID of the image generation call. - `result: String` The generated image encoded in base64. - `status: :in_progress | :completed | :generating | :failed` The status of the image generation call. - `:in_progress` - `:completed` - `:generating` - `:failed` - `type: :image_generation_call` The type of the image generation call. Always `image_generation_call`. - `:image_generation_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class BetaResponseCodeInterpreterToolCall` A tool call to run code. - `id: String` The unique ID of the code interpreter tool call. - `code: String` The code to run, or null if not available. - `container_id: String` The ID of the container used to run the code. - `outputs: Array[Logs{ logs, type} | Image{ type, url}]` The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - `class Logs` The logs output from the code interpreter. - `logs: String` The logs output from the code interpreter. - `type: :logs` The type of the output. Always `logs`. - `:logs` - `class Image` The image output from the code interpreter. - `type: :image` The type of the output. Always `image`. - `:image` - `url: String` The URL of the image output from the code interpreter. - `status: :in_progress | :completed | :incomplete | 2 more` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `:in_progress` - `:completed` - `:incomplete` - `:interpreting` - `:failed` - `type: :code_interpreter_call` The type of the code interpreter tool call. Always `code_interpreter_call`. - `:code_interpreter_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class LocalShellCall` A tool call to run a command on the local shell. - `id: String` The unique ID of the local shell call. - `action: Action{ command, env, type, 3 more}` Execute a shell command on the server. - `command: Array[String]` The command to run. - `env: Hash[Symbol, String]` Environment variables to set for the command. - `type: :exec` The type of the local shell action. Always `exec`. - `:exec` - `timeout_ms: Integer` Optional timeout in milliseconds for the command. - `user: String` Optional user to run the command as. - `working_directory: String` Optional working directory to run the command in. - `call_id: String` The unique ID of the local shell tool call generated by the model. - `status: :in_progress | :completed | :incomplete` The status of the local shell call. - `:in_progress` - `:completed` - `:incomplete` - `type: :local_shell_call` The type of the local shell call. Always `local_shell_call`. - `:local_shell_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class LocalShellCallOutput` The output of a local shell tool call. - `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. - `type: :local_shell_call_output` The type of the local shell tool call output. Always `local_shell_call_output`. - `:local_shell_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. - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` - `:completed` - `:incomplete` - `class BetaResponseFunctionShellToolCall` A tool call that executes one or more shell commands in a managed environment. - `id: String` The unique ID of the shell tool call. Populated when this item is returned via API. - `action: Action{ commands, max_output_length, timeout_ms}` The shell commands and limits that describe how to run the tool call. - `commands: Array[String]` - `max_output_length: Integer` Optional maximum number of characters to return from each command. - `timeout_ms: Integer` Optional timeout in milliseconds for the commands. - `call_id: String` The unique ID of the shell tool call generated by the model. - `environment: BetaResponseLocalEnvironment | BetaResponseContainerReference` Represents the use of a local environment to perform shell actions. - `class BetaResponseLocalEnvironment` Represents the use of a local environment to perform shell actions. - `type: :local` The environment type. Always `local`. - `:local` - `class BetaResponseContainerReference` Represents a container created with /v1/containers. - `container_id: String` - `type: :container_reference` The environment type. Always `container_reference`. - `:container_reference` - `status: :in_progress | :completed | :incomplete` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` - `:completed` - `:incomplete` - `type: :shell_call` The type of the item. Always `shell_call`. - `:shell_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `created_by: String` The ID of the entity that created this tool call. - `class BetaResponseFunctionShellToolCallOutput` The output of a shell tool call that was emitted. - `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. - `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. - `output: Array[Output{ outcome, stderr, stdout, created_by}]` An array of shell call output contents - `outcome: Timeout{ type} | Exit{ exit_code, type}` Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `class Timeout` Indicates that the shell call exceeded its configured time limit. - `type: :timeout` The outcome type. Always `timeout`. - `:timeout` - `class Exit` Indicates that the shell commands finished and returned an exit code. - `exit_code: Integer` Exit code from the shell process. - `type: :exit` The outcome type. Always `exit`. - `:exit` - `stderr: String` The standard error output that was captured. - `stdout: String` The standard output that was captured. - `created_by: String` The identifier of the actor that created the item. - `status: :in_progress | :completed | :incomplete` The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `:in_progress` - `:completed` - `:incomplete` - `type: :shell_call_output` The type of the shell call output. Always `shell_call_output`. - `:shell_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. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `created_by: String` The identifier of the actor that created the item. - `class BetaResponseApplyPatchToolCall` A tool call that applies file diffs by creating, deleting, or updating files. - `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. - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}` One of the create_file, delete_file, or update_file operations applied via apply_patch. - `class CreateFile` Instruction describing how to create a file via the apply_patch tool. - `diff: String` Diff to apply. - `path: String` Path of the file to create. - `type: :create_file` Create a new file with the provided diff. - `:create_file` - `class DeleteFile` Instruction describing how to delete a file via the apply_patch tool. - `path: String` Path of the file to delete. - `type: :delete_file` Delete the specified file. - `:delete_file` - `class UpdateFile` Instruction describing how to update a file via the apply_patch tool. - `diff: String` Diff to apply. - `path: String` Path of the file to update. - `type: :update_file` Update an existing file with the provided diff. - `:update_file` - `status: :in_progress | :completed` The status of the apply patch tool call. One of `in_progress` or `completed`. - `:in_progress` - `:completed` - `type: :apply_patch_call` The type of the item. Always `apply_patch_call`. - `:apply_patch_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `created_by: String` The ID of the entity that created this tool call. - `class BetaResponseApplyPatchToolCallOutput` The output emitted by an apply patch tool call. - `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. - `status: :completed | :failed` The status of the apply patch tool call output. One of `completed` or `failed`. - `:completed` - `:failed` - `type: :apply_patch_call_output` The type of the item. Always `apply_patch_call_output`. - `:apply_patch_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. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `created_by: String` The ID of the entity that created this tool call output. - `output: String` Optional textual output returned by the apply patch tool. - `class McpCall` An invocation of a tool on an MCP server. - `id: String` The unique ID of the tool call. - `arguments: String` A JSON string of the arguments passed to the tool. - `name: String` The name of the tool that was run. - `server_label: String` The label of the MCP server running the tool. - `type: :mcp_call` The type of the item. Always `mcp_call`. - `:mcp_call` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `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. - `error: String` The error from the tool call, if any. - `output: String` The output from the tool call. - `status: :in_progress | :completed | :incomplete | 2 more` The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `:in_progress` - `:completed` - `:incomplete` - `:calling` - `:failed` - `class McpListTools` A list of tools available on an MCP server. - `id: String` The unique ID of the list. - `server_label: String` The label of the MCP server. - `tools: Array[Tool{ input_schema, name, annotations, description}]` The tools available on the server. - `input_schema: untyped` The JSON schema describing the tool's input. - `name: String` The name of the tool. - `annotations: untyped` Additional annotations about the tool. - `description: String` The description of the tool. - `type: :mcp_list_tools` The type of the item. Always `mcp_list_tools`. - `:mcp_list_tools` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `error: String` Error message if the server could not list tools. - `class McpApprovalRequest` A request for human approval of a tool invocation. - `id: String` The unique ID of the approval request. - `arguments: String` A JSON string of arguments for the tool. - `name: String` The name of the tool to run. - `server_label: String` The label of the MCP server making the request. - `type: :mcp_approval_request` The type of the item. Always `mcp_approval_request`. - `:mcp_approval_request` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `class McpApprovalResponse` A response to an MCP approval request. - `id: String` The unique ID of the approval response - `approval_request_id: String` The ID of the approval request being answered. - `approve: bool` Whether the request was approved. - `type: :mcp_approval_response` The type of the item. Always `mcp_approval_response`. - `:mcp_approval_response` - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `reason: String` Optional reason for the decision. - `class BetaResponseCustomToolCall` A call to a custom tool created by the model. - `call_id: String` An identifier used to map this custom tool call to a tool call output. - `input: String` The input for the custom tool call generated by the model. - `name: String` The name of the custom tool being called. - `type: :custom_tool_call` 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. - `agent: Agent{ agent_name}` The agent that produced this item. - `agent_name: String` The canonical name of the agent that produced this item. - `caller_: Direct{ type} | Program{ caller_id, type}` The execution context that produced this tool call. - `class Direct` - `type: :direct` - `:direct` - `class Program` - `caller_id: String` The call ID of the program item that produced this tool call. - `type: :program` - `:program` - `namespace: String` The namespace of the custom tool being called. - `class BetaResponseCustomToolCallOutputItem` The output of a custom tool call from your code, being sent back to the model. - `id: String` The unique ID of the custom tool call output item. - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `:in_progress` - `:completed` - `:incomplete` - `created_by: String` The identifier of the actor that created the item. - `usage: BetaResponseUsage` Token accounting for the compaction pass, including cached, reasoning, and total tokens. - `input_tokens: Integer` The number of input tokens. - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. - `cache_write_tokens: Integer` The number of input tokens that were written to the cache. - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - `output_tokens: Integer` The number of output tokens. - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}` A detailed breakdown of the output tokens. - `reasoning_tokens: Integer` The number of reasoning tokens. - `total_tokens: Integer` The total number of tokens used. ### Example ```ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") beta_compacted_response = openai.beta.responses.compact(model: :"gpt-5.6-sol") puts(beta_compacted_response) ``` #### Response ```json { "id": "id", "created_at": 0, "object": "response.compaction", "output": [ { "id": "id", "content": [ { "annotations": [ { "file_id": "file_id", "filename": "filename", "index": 0, "type": "file_citation" } ], "text": "text", "type": "output_text", "logprobs": [ { "token": "token", "bytes": [ 0 ], "logprob": 0, "top_logprobs": [ { "token": "token", "bytes": [ 0 ], "logprob": 0 } ] } ] } ], "role": "assistant", "status": "in_progress", "type": "message", "agent": { "agent_name": "agent_name" }, "phase": "commentary" } ], "usage": { "input_tokens": 0, "input_tokens_details": { "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ```