--- title: "Compact a response" method: POST path: "/responses/compact?beta=true" --- # Compact a response `POST /responses/compact?beta=true` Compact a conversation. Returns a compacted response object. Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced). ## Headers - `openai-beta` string[] ## Request body - BetaCompactResponseMethodPublicBody - `model` union, required — 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. - union - union - string - '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 - `input` union - string — A text input to the model, equivalent to a text input with the `user` role. - BetaInputItem[] — A list of one or many input items to the model, containing different content types. - union - 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. - `role` 'user' | 'assistant' | 'system' | 'developer', required — The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `content` union, required — Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - string — A text input to the model. - BetaInputContent[] — A list of one or many input items to the model, containing different content types. - … - `phase` 'commentary' | 'final_answer' — 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. - `type` 'message' — The type of the message input. Always `message`. - union — Content item used to generate a response. - object — 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. - `agent` BetaAgentTag - … - `type` 'message' — The type of the message input. Always set to `message`. - `role` 'user' | 'system' | 'developer', required — The role of the message input. One of `user`, `system`, or `developer`. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `content` BetaInputContent[], required — A list of one or many input items to the model, containing different content types. - … - object — An output message from the model. - `agent` BetaAgentTag - … - `id` string, required — The unique ID of the output message. - `type` 'message', required — The type of the output message. Always `message`. - `role` 'assistant', required — The role of the output message. Always `assistant`. - `content` BetaOutputMessageContent[], required — The content of the output message. - … - `phase` 'commentary' | 'final_answer' — 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. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - object — 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. - `agent` BetaAgentTag - … - `id` string, required — The unique ID of the file search tool call. - `type` 'file_search_call', required — The type of the file search tool call. Always `file_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required — The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `queries` string[], required — The queries used to search for files. - `results` object[], nullable — The results of the file search tool call. - … - object — 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. - `agent` BetaAgentTag - … - `type` 'computer_call', required — The type of the computer call. Always `computer_call`. - `id` string, required — The unique ID of the computer call. - `call_id` string, required — An identifier used when responding to the tool call with output. - `action` union - … - `actions` BetaComputerAction[] — Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - … - `pending_safety_checks` BetaComputerCallSafetyCheckParam[], required — The pending safety checks for the computer call. - … - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object — The output of a computer tool call. - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The ID of the computer tool call output. - `call_id` string, required — The ID of the computer tool call that produced the output. - `type` 'computer_call_output', required — The type of the computer tool call output. Always `computer_call_output`. - `output` BetaComputerScreenshotImage, required — A computer screenshot image used with the computer use tool. - … - `acknowledged_safety_checks` BetaComputerCallSafetyCheckParam[], nullable — The safety checks reported by the API that have been acknowledged by the developer. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object — 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. - `agent` BetaAgentTag - … - `id` string, required — The unique ID of the web search tool call. - `type` 'web_search_call', required — The type of the web search tool call. Always `web_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required — The status of the web search tool call. - `action` union, required — 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). - … - object — A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `agent` BetaAgentTag - … - `id` string — The unique ID of the function tool call. - `type` 'function_call', required — The type of the function tool call. Always `function_call`. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `namespace` string — The namespace of the function to run. - `name` string, required — The name of the function to run. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object — The output of a function tool call. - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of the function tool call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `type` 'function_call_output', required — The type of the function tool call output. Always `function_call_output`. - `output` union, required — Text, image, or file output of the function tool call. - … - `caller` union — The execution context that produced this tool call. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object — A message routed between agents. - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of this agent message item. - `type` 'agent_message', required — The item type. Always `agent_message`. - `author` string, required — The sending agent identity. - `recipient` string, required — The destination agent identity. - `content` union[], required — Plaintext, image, or encrypted content sent between agents. - … - object - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of this multi-agent call. - `call_id` string, required — The unique ID linking this call to its output. - `type` 'multi_agent_call', required — The item type. Always `multi_agent_call`. - `action` 'spawn_agent' | 'interrupt_agent' | 'list_agents' | 'send_message' | 'followup_task' | 'wait_agent', required - `arguments` string, required — The action arguments as a JSON string. - object - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of this multi-agent call output. - `call_id` string, required — The unique ID of the multi-agent call. - `type` 'multi_agent_call_output', required — The item type. Always `multi_agent_call_output`. - `action` 'spawn_agent' | 'interrupt_agent' | 'list_agents' | 'send_message' | 'followup_task' | 'wait_agent', required - `output` BetaOutputTextContentParam[], required — Text output returned by the multi-agent action. - … - object - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of this tool search call. - `call_id` string, nullable — The unique ID of the tool search call generated by the model. - `type` 'tool_search_call', required — The item type. Always `tool_search_call`. - `execution` 'server' | 'client' - `arguments` BetaEmptyModelParam, required - `status` 'in_progress' | 'completed' | 'incomplete' - object - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of this tool search output. - `call_id` string, nullable — The unique ID of the tool search call generated by the model. - `type` 'tool_search_output', required — The item type. Always `tool_search_output`. - `execution` 'server' | 'client' - `tools` BetaTool[], required — The loaded tool definitions returned by the tool search output. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of this additional tools item. - `type` 'additional_tools', required — The item type. Always `additional_tools`. - `role` 'developer', required — The role that provided the additional tools. Only `developer` is supported. - `tools` BetaTool[], required — A list of additional tools made available at this item. - … - object — 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). - `agent` BetaAgentTag - … - `type` 'reasoning', required — The type of the object. Always `reasoning`. - `id` string, required — The unique identifier of the reasoning content. - `encrypted_content` string, nullable — The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests. - `summary` BetaSummaryTextContent[], required — Reasoning summary content. - … - `content` BetaReasoningTextContent[] — Reasoning text content. - … - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object — A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The ID of the compaction item. - `type` 'compaction', required — The type of the item. Always `compaction`. - `encrypted_content` string, required — The encrypted content of the compaction summary. - object — An image generation request made by the model. - `agent` BetaAgentTag - … - `type` 'image_generation_call', required — The type of the image generation call. Always `image_generation_call`. - `id` string, required — The unique ID of the image generation call. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required — The status of the image generation call. - `result` string, nullable, required — The generated image encoded in base64. - object — A tool call to run code. - `agent` BetaAgentTag - … - `type` 'code_interpreter_call', required — The type of the code interpreter tool call. Always `code_interpreter_call`. - `id` string, required — The unique ID of the code interpreter tool call. - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required — The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `container_id` string, required — The ID of the container used to run the code. - `code` string, nullable, required — The code to run, or null if not available. - `outputs` union[], nullable, required — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - … - object — A tool call to run a command on the local shell. - `agent` BetaAgentTag - … - `type` 'local_shell_call', required — The type of the local shell call. Always `local_shell_call`. - `id` string, required — The unique ID of the local shell call. - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `action` BetaLocalShellExecAction, required — Execute a shell command on the server. - … - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the local shell call. - object — The output of a local shell tool call. - `agent` BetaAgentTag - … - `type` 'local_shell_call_output', required — The type of the local shell tool call output. Always `local_shell_call_output`. - `id` string, required — The unique ID of the local shell tool call generated by the model. - `output` string, required — A JSON string of the output of the local shell tool call. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the item. One of `in_progress`, `completed`, or `incomplete`. - object — A tool representing a request to execute one or more shell commands. - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of the shell tool call. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `type` 'shell_call', required — The type of the item. Always `shell_call`. - `action` BetaFunctionShellActionParam, required — Commands and limits describing how to run the shell tool call. - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status values reported for shell tool calls. - `environment` union - … - object — The streamed output items emitted by a shell tool call. - `agent` BetaAgentTagParam — The agent that produced this item. - … - `id` string, nullable — The unique ID of the shell tool call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `type` 'shell_call_output', required — The type of the item. Always `shell_call_output`. - `output` BetaFunctionShellCallOutputContentParam[], required — Captured chunks of stdout and stderr output, along with their associated outcomes. - … - `status` 'in_progress' | 'completed' | 'incomplete' — Status values reported for shell tool calls. - `max_output_length` integer, nullable — The maximum number of UTF-8 characters captured for this shell call's combined output. - object — A tool call representing a request to create, delete, or update files using diff patches. - `agent` BetaAgentTagParam — The agent that produced this item. - … - `type` 'apply_patch_call', required — The type of the item. Always `apply_patch_call`. - `id` string, nullable — The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `status` 'in_progress' | 'completed', required — Status values reported for apply_patch tool calls. - `operation` union, required — One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - … - object — The streamed output emitted by an apply patch tool call. - `agent` BetaAgentTagParam — The agent that produced this item. - … - `type` 'apply_patch_call_output', required — The type of the item. Always `apply_patch_call_output`. - `id` string, nullable — The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `caller` union — The execution context that produced this tool call. - … - `status` 'completed' | 'failed', required — Outcome values reported for apply_patch tool call outputs. - `output` string, nullable — Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - object — A list of tools available on an MCP server. - `agent` BetaAgentTag - … - `type` 'mcp_list_tools', required — The type of the item. Always `mcp_list_tools`. - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` BetaMCPListToolsTool[], required — The tools available on the server. - … - `error` string, nullable — Error message if the server could not list tools. - object — A request for human approval of a tool invocation. - `agent` BetaAgentTag - … - `type` 'mcp_approval_request', required — The type of the item. Always `mcp_approval_request`. - `id` string, required — The unique ID of the approval request. - `server_label` string, required — The label of the MCP server making the request. - `name` string, required — The name of the tool to run. - `arguments` string, required — A JSON string of arguments for the tool. - object — A response to an MCP approval request. - `agent` BetaAgentTag - … - `type` 'mcp_approval_response', required — The type of the item. Always `mcp_approval_response`. - `id` string, nullable — The unique ID of the approval response - `approval_request_id` string, required — The ID of the approval request being answered. - `approve` boolean, required — Whether the request was approved. - `reason` string, nullable — Optional reason for the decision. - object — An invocation of a tool on an MCP server. - `agent` BetaAgentTag - … - `type` 'mcp_call', required — The type of the item. Always `mcp_call`. - `id` string, required — The unique ID of the tool call. - `server_label` string, required — The label of the MCP server running the tool. - `name` string, required — The name of the tool that was run. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `output` string, nullable — The output from the tool call. - `error` string, nullable — The error from the tool call, if any. - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `approval_request_id` string, nullable — 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. - object — The output of a custom tool call from your code, being sent back to the model. - `agent` BetaAgentTag - … - `type` 'custom_tool_call_output', required — The type of the custom tool call output. Always `custom_tool_call_output`. - `id` string — The unique ID of the custom tool call output in the OpenAI platform. - `call_id` string, required — The call ID, used to map this custom tool call output to a custom tool call. - `caller` union — The execution context that produced this tool call. - … - `output` union, required — The output from the custom tool call generated by your code. Can be a string or an list of output content. - … - object — A call to a custom tool created by the model. - `agent` BetaAgentTag - … - `type` 'custom_tool_call', required — The type of the custom tool call. Always `custom_tool_call`. - `id` string — The unique ID of the custom tool call in the OpenAI platform. - `call_id` string, required — An identifier used to map this custom tool call to a tool call output. - `caller` union — The execution context that produced this tool call. - … - `namespace` string — The namespace of the custom tool being called. - `name` string, required — The name of the custom tool being called. - `input` string, required — The input for the custom tool call generated by the model. - BetaCompactionTriggerItemParam — Compacts the current context. Must be the final input item. - `agent` BetaAgentTagParam — The agent that produced this item. - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'compaction_trigger', required — The type of the item. Always `compaction_trigger`. - BetaItemReferenceParam — An internal identifier for an item to reference. - `agent` BetaAgentTagParam — The agent that produced this item. - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'item_reference', nullable — The type of item to reference. Always `item_reference`. - `id` string, required — The ID of the item to reference. - BetaProgramItemParam - `agent` BetaAgentTagParam — The agent that produced this item. - `agent_name` string, required — The canonical name of the agent that produced this item. - `id` string, required — The unique ID of this program item. - `type` 'program', required — The item type. Always `program`. - `call_id` string, required — The stable call ID of the program item. - `code` string, required — The JavaScript source executed by programmatic tool calling. - `fingerprint` string, required — Opaque program replay fingerprint that must be round-tripped. - BetaProgramOutputItemParam - `agent` BetaAgentTagParam — The agent that produced this item. - `agent_name` string, required — The canonical name of the agent that produced this item. - `id` string, required — The unique ID of this program output item. - `type` 'program_output', required — The item type. Always `program_output`. - `call_id` string, required — The call ID of the program item. - `result` string, required — The result produced by the program item. - `status` 'completed' | 'incomplete', required - `previous_response_id` string, nullable — 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`. - `instructions` string, nullable — 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. - `prompt_cache_key` string, nullable — A key to use when reading from or writing to the prompt cache. - `prompt_cache_retention` 'in_memory' | '24h' - `prompt_cache_options` BetaPromptCacheOptionsParam — 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. - `ttl` '30m' - `mode` 'implicit' | 'explicit' - `service_tier` 'auto' | 'default' | 'fast' | 'flex' | 'priority' ## Response `200` Success - BetaCompactResource - `id` string, required — The unique identifier for the compacted response. - `object` 'response.compaction', required — The object type. Always `response.compaction`. - `output` BetaOutputItem[], required — The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - union - BetaOutputMessage — An output message from the model. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `id` string, required — The unique ID of the output message. - `type` 'message', required — The type of the output message. Always `message`. - `role` 'assistant', required — The role of the output message. Always `assistant`. - `content` BetaOutputMessageContent[], required — The content of the output message. - union - BetaOutputTextContent — A text output from the model. - … - BetaRefusalContent — A refusal from the model. - … - `phase` 'commentary' | 'final_answer' — 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. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - BetaFileSearchToolCall — 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. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `id` string, required — The unique ID of the file search tool call. - `type` 'file_search_call', required — The type of the file search tool call. Always `file_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required — The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `queries` string[], required — The queries used to search for files. - `results` object[], nullable — The results of the file search tool call. - `file_id` string — The unique ID of the file. - `text` string — The text that was retrieved from the file. - `filename` string — The name of the file. - `attributes` BetaVectorStoreFileAttributes, nullable — 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. - `score` number, float — The relevance score of the file - a value between 0 and 1. - BetaFunctionToolCall — A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `id` string — The unique ID of the function tool call. - `type` 'function_call', required — The type of the function tool call. Always `function_call`. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCaller - `type` 'direct', required - BetaProgramToolCallCaller - `type` 'program', required - `caller_id` string, required — The call ID of the program item that produced this tool call. - `namespace` string — The namespace of the function to run. - `name` string, required — The name of the function to run. - `arguments` string, required — A JSON string of the arguments to pass to the function. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - BetaFunctionToolCallOutputResource — The output of a function tool call. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `id` string, required — The unique ID of the function call tool output. - `type` 'function_call_output', required — The type of the function tool call output. Always `function_call_output`. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCallerParam - `type` 'direct', required — The caller type. Always `direct`. - BetaProgramToolCallCallerParam - `type` 'program', required — The caller type. Always `program`. - `caller_id` string, required — The call ID of the program item that produced this tool call. - `output` union, required — The output from the function call generated by your code. Can be a string or an list of output content. - string — A string of the output of the function call. - BetaFunctionAndCustomToolCallOutput[] — Text, image, or file output of the function call. - union - … - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `created_by` string — The identifier of the actor that created the item. - BetaAgentMessage - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'agent_message', required — The type of the item. Always `agent_message`. - `id` string, required — The unique ID of the agent message. - `author` string, required — The sending agent identity. - `recipient` string, required — The destination agent identity. - `content` union[], required — Encrypted content sent between agents. - union — A content part that makes up an input or output item. - BetaInputTextContent — A text input to the model. - … - BetaOutputTextContent — A text output from the model. - … - BetaTextContent — A text content. - … - BetaSummaryTextContent — A summary text from the model. - … - BetaReasoningTextContent — Reasoning text from the model. - … - BetaRefusalContent — A refusal from the model. - … - BetaInputImageContent — An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - … - BetaComputerScreenshotContent — A screenshot of a computer. - … - BetaInputFileContent — A file input to the model. - … - BetaEncryptedContent — Opaque encrypted content that Responses API decrypts inside trusted model execution. - … - BetaMultiAgentCall - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'multi_agent_call', required — The type of the multi-agent call. Always `multi_agent_call`. - `id` string, required — The unique ID of the multi-agent call item. - `call_id` string, required — The unique ID linking this call to its output. - `action` 'spawn_agent' | 'interrupt_agent' | 'list_agents' | 'send_message' | 'followup_task' | 'wait_agent', required - `arguments` string, required — The JSON string of arguments generated for the action. - BetaMultiAgentCallOutput - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'multi_agent_call_output', required — The type of the multi-agent result. Always `multi_agent_call_output`. - `id` string, required — The unique ID of the multi-agent call output item. - `call_id` string, required — The unique ID of the multi-agent call. - `action` 'spawn_agent' | 'interrupt_agent' | 'list_agents' | 'send_message' | 'followup_task' | 'wait_agent', required - `output` BetaOutputTextContent[], required — Text output returned by the multi-agent action. - `type` 'output_text', required — The type of the output text. Always `output_text`. - `text` string, required — The text output from the model. - `annotations` BetaAnnotation[], required — The annotations of the text output. - union — An annotation that applies to a span of output text. - … - `logprobs` BetaLogProb[] - `token` string, required - `logprob` number, required - `bytes` integer[], required - `top_logprobs` BetaTopLogProb[], required - … - BetaWebSearchToolCall — 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. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `id` string, required — The unique ID of the web search tool call. - `type` 'web_search_call', required — The type of the web search tool call. Always `web_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required — The status of the web search tool call. - `action` union, required — 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). - object — Action type "search" - Performs a web search query. - `type` 'search', required — The action type. - `query` string — The search query. - `queries` string[] — The search queries. - `sources` object[] — The sources used in the search. - … - object — Action type "open_page" - Opens a specific URL from search results. - `type` 'open_page', required — The action type. - `url` string, uri, nullable — The URL opened by the model. - object — Action type "find_in_page": Searches for a pattern within a loaded page. - `type` 'find_in_page', required — The action type. - `url` string, uri, required — The URL of the page searched for the pattern. - `pattern` string, required — The pattern or text to search for within the page. - BetaComputerToolCall — 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. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'computer_call', required — The type of the computer call. Always `computer_call`. - `id` string, required — The unique ID of the computer call. - `call_id` string, required — An identifier used when responding to the tool call with output. - `action` union - BetaClickParam — A click action. - `type` 'click', required — Specifies the event type. For a click action, this property is always `click`. - `button` 'left' | 'right' | 'wheel' | 'back' | 'forward', required - `x` integer, required — The x-coordinate where the click occurred. - `y` integer, required — The y-coordinate where the click occurred. - `keys` string[], nullable — The keys being held while clicking. - BetaDoubleClickAction — A double click action. - `type` 'double_click', required — Specifies the event type. For a double click action, this property is always set to `double_click`. - `x` integer, required — The x-coordinate where the double click occurred. - `y` integer, required — The y-coordinate where the double click occurred. - `keys` string[], nullable, required — The keys being held while double-clicking. - BetaDragParam — A drag action. - `type` 'drag', required — Specifies the event type. For a drag action, this property is always set to `drag`. - `path` BetaCoordParam[], required — An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg ``` [ { x: 100, y: 200 }, { x: 200, y: 300 } ] ``` - … - `keys` string[], nullable — The keys being held while dragging the mouse. - BetaKeyPressAction — A collection of keypresses the model would like to perform. - `type` 'keypress', required — Specifies the event type. For a keypress action, this property is always set to `keypress`. - `keys` string[], required — The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - BetaMoveParam — A mouse move action. - `type` 'move', required — Specifies the event type. For a move action, this property is always set to `move`. - `x` integer, required — The x-coordinate to move to. - `y` integer, required — The y-coordinate to move to. - `keys` string[], nullable — The keys being held while moving the mouse. - BetaScreenshotParam — A screenshot action. - `type` 'screenshot', required — Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - BetaScrollParam — A scroll action. - `type` 'scroll', required — Specifies the event type. For a scroll action, this property is always set to `scroll`. - `x` integer, required — The x-coordinate where the scroll occurred. - `y` integer, required — The y-coordinate where the scroll occurred. - `scroll_x` integer, required — The horizontal scroll distance. - `scroll_y` integer, required — The vertical scroll distance. - `keys` string[], nullable — The keys being held while scrolling. - BetaTypeParam — An action to type in text. - `type` 'type', required — Specifies the event type. For a type action, this property is always set to `type`. - `text` string, required — The text to type. - BetaWaitParam — A wait action. - `type` 'wait', required — Specifies the event type. For a wait action, this property is always set to `wait`. - `actions` BetaComputerAction[] — Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - union - BetaClickParam — A click action. - … - BetaDoubleClickAction — A double click action. - … - BetaDragParam — A drag action. - … - BetaKeyPressAction — A collection of keypresses the model would like to perform. - … - BetaMoveParam — A mouse move action. - … - BetaScreenshotParam — A screenshot action. - … - BetaScrollParam — A scroll action. - … - BetaTypeParam — An action to type in text. - … - BetaWaitParam — A wait action. - … - `pending_safety_checks` BetaComputerCallSafetyCheckParam[], required — The pending safety checks for the computer call. - `id` string, required — The ID of the pending safety check. - `code` string, nullable — The type of the pending safety check. - `message` string, nullable — Details about the pending safety check. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - BetaComputerToolCallOutputResource — The output of a computer tool call. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'computer_call_output', required — The type of the computer tool call output. Always `computer_call_output`. - `id` string, required — The unique ID of the computer call tool output. - `call_id` string, required — The ID of the computer tool call that produced the output. - `acknowledged_safety_checks` BetaComputerCallSafetyCheckParam[] — The safety checks reported by the API that have been acknowledged by the developer. - `id` string, required — The ID of the pending safety check. - `code` string, nullable — The type of the pending safety check. - `message` string, nullable — Details about the pending safety check. - `output` BetaComputerScreenshotImage, required — A computer screenshot image used with the computer use tool. - `type` 'computer_screenshot', required — Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `image_url` string, uri — The URL of the screenshot image. - `file_id` string — The identifier of an uploaded file that contains the screenshot. - `status` 'completed' | 'incomplete', required — The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `created_by` string — The identifier of the actor that created the item. - BetaReasoningItem — 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). - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'reasoning', required — The type of the object. Always `reasoning`. - `id` string, required — The unique identifier of the reasoning content. - `encrypted_content` string, nullable — The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests. - `summary` BetaSummaryTextContent[], required — Reasoning summary content. - `type` 'summary_text', required — The type of the object. Always `summary_text`. - `text` string, required — A summary of the reasoning output from the model so far. - `content` BetaReasoningTextContent[] — Reasoning text content. - `type` 'reasoning_text', required — The type of the reasoning text. Always `reasoning_text`. - `text` string, required — The reasoning text from the model. - `status` 'in_progress' | 'completed' | 'incomplete' — The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - BetaProgram - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'program', required — The type of the item. Always `program`. - `id` string, required — The unique ID of the program item. - `call_id` string, required — The stable call ID of the program item. - `code` string, required — The JavaScript source executed by programmatic tool calling. - `fingerprint` string, required — Opaque program replay fingerprint that must be round-tripped. - BetaProgramOutput - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'program_output', required — The type of the item. Always `program_output`. - `id` string, required — The unique ID of the program output item. - `call_id` string, required — The call ID of the program item. - `result` string, required — The result produced by the program item. - `status` 'completed' | 'incomplete', required - BetaToolSearchCall - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'tool_search_call', required — The type of the item. Always `tool_search_call`. - `id` string, required — The unique ID of the tool search call item. - `call_id` string, nullable, required — The unique ID of the tool search call generated by the model. - `execution` 'server' | 'client', required - `arguments` unknown, required - `status` 'in_progress' | 'completed' | 'incomplete', required - `created_by` string — The identifier of the actor that created the item. - BetaToolSearchOutput - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'tool_search_output', required — The type of the item. Always `tool_search_output`. - `id` string, required — The unique ID of the tool search output item. - `call_id` string, nullable, required — The unique ID of the tool search call generated by the model. - `execution` 'server' | 'client', required - `tools` BetaTool[], required — The loaded tool definitions returned by tool search. - union — A tool that can be used to generate a response. - 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). - … - 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). - … - BetaComputerTool — A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - … - BetaComputerUsePreviewTool — A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - … - 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). - … - BetaMCPTool — 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). - … - BetaCodeInterpreterTool — A tool that runs Python code to help generate a response to a prompt. - … - BetaProgrammaticToolCallingParam - … - BetaImageGenTool — A tool that generates images using the GPT image models. - … - BetaLocalShellToolParam — A tool that allows the model to execute shell commands in a local environment. - … - BetaFunctionShellToolParam — A tool that allows the model to execute shell commands. - … - BetaCustomToolParam — 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) - … - BetaNamespaceToolParam — Groups function/custom tools under a shared namespace. - … - BetaToolSearchToolParam — Hosted or BYOT tool search configuration for deferred tools. - … - 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). - … - BetaApplyPatchToolParam — Allows the assistant to create, delete, or update files using unified diffs. - … - `status` 'in_progress' | 'completed' | 'incomplete', required - `created_by` string — The identifier of the actor that created the item. - BetaAdditionalTools - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'additional_tools', required — The type of the item. Always `additional_tools`. - `id` string, required — The unique ID of the additional tools item. - `role` 'unknown' | 'user' | 'assistant' | 'system' | 'critic' | 'discriminator' | 'developer' | 'tool', required - `tools` BetaTool[], required — The additional tool definitions made available at this item. - union — A tool that can be used to generate a response. - 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). - … - 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). - … - BetaComputerTool — A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - … - BetaComputerUsePreviewTool — A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - … - 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). - … - BetaMCPTool — 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). - … - BetaCodeInterpreterTool — A tool that runs Python code to help generate a response to a prompt. - … - BetaProgrammaticToolCallingParam - … - BetaImageGenTool — A tool that generates images using the GPT image models. - … - BetaLocalShellToolParam — A tool that allows the model to execute shell commands in a local environment. - … - BetaFunctionShellToolParam — A tool that allows the model to execute shell commands. - … - BetaCustomToolParam — 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) - … - BetaNamespaceToolParam — Groups function/custom tools under a shared namespace. - … - BetaToolSearchToolParam — Hosted or BYOT tool search configuration for deferred tools. - … - 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). - … - BetaApplyPatchToolParam — Allows the assistant to create, delete, or update files using unified diffs. - … - BetaCompactionBody — A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'compaction', required — The type of the item. Always `compaction`. - `id` string, required — The unique ID of the compaction item. - `encrypted_content` string, required — The encrypted content that was produced by compaction. - `created_by` string — The identifier of the actor that created the item. - BetaImageGenToolCall — An image generation request made by the model. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'image_generation_call', required — The type of the image generation call. Always `image_generation_call`. - `id` string, required — The unique ID of the image generation call. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required — The status of the image generation call. - `result` string, nullable, required — The generated image encoded in base64. - BetaCodeInterpreterToolCall — A tool call to run code. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'code_interpreter_call', required — The type of the code interpreter tool call. Always `code_interpreter_call`. - `id` string, required — The unique ID of the code interpreter tool call. - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required — The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `container_id` string, required — The ID of the container used to run the code. - `code` string, nullable, required — The code to run, or null if not available. - `outputs` union[], nullable, required — The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - union - BetaCodeInterpreterOutputLogs — The logs output from the code interpreter. - … - BetaCodeInterpreterOutputImage — The image output from the code interpreter. - … - BetaLocalShellToolCall — A tool call to run a command on the local shell. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'local_shell_call', required — The type of the local shell call. Always `local_shell_call`. - `id` string, required — The unique ID of the local shell call. - `call_id` string, required — The unique ID of the local shell tool call generated by the model. - `action` BetaLocalShellExecAction, required — Execute a shell command on the server. - `type` 'exec', required — The type of the local shell action. Always `exec`. - `command` string[], required — The command to run. - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the command. - `working_directory` string, nullable — Optional working directory to run the command in. - `env` object, required — Environment variables to set for the command. - `user` string, nullable — Optional user to run the command as. - `status` 'in_progress' | 'completed' | 'incomplete', required — The status of the local shell call. - BetaLocalShellToolCallOutput — The output of a local shell tool call. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'local_shell_call_output', required — The type of the local shell tool call output. Always `local_shell_call_output`. - `id` string, required — The unique ID of the local shell tool call generated by the model. - `output` string, required — A JSON string of the output of the local shell tool call. - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the item. One of `in_progress`, `completed`, or `incomplete`. - BetaFunctionShellCall — A tool call that executes one or more shell commands in a managed environment. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'shell_call', required — The type of the item. Always `shell_call`. - `id` string, required — The unique ID of the shell tool call. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCaller - `type` 'direct', required - BetaProgramToolCallCaller - `type` 'program', required - `caller_id` string, required — The call ID of the program item that produced this tool call. - `action` BetaFunctionShellAction, required — Execute a shell command. - `commands` string[], required - `timeout_ms` integer, nullable, required — Optional timeout in milliseconds for the commands. - `max_output_length` integer, nullable, required — Optional maximum number of characters to return from each command. - `status` 'in_progress' | 'completed' | 'incomplete', required - `environment` union, required - BetaLocalEnvironmentResource — Represents the use of a local environment to perform shell actions. - `type` 'local', required — The environment type. Always `local`. - BetaContainerReferenceResource — Represents a container created with /v1/containers. - `type` 'container_reference', required — The environment type. Always `container_reference`. - `container_id` string, required - `created_by` string — The ID of the entity that created this tool call. - BetaFunctionShellCallOutput — The output of a shell tool call that was emitted. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'shell_call_output', required — The type of the shell call output. Always `shell_call_output`. - `id` string, required — The unique ID of the shell call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCaller - `type` 'direct', required - BetaProgramToolCallCaller - `type` 'program', required - `caller_id` string, required — The call ID of the program item that produced this tool call. - `status` 'in_progress' | 'completed' | 'incomplete', required - `output` BetaFunctionShellCallOutputContent[], required — An array of shell call output contents - `stdout` string, required — The standard output that was captured. - `stderr` string, required — The standard error output that was captured. - `outcome` union, required — Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - BetaFunctionShellCallOutputTimeoutOutcome — Indicates that the shell call exceeded its configured time limit. - … - BetaFunctionShellCallOutputExitOutcome — Indicates that the shell commands finished and returned an exit code. - … - `created_by` string — The identifier of the actor that created the item. - `max_output_length` integer, nullable, required — The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - `created_by` string — The identifier of the actor that created the item. - BetaApplyPatchToolCall — A tool call that applies file diffs by creating, deleting, or updating files. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'apply_patch_call', required — The type of the item. Always `apply_patch_call`. - `id` string, required — The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCaller - `type` 'direct', required - BetaProgramToolCallCaller - `type` 'program', required - `caller_id` string, required — The call ID of the program item that produced this tool call. - `status` 'in_progress' | 'completed', required - `operation` union, required — One of the create_file, delete_file, or update_file operations applied via apply_patch. - BetaApplyPatchCreateFileOperation — Instruction describing how to create a file via the apply_patch tool. - `type` 'create_file', required — Create a new file with the provided diff. - `path` string, required — Path of the file to create. - `diff` string, required — Diff to apply. - BetaApplyPatchDeleteFileOperation — Instruction describing how to delete a file via the apply_patch tool. - `type` 'delete_file', required — Delete the specified file. - `path` string, required — Path of the file to delete. - BetaApplyPatchUpdateFileOperation — Instruction describing how to update a file via the apply_patch tool. - `type` 'update_file', required — Update an existing file with the provided diff. - `path` string, required — Path of the file to update. - `diff` string, required — Diff to apply. - `created_by` string — The ID of the entity that created this tool call. - BetaApplyPatchToolCallOutput — The output emitted by an apply patch tool call. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'apply_patch_call_output', required — The type of the item. Always `apply_patch_call_output`. - `id` string, required — The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id` string, required — The unique ID of the apply patch tool call generated by the model. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCaller - `type` 'direct', required - BetaProgramToolCallCaller - `type` 'program', required - `caller_id` string, required — The call ID of the program item that produced this tool call. - `status` 'completed' | 'failed', required - `output` string, nullable — Optional textual output returned by the apply patch tool. - `created_by` string — The ID of the entity that created this tool call output. - BetaMCPToolCall — An invocation of a tool on an MCP server. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'mcp_call', required — The type of the item. Always `mcp_call`. - `id` string, required — The unique ID of the tool call. - `server_label` string, required — The label of the MCP server running the tool. - `name` string, required — The name of the tool that was run. - `arguments` string, required — A JSON string of the arguments passed to the tool. - `output` string, nullable — The output from the tool call. - `error` string, nullable — The error from the tool call, if any. - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `approval_request_id` string, nullable — 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. - BetaMCPListTools — A list of tools available on an MCP server. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'mcp_list_tools', required — The type of the item. Always `mcp_list_tools`. - `id` string, required — The unique ID of the list. - `server_label` string, required — The label of the MCP server. - `tools` BetaMCPListToolsTool[], required — The tools available on the server. - `name` string, required — The name of the tool. - `description` string, nullable — The description of the tool. - `input_schema` object, required — The JSON schema describing the tool's input. - `annotations` object, nullable — Additional annotations about the tool. - `error` string, nullable — Error message if the server could not list tools. - BetaMCPApprovalRequest — A request for human approval of a tool invocation. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'mcp_approval_request', required — The type of the item. Always `mcp_approval_request`. - `id` string, required — The unique ID of the approval request. - `server_label` string, required — The label of the MCP server making the request. - `name` string, required — The name of the tool to run. - `arguments` string, required — A JSON string of arguments for the tool. - BetaMCPApprovalResponseResource — A response to an MCP approval request. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'mcp_approval_response', required — The type of the item. Always `mcp_approval_response`. - `id` string, required — The unique ID of the approval response - `approval_request_id` string, required — The ID of the approval request being answered. - `approve` boolean, required — Whether the request was approved. - `reason` string, nullable — Optional reason for the decision. - BetaCustomToolCall — A call to a custom tool created by the model. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'custom_tool_call', required — The type of the custom tool call. Always `custom_tool_call`. - `id` string — The unique ID of the custom tool call in the OpenAI platform. - `call_id` string, required — An identifier used to map this custom tool call to a tool call output. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCaller - `type` 'direct', required - BetaProgramToolCallCaller - `type` 'program', required - `caller_id` string, required — The call ID of the program item that produced this tool call. - `namespace` string — The namespace of the custom tool being called. - `name` string, required — The name of the custom tool being called. - `input` string, required — The input for the custom tool call generated by the model. - BetaCustomToolCallOutputResource — The output of a custom tool call from your code, being sent back to the model. - `agent` BetaAgentTag - `agent_name` string, required — The canonical name of the agent that produced this item. - `type` 'custom_tool_call_output', required — The type of the custom tool call output. Always `custom_tool_call_output`. - `id` string, required — The unique ID of the custom tool call output item. - `call_id` string, required — The call ID, used to map this custom tool call output to a custom tool call. - `caller` union — The execution context that produced this tool call. - BetaDirectToolCallCallerParam - `type` 'direct', required — The caller type. Always `direct`. - BetaProgramToolCallCallerParam - `type` 'program', required — The caller type. Always `program`. - `caller_id` string, required — The call ID of the program item that produced this tool call. - `output` union, required — The output from the custom tool call generated by your code. Can be a string or an list of output content. - string — A string of the output of the custom tool call. - BetaFunctionAndCustomToolCallOutput[] — Text, image, or file output of the custom tool call. - union - … - `status` 'in_progress' | 'completed' | 'incomplete', required - `created_by` string — The identifier of the actor that created the item. - `created_at` integer, required — Unix timestamp (in seconds) when the compacted conversation was created. - `usage` BetaResponseUsage, required — Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. - `input_tokens` integer, required — The number of input tokens. - `input_tokens_details` object, required — A detailed breakdown of the input tokens. - `cached_tokens` integer, required — The number of tokens that were retrieved from the cache. [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - `cache_write_tokens` integer, required — The number of input tokens that were written to the cache. - `output_tokens` integer, required — The number of output tokens. - `output_tokens_details` object, required — A detailed breakdown of the output tokens. - `reasoning_tokens` integer, required — The number of reasoning tokens. - `total_tokens` integer, required — The total number of tokens used. --- [API](https://skmtc.net/openai/apis/openai-api.md) · [All operations](https://skmtc.net/openai/apis/openai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openai/openai-api/versions/dcd35773a322/schema)