## Compact a response `BetaCompactedResponse beta().responses().compact(ResponseCompactParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **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). ### Parameters - `ResponseCompactParams params` - `Optional> betas` - `RESPONSES_MULTI_AGENT_V1("responses_multi_agent=v1")` - `Optional model` 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-sol")` - `GPT_5_6_TERRA("gpt-5.6-terra")` - `GPT_5_6_LUNA("gpt-5.6-luna")` - `GPT_5_4("gpt-5.4")` - `GPT_5_4_MINI("gpt-5.4-mini")` - `GPT_5_4_NANO("gpt-5.4-nano")` - `GPT_5_4_MINI_2026_03_17("gpt-5.4-mini-2026-03-17")` - `GPT_5_4_NANO_2026_03_17("gpt-5.4-nano-2026-03-17")` - `GPT_5_3_CHAT_LATEST("gpt-5.3-chat-latest")` - `GPT_5_2("gpt-5.2")` - `GPT_5_2_2025_12_11("gpt-5.2-2025-12-11")` - `GPT_5_2_CHAT_LATEST("gpt-5.2-chat-latest")` - `GPT_5_2_PRO("gpt-5.2-pro")` - `GPT_5_2_PRO_2025_12_11("gpt-5.2-pro-2025-12-11")` - `GPT_5_1("gpt-5.1")` - `GPT_5_1_2025_11_13("gpt-5.1-2025-11-13")` - `GPT_5_1_CODEX("gpt-5.1-codex")` - `GPT_5_1_MINI("gpt-5.1-mini")` - `GPT_5_1_CHAT_LATEST("gpt-5.1-chat-latest")` - `GPT_5("gpt-5")` - `GPT_5_MINI("gpt-5-mini")` - `GPT_5_NANO("gpt-5-nano")` - `GPT_5_2025_08_07("gpt-5-2025-08-07")` - `GPT_5_MINI_2025_08_07("gpt-5-mini-2025-08-07")` - `GPT_5_NANO_2025_08_07("gpt-5-nano-2025-08-07")` - `GPT_5_CHAT_LATEST("gpt-5-chat-latest")` - `GPT_4_1("gpt-4.1")` - `GPT_4_1_MINI("gpt-4.1-mini")` - `GPT_4_1_NANO("gpt-4.1-nano")` - `GPT_4_1_2025_04_14("gpt-4.1-2025-04-14")` - `GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14")` - `GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14")` - `O4_MINI("o4-mini")` - `O4_MINI_2025_04_16("o4-mini-2025-04-16")` - `O3("o3")` - `O3_2025_04_16("o3-2025-04-16")` - `O3_MINI("o3-mini")` - `O3_MINI_2025_01_31("o3-mini-2025-01-31")` - `O1("o1")` - `O1_2024_12_17("o1-2024-12-17")` - `O1_PREVIEW("o1-preview")` - `O1_PREVIEW_2024_09_12("o1-preview-2024-09-12")` - `O1_MINI("o1-mini")` - `O1_MINI_2024_09_12("o1-mini-2024-09-12")` - `GPT_4O("gpt-4o")` - `GPT_4O_2024_11_20("gpt-4o-2024-11-20")` - `GPT_4O_2024_08_06("gpt-4o-2024-08-06")` - `GPT_4O_2024_05_13("gpt-4o-2024-05-13")` - `GPT_4O_AUDIO_PREVIEW("gpt-4o-audio-preview")` - `GPT_4O_AUDIO_PREVIEW_2024_10_01("gpt-4o-audio-preview-2024-10-01")` - `GPT_4O_AUDIO_PREVIEW_2024_12_17("gpt-4o-audio-preview-2024-12-17")` - `GPT_4O_AUDIO_PREVIEW_2025_06_03("gpt-4o-audio-preview-2025-06-03")` - `GPT_4O_MINI_AUDIO_PREVIEW("gpt-4o-mini-audio-preview")` - `GPT_4O_MINI_AUDIO_PREVIEW_2024_12_17("gpt-4o-mini-audio-preview-2024-12-17")` - `GPT_4O_SEARCH_PREVIEW("gpt-4o-search-preview")` - `GPT_4O_MINI_SEARCH_PREVIEW("gpt-4o-mini-search-preview")` - `GPT_4O_SEARCH_PREVIEW_2025_03_11("gpt-4o-search-preview-2025-03-11")` - `GPT_4O_MINI_SEARCH_PREVIEW_2025_03_11("gpt-4o-mini-search-preview-2025-03-11")` - `CHATGPT_4O_LATEST("chatgpt-4o-latest")` - `CODEX_MINI_LATEST("codex-mini-latest")` - `GPT_4O_MINI("gpt-4o-mini")` - `GPT_4O_MINI_2024_07_18("gpt-4o-mini-2024-07-18")` - `GPT_4_TURBO("gpt-4-turbo")` - `GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09")` - `GPT_4_0125_PREVIEW("gpt-4-0125-preview")` - `GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview")` - `GPT_4_1106_PREVIEW("gpt-4-1106-preview")` - `GPT_4_VISION_PREVIEW("gpt-4-vision-preview")` - `GPT_4("gpt-4")` - `GPT_4_0314("gpt-4-0314")` - `GPT_4_0613("gpt-4-0613")` - `GPT_4_32K("gpt-4-32k")` - `GPT_4_32K_0314("gpt-4-32k-0314")` - `GPT_4_32K_0613("gpt-4-32k-0613")` - `GPT_3_5_TURBO("gpt-3.5-turbo")` - `GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k")` - `GPT_3_5_TURBO_0301("gpt-3.5-turbo-0301")` - `GPT_3_5_TURBO_0613("gpt-3.5-turbo-0613")` - `GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106")` - `GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125")` - `GPT_3_5_TURBO_16K_0613("gpt-3.5-turbo-16k-0613")` - `O1_PRO("o1-pro")` - `O1_PRO_2025_03_19("o1-pro-2025-03-19")` - `O3_PRO("o3-pro")` - `O3_PRO_2025_06_10("o3-pro-2025-06-10")` - `O3_DEEP_RESEARCH("o3-deep-research")` - `O3_DEEP_RESEARCH_2025_06_26("o3-deep-research-2025-06-26")` - `O4_MINI_DEEP_RESEARCH("o4-mini-deep-research")` - `O4_MINI_DEEP_RESEARCH_2025_06_26("o4-mini-deep-research-2025-06-26")` - `COMPUTER_USE_PREVIEW("computer-use-preview")` - `COMPUTER_USE_PREVIEW_2025_03_11("computer-use-preview-2025-03-11")` - `GPT_5_CODEX("gpt-5-codex")` - `GPT_5_PRO("gpt-5-pro")` - `GPT_5_PRO_2025_10_06("gpt-5-pro-2025-10-06")` - `GPT_5_1_CODEX_MAX("gpt-5.1-codex-max")` - `Optional input` Text, image, or file inputs to the model, used to generate a response - `String` - `List` - `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 content` Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - `String` - `List` - `class BetaResponseInputText:` A text input to the model. - `String text` The text input to the model. - `JsonValue; type "input_text"constant` The type of the input item. Always `input_text`. - `INPUT_TEXT("input_text")` - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `class BetaResponseInputImage:` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `Detail detail` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `LOW("low")` - `HIGH("high")` - `AUTO("auto")` - `ORIGINAL("original")` - `JsonValue; type "input_image"constant` The type of the input item. Always `input_image`. - `INPUT_IMAGE("input_image")` - `Optional fileId` The ID of the file to be sent to the model. - `Optional imageUrl` The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `class BetaResponseInputFile:` A file input to the model. - `JsonValue; type "input_file"constant` The type of the input item. Always `input_file`. - `INPUT_FILE("input_file")` - `Optional detail` 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("auto")` - `LOW("low")` - `HIGH("high")` - `Optional fileData` The content of the file to be sent to the model. - `Optional fileId` The ID of the file to be sent to the model. - `Optional fileUrl` The URL of the file to be sent to the model. - `Optional filename` The name of the file to be sent to the model. - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `Role role` The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `USER("user")` - `ASSISTANT("assistant")` - `SYSTEM("system")` - `DEVELOPER("developer")` - `Optional phase` 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("commentary")` - `FINAL_ANSWER("final_answer")` - `Optional type` The type of the message input. Always `message`. - `MESSAGE("message")` - `Message` - `List content` A list of one or many input items to the model, containing different content types. - `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. - `Role role` The role of the message input. One of `user`, `system`, or `developer`. - `USER("user")` - `SYSTEM("system")` - `DEVELOPER("developer")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional status` The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `Optional type` The type of the message input. Always set to `message`. - `MESSAGE("message")` - `class BetaResponseOutputMessage:` An output message from the model. - `String id` The unique ID of the output message. - `List content` The content of the output message. - `class BetaResponseOutputText:` A text output from the model. - `List annotations` The annotations of the text output. - `class FileCitation:` A citation to a file. - `String fileId` The ID of the file. - `String filename` The filename of the file cited. - `long index` The index of the file in the list of files. - `JsonValue; type "file_citation"constant` The type of the file citation. Always `file_citation`. - `FILE_CITATION("file_citation")` - `class UrlCitation:` A citation for a web resource used to generate a model response. - `long endIndex` The index of the last character of the URL citation in the message. - `long startIndex` The index of the first character of the URL citation in the message. - `String title` The title of the web resource. - `JsonValue; type "url_citation"constant` The type of the URL citation. Always `url_citation`. - `URL_CITATION("url_citation")` - `String url` The URL of the web resource. - `class ContainerFileCitation:` A citation for a container file used to generate a model response. - `String containerId` The ID of the container file. - `long endIndex` The index of the last character of the container file citation in the message. - `String fileId` The ID of the file. - `String filename` The filename of the container file cited. - `long startIndex` The index of the first character of the container file citation in the message. - `JsonValue; type "container_file_citation"constant` The type of the container file citation. Always `container_file_citation`. - `CONTAINER_FILE_CITATION("container_file_citation")` - `class FilePath:` A path to a file. - `String fileId` The ID of the file. - `long index` The index of the file in the list of files. - `JsonValue; type "file_path"constant` The type of the file path. Always `file_path`. - `FILE_PATH("file_path")` - `String text` The text output from the model. - `JsonValue; type "output_text"constant` The type of the output text. Always `output_text`. - `OUTPUT_TEXT("output_text")` - `Optional> logprobs` - `String token` - `List bytes` - `double logprob` - `List topLogprobs` - `String token` - `List bytes` - `double logprob` - `class BetaResponseOutputRefusal:` A refusal from the model. - `String refusal` The refusal explanation from the model. - `JsonValue; type "refusal"constant` The type of the refusal. Always `refusal`. - `REFUSAL("refusal")` - `JsonValue; role "assistant"constant` The role of the output message. Always `assistant`. - `ASSISTANT("assistant")` - `Status status` The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "message"constant` The type of the output message. Always `message`. - `MESSAGE("message")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional phase` 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("commentary")` - `FINAL_ANSWER("final_answer")` - `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. - `String id` The unique ID of the file search tool call. - `List queries` The queries used to search for files. - `Status status` The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `IN_PROGRESS("in_progress")` - `SEARCHING("searching")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `FAILED("failed")` - `JsonValue; type "file_search_call"constant` The type of the file search tool call. Always `file_search_call`. - `FILE_SEARCH_CALL("file_search_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional> results` The results of the file search tool call. - `Optional attributes` 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` - `double` - `boolean` - `Optional fileId` The unique ID of the file. - `Optional filename` The name of the file. - `Optional score` The relevance score of the file - a value between 0 and 1. - `Optional text` 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. - `String id` The unique ID of the computer call. - `String callId` An identifier used when responding to the tool call with output. - `List pendingSafetyChecks` The pending safety checks for the computer call. - `String id` The ID of the pending safety check. - `Optional code` The type of the pending safety check. - `Optional message` Details about the pending safety check. - `Status status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `Type type` The type of the computer call. Always `computer_call`. - `COMPUTER_CALL("computer_call")` - `Optional action` A click action. - `Click` - `Button button` Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - `LEFT("left")` - `RIGHT("right")` - `WHEEL("wheel")` - `BACK("back")` - `FORWARD("forward")` - `JsonValue; type "click"constant` Specifies the event type. For a click action, this property is always `click`. - `CLICK("click")` - `long x` The x-coordinate where the click occurred. - `long y` The y-coordinate where the click occurred. - `Optional> keys` The keys being held while clicking. - `DoubleClick` - `Optional> keys` The keys being held while double-clicking. - `JsonValue; type "double_click"constant` Specifies the event type. For a double click action, this property is always set to `double_click`. - `DOUBLE_CLICK("double_click")` - `long x` The x-coordinate where the double click occurred. - `long y` The y-coordinate where the double click occurred. - `Drag` - `List path` 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 } ] ``` - `long x` The x-coordinate. - `long y` The y-coordinate. - `JsonValue; type "drag"constant` Specifies the event type. For a drag action, this property is always set to `drag`. - `DRAG("drag")` - `Optional> keys` The keys being held while dragging the mouse. - `Keypress` - `List keys` The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `JsonValue; type "keypress"constant` Specifies the event type. For a keypress action, this property is always set to `keypress`. - `KEYPRESS("keypress")` - `Move` - `JsonValue; type "move"constant` Specifies the event type. For a move action, this property is always set to `move`. - `MOVE("move")` - `long x` The x-coordinate to move to. - `long y` The y-coordinate to move to. - `Optional> keys` The keys being held while moving the mouse. - `JsonValue;` - `JsonValue; type "screenshot"constant` Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - `SCREENSHOT("screenshot")` - `Scroll` - `long scrollX` The horizontal scroll distance. - `long scrollY` The vertical scroll distance. - `JsonValue; type "scroll"constant` Specifies the event type. For a scroll action, this property is always set to `scroll`. - `SCROLL("scroll")` - `long x` The x-coordinate where the scroll occurred. - `long y` The y-coordinate where the scroll occurred. - `Optional> keys` The keys being held while scrolling. - `Type` - `String text` The text to type. - `JsonValue; type "type"constant` Specifies the event type. For a type action, this property is always set to `type`. - `TYPE("type")` - `JsonValue;` - `JsonValue; type "wait"constant` Specifies the event type. For a wait action, this property is always set to `wait`. - `WAIT("wait")` - `Optional> actions` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - `Click` - `DoubleClick` - `Drag` - `Keypress` - `Move` - `JsonValue;` - `Scroll` - `Type` - `JsonValue;` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `ComputerCallOutput` - `String callId` The ID of the computer tool call that produced the output. - `BetaResponseComputerToolCallOutputScreenshot output` A computer screenshot image used with the computer use tool. - `JsonValue; type "computer_screenshot"constant` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `COMPUTER_SCREENSHOT("computer_screenshot")` - `Optional fileId` The identifier of an uploaded file that contains the screenshot. - `Optional imageUrl` The URL of the screenshot image. - `JsonValue; type "computer_call_output"constant` The type of the computer tool call output. Always `computer_call_output`. - `COMPUTER_CALL_OUTPUT("computer_call_output")` - `Optional id` The ID of the computer tool call output. - `Optional> acknowledgedSafetyChecks` The safety checks reported by the API that have been acknowledged by the developer. - `String id` The ID of the pending safety check. - `Optional code` The type of the pending safety check. - `Optional message` Details about the pending safety check. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional status` The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("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. - `String id` The unique ID of the web search tool call. - `Action action` An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page). - `class Search:` Action type "search" - Performs a web search query. - `JsonValue; type "search"constant` The action type. - `SEARCH("search")` - `Optional> queries` The search queries. - `Optional query` The search query. - `Optional> sources` The sources used in the search. - `JsonValue; type "url"constant` The type of source. Always `url`. - `URL("url")` - `String url` The URL of the source. - `class OpenPage:` Action type "open_page" - Opens a specific URL from search results. - `JsonValue; type "open_page"constant` The action type. - `OPEN_PAGE("open_page")` - `Optional url` The URL opened by the model. - `class FindInPage:` Action type "find_in_page": Searches for a pattern within a loaded page. - `String pattern` The pattern or text to search for within the page. - `JsonValue; type "find_in_page"constant` The action type. - `FIND_IN_PAGE("find_in_page")` - `String url` The URL of the page searched for the pattern. - `Status status` The status of the web search tool call. - `IN_PROGRESS("in_progress")` - `SEARCHING("searching")` - `COMPLETED("completed")` - `FAILED("failed")` - `JsonValue; type "web_search_call"constant` The type of the web search tool call. Always `web_search_call`. - `WEB_SEARCH_CALL("web_search_call")` - `Optional agent` The agent that produced this item. - `String agentName` 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. - `String arguments` A JSON string of the arguments to pass to the function. - `String callId` The unique ID of the function tool call generated by the model. - `String name` The name of the function to run. - `JsonValue; type "function_call"constant` The type of the function tool call. Always `function_call`. - `FUNCTION_CALL("function_call")` - `Optional id` The unique ID of the function tool call. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional namespace` The namespace of the function to run. - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `FunctionCallOutput` - `String callId` The unique ID of the function tool call generated by the model. - `Output output` Text, image, or file output of the function tool call. - `String` - `List` - `class BetaResponseInputTextContent:` A text input to the model. - `String text` The text input to the model. - `JsonValue; type "input_text"constant` The type of the input item. Always `input_text`. - `INPUT_TEXT("input_text")` - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `class BetaResponseInputImageContent:` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `JsonValue; type "input_image"constant` The type of the input item. Always `input_image`. - `INPUT_IMAGE("input_image")` - `Optional detail` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `LOW("low")` - `HIGH("high")` - `AUTO("auto")` - `ORIGINAL("original")` - `Optional fileId` The ID of the file to be sent to the model. - `Optional imageUrl` The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `class BetaResponseInputFileContent:` A file input to the model. - `JsonValue; type "input_file"constant` The type of the input item. Always `input_file`. - `INPUT_FILE("input_file")` - `Optional detail` 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("auto")` - `LOW("low")` - `HIGH("high")` - `Optional fileData` The base64-encoded data of the file to be sent to the model. - `Optional fileId` The ID of the file to be sent to the model. - `Optional fileUrl` The URL of the file to be sent to the model. - `Optional filename` The name of the file to be sent to the model. - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `JsonValue; type "function_call_output"constant` The type of the function tool call output. Always `function_call_output`. - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional id` The unique ID of the function tool call output. Populated when this item is returned via API. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` The caller type. Always `direct`. - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` The caller type. Always `program`. - `PROGRAM("program")` - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `AgentMessage` - `String author` The sending agent identity. - `List content` 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. - `String encryptedContent` Opaque encrypted content. - `JsonValue; type "encrypted_content"constant` The type of the input item. Always `encrypted_content`. - `ENCRYPTED_CONTENT("encrypted_content")` - `String recipient` The destination agent identity. - `JsonValue; type "agent_message"constant` The item type. Always `agent_message`. - `AGENT_MESSAGE("agent_message")` - `Optional id` The unique ID of this agent message item. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `MultiAgentCall` - `Action action` The multi-agent action that was executed. - `SPAWN_AGENT("spawn_agent")` - `INTERRUPT_AGENT("interrupt_agent")` - `LIST_AGENTS("list_agents")` - `SEND_MESSAGE("send_message")` - `FOLLOWUP_TASK("followup_task")` - `WAIT_AGENT("wait_agent")` - `String arguments` The action arguments as a JSON string. - `String callId` The unique ID linking this call to its output. - `JsonValue; type "multi_agent_call"constant` The item type. Always `multi_agent_call`. - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional id` The unique ID of this multi-agent call. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `MultiAgentCallOutput` - `Action action` The multi-agent action that produced this result. - `SPAWN_AGENT("spawn_agent")` - `INTERRUPT_AGENT("interrupt_agent")` - `LIST_AGENTS("list_agents")` - `SEND_MESSAGE("send_message")` - `FOLLOWUP_TASK("followup_task")` - `WAIT_AGENT("wait_agent")` - `String callId` The unique ID of the multi-agent call. - `List output` Text output returned by the multi-agent action. - `String text` The text content. - `JsonValue; type "output_text"constant` The content type. Always `output_text`. - `OUTPUT_TEXT("output_text")` - `Optional> annotations` Citations associated with the text content. - `class FileCitation:` - `String fileId` The ID of the file. - `String filename` The filename of the file cited. - `long index` The index of the file in the list of files. - `JsonValue; type "file_citation"constant` The citation type. Always `file_citation`. - `FILE_CITATION("file_citation")` - `class UrlCitation:` - `long endIndex` The index of the last character of the citation in the message. - `long startIndex` The index of the first character of the citation in the message. - `String title` The title of the cited resource. - `JsonValue; type "url_citation"constant` The citation type. Always `url_citation`. - `URL_CITATION("url_citation")` - `String url` The URL of the cited resource. - `class ContainerFileCitation:` - `String containerId` The ID of the container. - `long endIndex` The index of the last character of the citation in the message. - `String fileId` The ID of the container file. - `String filename` The filename of the container file cited. - `long startIndex` The index of the first character of the citation in the message. - `JsonValue; type "container_file_citation"constant` The citation type. Always `container_file_citation`. - `CONTAINER_FILE_CITATION("container_file_citation")` - `JsonValue; type "multi_agent_call_output"constant` The item type. Always `multi_agent_call_output`. - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - `Optional id` The unique ID of this multi-agent call output. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `ToolSearchCall` - `JsonValue arguments` The arguments supplied to the tool search call. - `JsonValue; type "tool_search_call"constant` The item type. Always `tool_search_call`. - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional id` The unique ID of this tool search call. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional callId` The unique ID of the tool search call generated by the model. - `Optional execution` Whether tool search was executed by the server or by the client. - `SERVER("server")` - `CLIENT("client")` - `Optional status` The status of the tool search call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `class BetaResponseToolSearchOutputItemParam:` - `List tools` 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). - `String name` The name of the function to call. - `Optional parameters` A JSON schema object describing the parameters of the function. - `Optional strict` Whether strict parameter validation is enforced for this function tool. - `JsonValue; type "function"constant` The type of the function tool. Always `function`. - `FUNCTION("function")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional deferLoading` Whether this function is deferred and loaded via tool search. - `Optional description` A description of the function. Used by the model to determine whether or not to call the function. - `Optional outputSchema` 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). - `JsonValue; type "file_search"constant` The type of the file search tool. Always `file_search`. - `FILE_SEARCH("file_search")` - `List vectorStoreIds` The IDs of the vector stores to search. - `Optional filters` A filter to apply. - `class ComparisonFilter:` A filter used to compare a specified attribute key to a given value using a defined comparison operation. - `String key` The key to compare against the value. - `Type type` 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("eq")` - `NE("ne")` - `GT("gt")` - `GTE("gte")` - `LT("lt")` - `LTE("lte")` - `IN("in")` - `NIN("nin")` - `Value value` The value to compare against the attribute key; supports string, number, or boolean types. - `String` - `double` - `boolean` - `List` - `String` - `double` - `class CompoundFilter:` Combine multiple filters using `and` or `or`. - `List filters` 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. - `String key` The key to compare against the value. - `Type type` 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("eq")` - `NE("ne")` - `GT("gt")` - `GTE("gte")` - `LT("lt")` - `LTE("lte")` - `IN("in")` - `NIN("nin")` - `Value value` The value to compare against the attribute key; supports string, number, or boolean types. - `String` - `double` - `boolean` - `List` - `String` - `double` - `JsonValue` - `Type type` Type of operation: `and` or `or`. - `AND("and")` - `OR("or")` - `Optional maxNumResults` The maximum number of results to return. This number should be between 1 and 50 inclusive. - `Optional rankingOptions` Ranking options for search. - `Optional hybridSearch` Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - `double embeddingWeight` The weight of the embedding in the reciprocal ranking fusion. - `double textWeight` The weight of the text in the reciprocal ranking fusion. - `Optional ranker` The ranker to use for the file search. - `AUTO("auto")` - `DEFAULT_2024_11_15("default-2024-11-15")` - `Optional scoreThreshold` 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). - `JsonValue; type "computer"constant` The type of the computer tool. Always `computer`. - `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). - `long displayHeight` The height of the computer display. - `long displayWidth` The width of the computer display. - `Environment environment` The type of computer environment to control. - `WINDOWS("windows")` - `MAC("mac")` - `LINUX("linux")` - `UBUNTU("ubuntu")` - `BROWSER("browser")` - `JsonValue; type "computer_use_preview"constant` The type of the computer use tool. Always `computer_use_preview`. - `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 type` The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - `WEB_SEARCH("web_search")` - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - `Optional filters` Filters for the search. - `Optional> allowedDomains` 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"]` - `Optional searchContextSize` 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("low")` - `MEDIUM("medium")` - `HIGH("high")` - `Optional userLocation` The approximate location of the user. - `Optional city` Free text input for the city of the user, e.g. `San Francisco`. - `Optional country` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `Optional region` Free text input for the region of the user, e.g. `California`. - `Optional timezone` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `Optional type` The type of location approximation. Always `approximate`. - `APPROXIMATE("approximate")` - `Mcp` - `String serverLabel` A label for this MCP server, used to identify it in tool calls. - `JsonValue; type "mcp"constant` The type of the MCP tool. Always `mcp`. - `MCP("mcp")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional allowedTools` List of allowed tool names or a filter object. - `List` - `class McpToolFilter:` A filter object to specify which tools are allowed. - `Optional readOnly` 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. - `Optional> toolNames` List of allowed tool names. - `Optional authorization` 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. - `Optional connectorId` 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_dropbox")` - `CONNECTOR_GMAIL("connector_gmail")` - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - `Optional deferLoading` Whether this MCP tool is deferred and discovered via tool search. - `Optional headers` Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `Optional requireApproval` 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. - `Optional always` A filter object to specify which tools are allowed. - `Optional readOnly` 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. - `Optional> toolNames` List of allowed tool names. - `Optional never` A filter object to specify which tools are allowed. - `Optional readOnly` 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. - `Optional> toolNames` List of allowed tool names. - `enum McpToolApprovalSetting:` 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("always")` - `NEVER("never")` - `Optional serverDescription` Optional description of the MCP server, used to provide more context. - `Optional serverUrl` The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `Optional tunnelId` 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. - `CodeInterpreter` - `Container container` 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` - `class CodeInterpreterToolAuto:` Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `JsonValue; type "auto"constant` Always `auto`. - `AUTO("auto")` - `Optional> fileIds` An optional list of uploaded files to make available to your code. - `Optional memoryLimit` The memory limit for the code interpreter container. - `_1G("1g")` - `_4G("4g")` - `_16G("16g")` - `_64G("64g")` - `Optional networkPolicy` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled:` - `JsonValue; type "disabled"constant` Disable outbound network access. Always `disabled`. - `DISABLED("disabled")` - `class BetaContainerNetworkPolicyAllowlist:` - `List allowedDomains` A list of allowed domains when type is `allowlist`. - `JsonValue; type "allowlist"constant` Allow outbound network access only to specified domains. Always `allowlist`. - `ALLOWLIST("allowlist")` - `Optional> domainSecrets` Optional domain-scoped secrets for allowlisted domains. - `String domain` The domain associated with the secret. - `String name` The name of the secret to inject for the domain. - `String value` The secret value to inject for the domain. - `JsonValue; type "code_interpreter"constant` The type of the code interpreter tool. Always `code_interpreter`. - `CODE_INTERPRETER("code_interpreter")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `JsonValue;` - `JsonValue; type "programmatic_tool_calling"constant` The type of the tool. Always `programmatic_tool_calling`. - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - `ImageGeneration` - `JsonValue; type "image_generation"constant` The type of the image generation tool. Always `image_generation`. - `IMAGE_GENERATION("image_generation")` - `Optional action` Whether to generate a new image or edit an existing image. Default: `auto`. - `GENERATE("generate")` - `EDIT("edit")` - `AUTO("auto")` - `Optional background` 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("transparent")` - `OPAQUE("opaque")` - `AUTO("auto")` - `Optional inputFidelity` 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("high")` - `LOW("low")` - `Optional inputImageMask` Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). - `Optional fileId` File ID for the mask image. - `Optional imageUrl` Base64-encoded mask image. - `Optional model` The image generation model to use. Default: `gpt-image-1`. - `GPT_IMAGE_1("gpt-image-1")` - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - `GPT_IMAGE_2("gpt-image-2")` - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - `GPT_IMAGE_1_5("gpt-image-1.5")` - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - `Optional moderation` Moderation level for the generated image. Default: `auto`. - `AUTO("auto")` - `LOW("low")` - `Optional outputCompression` Compression level for the output image. Default: 100. - `Optional outputFormat` The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. - `PNG("png")` - `WEBP("webp")` - `JPEG("jpeg")` - `Optional partialImages` Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `Optional quality` The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. Default: `auto`. - `LOW("low")` - `MEDIUM("medium")` - `HIGH("high")` - `AUTO("auto")` - `Optional size` 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("1024x1024")` - `_1024X1536("1024x1536")` - `_1536X1024("1536x1024")` - `AUTO("auto")` - `JsonValue;` - `JsonValue; type "local_shell"constant` The type of the local shell tool. Always `local_shell`. - `LOCAL_SHELL("local_shell")` - `class BetaFunctionShellTool:` A tool that allows the model to execute shell commands. - `JsonValue; type "shell"constant` The type of the shell tool. Always `shell`. - `SHELL("shell")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional environment` - `class BetaContainerAuto:` - `JsonValue; type "container_auto"constant` Automatically creates a container for this request - `CONTAINER_AUTO("container_auto")` - `Optional> fileIds` An optional list of uploaded files to make available to your code. - `Optional memoryLimit` The memory limit for the container. - `_1G("1g")` - `_4G("4g")` - `_16G("16g")` - `_64G("64g")` - `Optional networkPolicy` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled:` - `class BetaContainerNetworkPolicyAllowlist:` - `Optional> skills` An optional list of skills referenced by id or inline data. - `class BetaSkillReference:` - `String skillId` The ID of the referenced skill. - `JsonValue; type "skill_reference"constant` References a skill created with the /v1/skills endpoint. - `SKILL_REFERENCE("skill_reference")` - `Optional version` Optional skill version. Use a positive integer or 'latest'. Omit for default. - `class BetaInlineSkill:` - `String description` The description of the skill. - `String name` The name of the skill. - `BetaInlineSkillSource source` Inline skill payload - `String data` Base64-encoded skill zip bundle. - `JsonValue; mediaType "application/zip"constant` The media type of the inline skill payload. Must be `application/zip`. - `APPLICATION_ZIP("application/zip")` - `JsonValue; type "base64"constant` The type of the inline skill source. Must be `base64`. - `BASE64("base64")` - `JsonValue; type "inline"constant` Defines an inline skill for this request. - `INLINE("inline")` - `class BetaLocalEnvironment:` - `JsonValue; type "local"constant` Use a local computer environment. - `LOCAL("local")` - `Optional> skills` An optional list of skills. - `String description` The description of the skill. - `String name` The name of the skill. - `String path` The path to the directory containing the skill. - `class BetaContainerReference:` - `String containerId` The ID of the referenced container. - `JsonValue; type "container_reference"constant` References a container created with the /v1/containers endpoint - `CONTAINER_REFERENCE("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) - `String name` The name of the custom tool, used to identify it in tool calls. - `JsonValue; type "custom"constant` The type of the custom tool. Always `custom`. - `CUSTOM("custom")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional deferLoading` Whether this tool should be deferred and discovered via tool search. - `Optional description` Optional description of the custom tool, used to provide more context. - `Optional format` The input format for the custom tool. Default is unconstrained text. - `JsonValue;` - `JsonValue; type "text"constant` Unconstrained text format. Always `text`. - `TEXT("text")` - `class Grammar:` A grammar defined by the user. - `String definition` The grammar definition. - `Syntax syntax` The syntax of the grammar definition. One of `lark` or `regex`. - `LARK("lark")` - `REGEX("regex")` - `JsonValue; type "grammar"constant` Grammar format. Always `grammar`. - `GRAMMAR("grammar")` - `class BetaNamespaceTool:` Groups function/custom tools under a shared namespace. - `String description` A description of the namespace shown to the model. - `String name` The namespace name used in tool calls (for example, `crm`). - `List tools` The function/custom tools available inside this namespace. - `class Function:` - `String name` - `JsonValue; type "function"constant` - `FUNCTION("function")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional deferLoading` Whether this function should be deferred and discovered via tool search. - `Optional description` - `Optional outputSchema` A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - `Optional parameters` - `Optional strict` 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) - `JsonValue; type "namespace"constant` The type of the tool. Always `namespace`. - `NAMESPACE("namespace")` - `class BetaToolSearchTool:` Hosted or BYOT tool search configuration for deferred tools. - `JsonValue; type "tool_search"constant` The type of the tool. Always `tool_search`. - `TOOL_SEARCH("tool_search")` - `Optional description` Description shown to the model for a client-executed tool search tool. - `Optional execution` Whether tool search is executed by the server or by the client. - `SERVER("server")` - `CLIENT("client")` - `Optional parameters` 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 type` 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")` - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - `Optional> searchContentTypes` - `TEXT("text")` - `IMAGE("image")` - `Optional searchContextSize` 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("low")` - `MEDIUM("medium")` - `HIGH("high")` - `Optional userLocation` The user's location. - `JsonValue; type "approximate"constant` The type of location approximation. Always `approximate`. - `APPROXIMATE("approximate")` - `Optional city` Free text input for the city of the user, e.g. `San Francisco`. - `Optional country` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `Optional region` Free text input for the region of the user, e.g. `California`. - `Optional timezone` 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. - `JsonValue; type "apply_patch"constant` The type of the tool. Always `apply_patch`. - `APPLY_PATCH("apply_patch")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `JsonValue; type "tool_search_output"constant` The item type. Always `tool_search_output`. - `TOOL_SEARCH_OUTPUT("tool_search_output")` - `Optional id` The unique ID of this tool search output. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional callId` The unique ID of the tool search call generated by the model. - `Optional execution` Whether tool search was executed by the server or by the client. - `SERVER("server")` - `CLIENT("client")` - `Optional status` The status of the tool search output. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `AdditionalTools` - `JsonValue; role "developer"constant` The role that provided the additional tools. Only `developer` is supported. - `DEVELOPER("developer")` - `List tools` 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). - `Mcp` - `CodeInterpreter` - `JsonValue;` - `ImageGeneration` - `JsonValue;` - `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. - `JsonValue; type "additional_tools"constant` The item type. Always `additional_tools`. - `ADDITIONAL_TOOLS("additional_tools")` - `Optional id` The unique ID of this additional tools item. - `Optional agent` The agent that produced this item. - `String agentName` 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). - `String id` The unique identifier of the reasoning content. - `List summary` Reasoning summary content. - `String text` A summary of the reasoning output from the model so far. - `JsonValue; type "summary_text"constant` The type of the object. Always `summary_text`. - `SUMMARY_TEXT("summary_text")` - `JsonValue; type "reasoning"constant` The type of the object. Always `reasoning`. - `REASONING("reasoning")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional> content` Reasoning text content. - `String text` The reasoning text from the model. - `JsonValue; type "reasoning_text"constant` The type of the reasoning text. Always `reasoning_text`. - `REASONING_TEXT("reasoning_text")` - `Optional encryptedContent` 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. - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `class BetaResponseCompactionItemParam:` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `String encryptedContent` The encrypted content of the compaction summary. - `JsonValue; type "compaction"constant` The type of the item. Always `compaction`. - `COMPACTION("compaction")` - `Optional id` The ID of the compaction item. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `ImageGenerationCall` - `String id` The unique ID of the image generation call. - `Optional result` The generated image encoded in base64. - `Status status` The status of the image generation call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `GENERATING("generating")` - `FAILED("failed")` - `JsonValue; type "image_generation_call"constant` The type of the image generation call. Always `image_generation_call`. - `IMAGE_GENERATION_CALL("image_generation_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `class BetaResponseCodeInterpreterToolCall:` A tool call to run code. - `String id` The unique ID of the code interpreter tool call. - `Optional code` The code to run, or null if not available. - `String containerId` The ID of the container used to run the code. - `Optional> outputs` 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. - `String logs` The logs output from the code interpreter. - `JsonValue; type "logs"constant` The type of the output. Always `logs`. - `LOGS("logs")` - `class Image:` The image output from the code interpreter. - `JsonValue; type "image"constant` The type of the output. Always `image`. - `IMAGE("image")` - `String url` The URL of the image output from the code interpreter. - `Status status` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `INTERPRETING("interpreting")` - `FAILED("failed")` - `JsonValue; type "code_interpreter_call"constant` The type of the code interpreter tool call. Always `code_interpreter_call`. - `CODE_INTERPRETER_CALL("code_interpreter_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `LocalShellCall` - `String id` The unique ID of the local shell call. - `Action action` Execute a shell command on the server. - `List command` The command to run. - `Env env` Environment variables to set for the command. - `JsonValue; type "exec"constant` The type of the local shell action. Always `exec`. - `EXEC("exec")` - `Optional timeoutMs` Optional timeout in milliseconds for the command. - `Optional user` Optional user to run the command as. - `Optional workingDirectory` Optional working directory to run the command in. - `String callId` The unique ID of the local shell tool call generated by the model. - `Status status` The status of the local shell call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "local_shell_call"constant` The type of the local shell call. Always `local_shell_call`. - `LOCAL_SHELL_CALL("local_shell_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `LocalShellCallOutput` - `String id` The unique ID of the local shell tool call generated by the model. - `String output` A JSON string of the output of the local shell tool call. - `JsonValue; type "local_shell_call_output"constant` The type of the local shell tool call output. Always `local_shell_call_output`. - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `ShellCall` - `Action action` The shell commands and limits that describe how to run the tool call. - `List commands` Ordered shell commands for the execution environment to run. - `Optional maxOutputLength` Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - `Optional timeoutMs` Maximum wall-clock time in milliseconds to allow the shell commands to run. - `String callId` The unique ID of the shell tool call generated by the model. - `JsonValue; type "shell_call"constant` The type of the item. Always `shell_call`. - `SHELL_CALL("shell_call")` - `Optional id` The unique ID of the shell tool call. Populated when this item is returned via API. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` The caller type. Always `direct`. - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` The caller type. Always `program`. - `PROGRAM("program")` - `Optional environment` The environment to execute the shell commands in. - `class BetaLocalEnvironment:` - `class BetaContainerReference:` - `Optional status` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `ShellCallOutput` - `String callId` The unique ID of the shell tool call generated by the model. - `List output` Captured chunks of stdout and stderr output, along with their associated outcomes. - `Outcome outcome` The exit or timeout outcome associated with this shell call. - `JsonValue;` - `JsonValue; type "timeout"constant` The outcome type. Always `timeout`. - `TIMEOUT("timeout")` - `class Exit:` Indicates that the shell commands finished and returned an exit code. - `long exitCode` The exit code returned by the shell process. - `JsonValue; type "exit"constant` The outcome type. Always `exit`. - `EXIT("exit")` - `String stderr` Captured stderr output for the shell call. - `String stdout` Captured stdout output for the shell call. - `JsonValue; type "shell_call_output"constant` The type of the item. Always `shell_call_output`. - `SHELL_CALL_OUTPUT("shell_call_output")` - `Optional id` The unique ID of the shell tool call output. Populated when this item is returned via API. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` The caller type. Always `direct`. - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` The caller type. Always `program`. - `PROGRAM("program")` - `Optional maxOutputLength` The maximum number of UTF-8 characters captured for this shell call's combined output. - `Optional status` The status of the shell call output. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `ApplyPatchCall` - `String callId` The unique ID of the apply patch tool call generated by the model. - `Operation operation` 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. - `String diff` Unified diff content to apply when creating the file. - `String path` Path of the file to create relative to the workspace root. - `JsonValue; type "create_file"constant` The operation type. Always `create_file`. - `CREATE_FILE("create_file")` - `class DeleteFile:` Instruction for deleting an existing file via the apply_patch tool. - `String path` Path of the file to delete relative to the workspace root. - `JsonValue; type "delete_file"constant` The operation type. Always `delete_file`. - `DELETE_FILE("delete_file")` - `class UpdateFile:` Instruction for updating an existing file via the apply_patch tool. - `String diff` Unified diff content to apply to the existing file. - `String path` Path of the file to update relative to the workspace root. - `JsonValue; type "update_file"constant` The operation type. Always `update_file`. - `UPDATE_FILE("update_file")` - `Status status` The status of the apply patch tool call. One of `in_progress` or `completed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `JsonValue; type "apply_patch_call"constant` The type of the item. Always `apply_patch_call`. - `APPLY_PATCH_CALL("apply_patch_call")` - `Optional id` The unique ID of the apply patch tool call. Populated when this item is returned via API. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` The caller type. Always `direct`. - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` The caller type. Always `program`. - `PROGRAM("program")` - `ApplyPatchCallOutput` - `String callId` The unique ID of the apply patch tool call generated by the model. - `Status status` The status of the apply patch tool call output. One of `completed` or `failed`. - `COMPLETED("completed")` - `FAILED("failed")` - `JsonValue; type "apply_patch_call_output"constant` The type of the item. Always `apply_patch_call_output`. - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - `Optional id` The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` The caller type. Always `direct`. - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` The caller type. Always `program`. - `PROGRAM("program")` - `Optional output` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `McpListTools` - `String id` The unique ID of the list. - `String serverLabel` The label of the MCP server. - `List tools` The tools available on the server. - `JsonValue inputSchema` The JSON schema describing the tool's input. - `String name` The name of the tool. - `Optional annotations` Additional annotations about the tool. - `Optional description` The description of the tool. - `JsonValue; type "mcp_list_tools"constant` The type of the item. Always `mcp_list_tools`. - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional error` Error message if the server could not list tools. - `McpApprovalRequest` - `String id` The unique ID of the approval request. - `String arguments` A JSON string of arguments for the tool. - `String name` The name of the tool to run. - `String serverLabel` The label of the MCP server making the request. - `JsonValue; type "mcp_approval_request"constant` The type of the item. Always `mcp_approval_request`. - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `McpApprovalResponse` - `String approvalRequestId` The ID of the approval request being answered. - `boolean approve` Whether the request was approved. - `JsonValue; type "mcp_approval_response"constant` The type of the item. Always `mcp_approval_response`. - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - `Optional id` The unique ID of the approval response - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional reason` Optional reason for the decision. - `McpCall` - `String id` The unique ID of the tool call. - `String arguments` A JSON string of the arguments passed to the tool. - `String name` The name of the tool that was run. - `String serverLabel` The label of the MCP server running the tool. - `JsonValue; type "mcp_call"constant` The type of the item. Always `mcp_call`. - `MCP_CALL("mcp_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional approvalRequestId` 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. - `Optional error` The error from the tool call, if any. - `Optional output` The output from the tool call. - `Optional status` The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `CALLING("calling")` - `FAILED("failed")` - `class BetaResponseCustomToolCallOutput:` The output of a custom tool call from your code, being sent back to the model. - `String callId` The call ID, used to map this custom tool call output to a custom tool call. - `Output output` The output from the custom tool call generated by your code. Can be a string or an list of output content. - `String` - `List` - `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. - `JsonValue; type "custom_tool_call_output"constant` The type of the custom tool call output. Always `custom_tool_call_output`. - `CUSTOM_TOOL_CALL_OUTPUT("custom_tool_call_output")` - `Optional id` The unique ID of the custom tool call output in the OpenAI platform. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` The caller type. Always `direct`. - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` The caller type. Always `program`. - `PROGRAM("program")` - `class BetaResponseCustomToolCall:` A call to a custom tool created by the model. - `String callId` An identifier used to map this custom tool call to a tool call output. - `String input` The input for the custom tool call generated by the model. - `String name` The name of the custom tool being called. - `JsonValue; type "custom_tool_call"constant` The type of the custom tool call. Always `custom_tool_call`. - `CUSTOM_TOOL_CALL("custom_tool_call")` - `Optional id` The unique ID of the custom tool call in the OpenAI platform. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional namespace` The namespace of the custom tool being called. - `CompactionTrigger` - `JsonValue; type "compaction_trigger"constant` The type of the item. Always `compaction_trigger`. - `COMPACTION_TRIGGER("compaction_trigger")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `ItemReference` - `String id` The ID of the item to reference. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional type` The type of item to reference. Always `item_reference`. - `ITEM_REFERENCE("item_reference")` - `Program` - `String id` The unique ID of this program item. - `String callId` The stable call ID of the program item. - `String code` The JavaScript source executed by programmatic tool calling. - `String fingerprint` Opaque program replay fingerprint that must be round-tripped. - `JsonValue; type "program"constant` The item type. Always `program`. - `PROGRAM("program")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `ProgramOutput` - `String id` The unique ID of this program output item. - `String callId` The call ID of the program item. - `String result` The result produced by the program item. - `Status status` The terminal status of the program output. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "program_output"constant` The item type. Always `program_output`. - `PROGRAM_OUTPUT("program_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional instructions` 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. - `Optional previousResponseId` 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`. - `Optional promptCacheKey` A key to use when reading from or writing to the prompt cache. - `Optional promptCacheOptions` 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. - `Optional mode` 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("implicit")` - `EXPLICIT("explicit")` - `Optional ttl` 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("30m")` - `Optional promptCacheRetention` How long to retain a prompt cache entry created by this request. - `IN_MEMORY("in_memory")` - `_24H("24h")` - `Optional serviceTier` The service tier to use for this request. - `AUTO("auto")` - `DEFAULT("default")` - `FLEX("flex")` - `PRIORITY("priority")` ### Returns - `class BetaCompactedResponse:` - `String id` The unique identifier for the compacted response. - `long createdAt` Unix timestamp (in seconds) when the compacted conversation was created. - `JsonValue; object_ "response.compaction"constant` The object type. Always `response.compaction`. - `RESPONSE_COMPACTION("response.compaction")` - `List output` 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. - `String id` The unique ID of the output message. - `List content` The content of the output message. - `class BetaResponseOutputText:` A text output from the model. - `List annotations` The annotations of the text output. - `class FileCitation:` A citation to a file. - `String fileId` The ID of the file. - `String filename` The filename of the file cited. - `long index` The index of the file in the list of files. - `JsonValue; type "file_citation"constant` The type of the file citation. Always `file_citation`. - `FILE_CITATION("file_citation")` - `class UrlCitation:` A citation for a web resource used to generate a model response. - `long endIndex` The index of the last character of the URL citation in the message. - `long startIndex` The index of the first character of the URL citation in the message. - `String title` The title of the web resource. - `JsonValue; type "url_citation"constant` The type of the URL citation. Always `url_citation`. - `URL_CITATION("url_citation")` - `String url` The URL of the web resource. - `class ContainerFileCitation:` A citation for a container file used to generate a model response. - `String containerId` The ID of the container file. - `long endIndex` The index of the last character of the container file citation in the message. - `String fileId` The ID of the file. - `String filename` The filename of the container file cited. - `long startIndex` The index of the first character of the container file citation in the message. - `JsonValue; type "container_file_citation"constant` The type of the container file citation. Always `container_file_citation`. - `CONTAINER_FILE_CITATION("container_file_citation")` - `class FilePath:` A path to a file. - `String fileId` The ID of the file. - `long index` The index of the file in the list of files. - `JsonValue; type "file_path"constant` The type of the file path. Always `file_path`. - `FILE_PATH("file_path")` - `String text` The text output from the model. - `JsonValue; type "output_text"constant` The type of the output text. Always `output_text`. - `OUTPUT_TEXT("output_text")` - `Optional> logprobs` - `String token` - `List bytes` - `double logprob` - `List topLogprobs` - `String token` - `List bytes` - `double logprob` - `class BetaResponseOutputRefusal:` A refusal from the model. - `String refusal` The refusal explanation from the model. - `JsonValue; type "refusal"constant` The type of the refusal. Always `refusal`. - `REFUSAL("refusal")` - `JsonValue; role "assistant"constant` The role of the output message. Always `assistant`. - `ASSISTANT("assistant")` - `Status status` The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "message"constant` The type of the output message. Always `message`. - `MESSAGE("message")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional phase` 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("commentary")` - `FINAL_ANSWER("final_answer")` - `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. - `String id` The unique ID of the file search tool call. - `List queries` The queries used to search for files. - `Status status` The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `IN_PROGRESS("in_progress")` - `SEARCHING("searching")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `FAILED("failed")` - `JsonValue; type "file_search_call"constant` The type of the file search tool call. Always `file_search_call`. - `FILE_SEARCH_CALL("file_search_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional> results` The results of the file search tool call. - `Optional attributes` 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` - `double` - `boolean` - `Optional fileId` The unique ID of the file. - `Optional filename` The name of the file. - `Optional score` The relevance score of the file - a value between 0 and 1. - `Optional text` 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. - `String arguments` A JSON string of the arguments to pass to the function. - `String callId` The unique ID of the function tool call generated by the model. - `String name` The name of the function to run. - `JsonValue; type "function_call"constant` The type of the function tool call. Always `function_call`. - `FUNCTION_CALL("function_call")` - `Optional id` The unique ID of the function tool call. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional namespace` The namespace of the function to run. - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `class BetaResponseFunctionToolCallOutputItem:` - `String id` The unique ID of the function call tool output. - `String callId` The unique ID of the function tool call generated by the model. - `Output output` The output from the function call generated by your code. Can be a string or an list of output content. - `String` - `List` - `class BetaResponseInputText:` A text input to the model. - `String text` The text input to the model. - `JsonValue; type "input_text"constant` The type of the input item. Always `input_text`. - `INPUT_TEXT("input_text")` - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `class BetaResponseInputImage:` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `Detail detail` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `LOW("low")` - `HIGH("high")` - `AUTO("auto")` - `ORIGINAL("original")` - `JsonValue; type "input_image"constant` The type of the input item. Always `input_image`. - `INPUT_IMAGE("input_image")` - `Optional fileId` The ID of the file to be sent to the model. - `Optional imageUrl` The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `class BetaResponseInputFile:` A file input to the model. - `JsonValue; type "input_file"constant` The type of the input item. Always `input_file`. - `INPUT_FILE("input_file")` - `Optional detail` 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("auto")` - `LOW("low")` - `HIGH("high")` - `Optional fileData` The content of the file to be sent to the model. - `Optional fileId` The ID of the file to be sent to the model. - `Optional fileUrl` The URL of the file to be sent to the model. - `Optional filename` The name of the file to be sent to the model. - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `Status status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "function_call_output"constant` The type of the function tool call output. Always `function_call_output`. - `FUNCTION_CALL_OUTPUT("function_call_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` The caller type. Always `direct`. - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` The caller type. Always `program`. - `PROGRAM("program")` - `Optional createdBy` The identifier of the actor that created the item. - `AgentMessage` - `String id` The unique ID of the agent message. - `String author` The sending agent identity. - `List content` 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. - `String text` - `JsonValue; type "text"constant` - `TEXT("text")` - `class SummaryText:` A summary text from the model. - `String text` A summary of the reasoning output from the model so far. - `JsonValue; type "summary_text"constant` The type of the object. Always `summary_text`. - `SUMMARY_TEXT("summary_text")` - `class ReasoningText:` Reasoning text from the model. - `String text` The reasoning text from the model. - `JsonValue; type "reasoning_text"constant` The type of the reasoning text. Always `reasoning_text`. - `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 detail` The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `LOW("low")` - `HIGH("high")` - `AUTO("auto")` - `ORIGINAL("original")` - `Optional fileId` The identifier of an uploaded file that contains the screenshot. - `Optional imageUrl` The URL of the screenshot image. - `JsonValue; type "computer_screenshot"constant` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `COMPUTER_SCREENSHOT("computer_screenshot")` - `Optional promptCacheBreakpoint` 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. - `JsonValue; mode "explicit"constant` The breakpoint mode. Always `explicit`. - `EXPLICIT("explicit")` - `class BetaResponseInputFile:` A file input to the model. - `class EncryptedContent:` Opaque encrypted content that Responses API decrypts inside trusted model execution. - `String encryptedContent` Opaque encrypted content. - `JsonValue; type "encrypted_content"constant` The type of the input item. Always `encrypted_content`. - `ENCRYPTED_CONTENT("encrypted_content")` - `String recipient` The destination agent identity. - `JsonValue; type "agent_message"constant` The type of the item. Always `agent_message`. - `AGENT_MESSAGE("agent_message")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `MultiAgentCall` - `String id` The unique ID of the multi-agent call item. - `Action action` The multi-agent action to execute. - `SPAWN_AGENT("spawn_agent")` - `INTERRUPT_AGENT("interrupt_agent")` - `LIST_AGENTS("list_agents")` - `SEND_MESSAGE("send_message")` - `FOLLOWUP_TASK("followup_task")` - `WAIT_AGENT("wait_agent")` - `String arguments` The JSON string of arguments generated for the action. - `String callId` The unique ID linking this call to its output. - `JsonValue; type "multi_agent_call"constant` The type of the multi-agent call. Always `multi_agent_call`. - `MULTI_AGENT_CALL("multi_agent_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `MultiAgentCallOutput` - `String id` The unique ID of the multi-agent call output item. - `Action action` The multi-agent action that produced this result. - `SPAWN_AGENT("spawn_agent")` - `INTERRUPT_AGENT("interrupt_agent")` - `LIST_AGENTS("list_agents")` - `SEND_MESSAGE("send_message")` - `FOLLOWUP_TASK("followup_task")` - `WAIT_AGENT("wait_agent")` - `String callId` The unique ID of the multi-agent call. - `List output` Text output returned by the multi-agent action. - `List annotations` The annotations of the text output. - `String text` The text output from the model. - `JsonValue; type "output_text"constant` The type of the output text. Always `output_text`. - `Optional> logprobs` - `JsonValue; type "multi_agent_call_output"constant` The type of the multi-agent result. Always `multi_agent_call_output`. - `MULTI_AGENT_CALL_OUTPUT("multi_agent_call_output")` - `Optional agent` The agent that produced this item. - `String agentName` 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. - `String id` The unique ID of the web search tool call. - `Action action` An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page). - `class Search:` Action type "search" - Performs a web search query. - `JsonValue; type "search"constant` The action type. - `SEARCH("search")` - `Optional> queries` The search queries. - `Optional query` The search query. - `Optional> sources` The sources used in the search. - `JsonValue; type "url"constant` The type of source. Always `url`. - `URL("url")` - `String url` The URL of the source. - `class OpenPage:` Action type "open_page" - Opens a specific URL from search results. - `JsonValue; type "open_page"constant` The action type. - `OPEN_PAGE("open_page")` - `Optional url` The URL opened by the model. - `class FindInPage:` Action type "find_in_page": Searches for a pattern within a loaded page. - `String pattern` The pattern or text to search for within the page. - `JsonValue; type "find_in_page"constant` The action type. - `FIND_IN_PAGE("find_in_page")` - `String url` The URL of the page searched for the pattern. - `Status status` The status of the web search tool call. - `IN_PROGRESS("in_progress")` - `SEARCHING("searching")` - `COMPLETED("completed")` - `FAILED("failed")` - `JsonValue; type "web_search_call"constant` The type of the web search tool call. Always `web_search_call`. - `WEB_SEARCH_CALL("web_search_call")` - `Optional agent` The agent that produced this item. - `String agentName` 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. - `String id` The unique ID of the computer call. - `String callId` An identifier used when responding to the tool call with output. - `List pendingSafetyChecks` The pending safety checks for the computer call. - `String id` The ID of the pending safety check. - `Optional code` The type of the pending safety check. - `Optional message` Details about the pending safety check. - `Status status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `Type type` The type of the computer call. Always `computer_call`. - `COMPUTER_CALL("computer_call")` - `Optional action` A click action. - `Click` - `Button button` Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - `LEFT("left")` - `RIGHT("right")` - `WHEEL("wheel")` - `BACK("back")` - `FORWARD("forward")` - `JsonValue; type "click"constant` Specifies the event type. For a click action, this property is always `click`. - `CLICK("click")` - `long x` The x-coordinate where the click occurred. - `long y` The y-coordinate where the click occurred. - `Optional> keys` The keys being held while clicking. - `DoubleClick` - `Optional> keys` The keys being held while double-clicking. - `JsonValue; type "double_click"constant` Specifies the event type. For a double click action, this property is always set to `double_click`. - `DOUBLE_CLICK("double_click")` - `long x` The x-coordinate where the double click occurred. - `long y` The y-coordinate where the double click occurred. - `Drag` - `List path` 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 } ] ``` - `long x` The x-coordinate. - `long y` The y-coordinate. - `JsonValue; type "drag"constant` Specifies the event type. For a drag action, this property is always set to `drag`. - `DRAG("drag")` - `Optional> keys` The keys being held while dragging the mouse. - `Keypress` - `List keys` The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - `JsonValue; type "keypress"constant` Specifies the event type. For a keypress action, this property is always set to `keypress`. - `KEYPRESS("keypress")` - `Move` - `JsonValue; type "move"constant` Specifies the event type. For a move action, this property is always set to `move`. - `MOVE("move")` - `long x` The x-coordinate to move to. - `long y` The y-coordinate to move to. - `Optional> keys` The keys being held while moving the mouse. - `JsonValue;` - `JsonValue; type "screenshot"constant` Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - `SCREENSHOT("screenshot")` - `Scroll` - `long scrollX` The horizontal scroll distance. - `long scrollY` The vertical scroll distance. - `JsonValue; type "scroll"constant` Specifies the event type. For a scroll action, this property is always set to `scroll`. - `SCROLL("scroll")` - `long x` The x-coordinate where the scroll occurred. - `long y` The y-coordinate where the scroll occurred. - `Optional> keys` The keys being held while scrolling. - `Type` - `String text` The text to type. - `JsonValue; type "type"constant` Specifies the event type. For a type action, this property is always set to `type`. - `TYPE("type")` - `JsonValue;` - `JsonValue; type "wait"constant` Specifies the event type. For a wait action, this property is always set to `wait`. - `WAIT("wait")` - `Optional> actions` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - `Click` - `DoubleClick` - `Drag` - `Keypress` - `Move` - `JsonValue;` - `Scroll` - `Type` - `JsonValue;` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `class BetaResponseComputerToolCallOutputItem:` - `String id` The unique ID of the computer call tool output. - `String callId` The ID of the computer tool call that produced the output. - `BetaResponseComputerToolCallOutputScreenshot output` A computer screenshot image used with the computer use tool. - `JsonValue; type "computer_screenshot"constant` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `COMPUTER_SCREENSHOT("computer_screenshot")` - `Optional fileId` The identifier of an uploaded file that contains the screenshot. - `Optional imageUrl` The URL of the screenshot image. - `Status status` The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `FAILED("failed")` - `IN_PROGRESS("in_progress")` - `JsonValue; type "computer_call_output"constant` The type of the computer tool call output. Always `computer_call_output`. - `COMPUTER_CALL_OUTPUT("computer_call_output")` - `Optional> acknowledgedSafetyChecks` The safety checks reported by the API that have been acknowledged by the developer. - `String id` The ID of the pending safety check. - `Optional code` The type of the pending safety check. - `Optional message` Details about the pending safety check. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional createdBy` 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). - `String id` The unique identifier of the reasoning content. - `List summary` Reasoning summary content. - `String text` A summary of the reasoning output from the model so far. - `JsonValue; type "summary_text"constant` The type of the object. Always `summary_text`. - `SUMMARY_TEXT("summary_text")` - `JsonValue; type "reasoning"constant` The type of the object. Always `reasoning`. - `REASONING("reasoning")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional> content` Reasoning text content. - `String text` The reasoning text from the model. - `JsonValue; type "reasoning_text"constant` The type of the reasoning text. Always `reasoning_text`. - `REASONING_TEXT("reasoning_text")` - `Optional encryptedContent` 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. - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `Program` - `String id` The unique ID of the program item. - `String callId` The stable call ID of the program item. - `String code` The JavaScript source executed by programmatic tool calling. - `String fingerprint` Opaque program replay fingerprint that must be round-tripped. - `JsonValue; type "program"constant` The type of the item. Always `program`. - `PROGRAM("program")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `ProgramOutput` - `String id` The unique ID of the program output item. - `String callId` The call ID of the program item. - `String result` The result produced by the program item. - `Status status` The terminal status of the program output item. - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "program_output"constant` The type of the item. Always `program_output`. - `PROGRAM_OUTPUT("program_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `class BetaResponseToolSearchCall:` - `String id` The unique ID of the tool search call item. - `JsonValue arguments` Arguments used for the tool search call. - `Optional callId` The unique ID of the tool search call generated by the model. - `Execution execution` Whether tool search was executed by the server or by the client. - `SERVER("server")` - `CLIENT("client")` - `Status status` The status of the tool search call item that was recorded. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "tool_search_call"constant` The type of the item. Always `tool_search_call`. - `TOOL_SEARCH_CALL("tool_search_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional createdBy` The identifier of the actor that created the item. - `class BetaResponseToolSearchOutputItem:` - `String id` The unique ID of the tool search output item. - `Optional callId` The unique ID of the tool search call generated by the model. - `Execution execution` Whether tool search was executed by the server or by the client. - `SERVER("server")` - `CLIENT("client")` - `Status status` The status of the tool search output item that was recorded. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `List tools` 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). - `String name` The name of the function to call. - `Optional parameters` A JSON schema object describing the parameters of the function. - `Optional strict` Whether strict parameter validation is enforced for this function tool. - `JsonValue; type "function"constant` The type of the function tool. Always `function`. - `FUNCTION("function")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional deferLoading` Whether this function is deferred and loaded via tool search. - `Optional description` A description of the function. Used by the model to determine whether or not to call the function. - `Optional outputSchema` 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). - `JsonValue; type "file_search"constant` The type of the file search tool. Always `file_search`. - `FILE_SEARCH("file_search")` - `List vectorStoreIds` The IDs of the vector stores to search. - `Optional filters` A filter to apply. - `class ComparisonFilter:` A filter used to compare a specified attribute key to a given value using a defined comparison operation. - `String key` The key to compare against the value. - `Type type` 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("eq")` - `NE("ne")` - `GT("gt")` - `GTE("gte")` - `LT("lt")` - `LTE("lte")` - `IN("in")` - `NIN("nin")` - `Value value` The value to compare against the attribute key; supports string, number, or boolean types. - `String` - `double` - `boolean` - `List` - `String` - `double` - `class CompoundFilter:` Combine multiple filters using `and` or `or`. - `List filters` 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. - `String key` The key to compare against the value. - `Type type` 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("eq")` - `NE("ne")` - `GT("gt")` - `GTE("gte")` - `LT("lt")` - `LTE("lte")` - `IN("in")` - `NIN("nin")` - `Value value` The value to compare against the attribute key; supports string, number, or boolean types. - `String` - `double` - `boolean` - `List` - `String` - `double` - `JsonValue` - `Type type` Type of operation: `and` or `or`. - `AND("and")` - `OR("or")` - `Optional maxNumResults` The maximum number of results to return. This number should be between 1 and 50 inclusive. - `Optional rankingOptions` Ranking options for search. - `Optional hybridSearch` Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - `double embeddingWeight` The weight of the embedding in the reciprocal ranking fusion. - `double textWeight` The weight of the text in the reciprocal ranking fusion. - `Optional ranker` The ranker to use for the file search. - `AUTO("auto")` - `DEFAULT_2024_11_15("default-2024-11-15")` - `Optional scoreThreshold` 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). - `JsonValue; type "computer"constant` The type of the computer tool. Always `computer`. - `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). - `long displayHeight` The height of the computer display. - `long displayWidth` The width of the computer display. - `Environment environment` The type of computer environment to control. - `WINDOWS("windows")` - `MAC("mac")` - `LINUX("linux")` - `UBUNTU("ubuntu")` - `BROWSER("browser")` - `JsonValue; type "computer_use_preview"constant` The type of the computer use tool. Always `computer_use_preview`. - `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 type` The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - `WEB_SEARCH("web_search")` - `WEB_SEARCH_2025_08_26("web_search_2025_08_26")` - `Optional filters` Filters for the search. - `Optional> allowedDomains` 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"]` - `Optional searchContextSize` 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("low")` - `MEDIUM("medium")` - `HIGH("high")` - `Optional userLocation` The approximate location of the user. - `Optional city` Free text input for the city of the user, e.g. `San Francisco`. - `Optional country` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `Optional region` Free text input for the region of the user, e.g. `California`. - `Optional timezone` The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `Optional type` The type of location approximation. Always `approximate`. - `APPROXIMATE("approximate")` - `Mcp` - `String serverLabel` A label for this MCP server, used to identify it in tool calls. - `JsonValue; type "mcp"constant` The type of the MCP tool. Always `mcp`. - `MCP("mcp")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional allowedTools` List of allowed tool names or a filter object. - `List` - `class McpToolFilter:` A filter object to specify which tools are allowed. - `Optional readOnly` 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. - `Optional> toolNames` List of allowed tool names. - `Optional authorization` 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. - `Optional connectorId` 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_dropbox")` - `CONNECTOR_GMAIL("connector_gmail")` - `CONNECTOR_GOOGLECALENDAR("connector_googlecalendar")` - `CONNECTOR_GOOGLEDRIVE("connector_googledrive")` - `CONNECTOR_MICROSOFTTEAMS("connector_microsoftteams")` - `CONNECTOR_OUTLOOKCALENDAR("connector_outlookcalendar")` - `CONNECTOR_OUTLOOKEMAIL("connector_outlookemail")` - `CONNECTOR_SHAREPOINT("connector_sharepoint")` - `Optional deferLoading` Whether this MCP tool is deferred and discovered via tool search. - `Optional headers` Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `Optional requireApproval` 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. - `Optional always` A filter object to specify which tools are allowed. - `Optional readOnly` 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. - `Optional> toolNames` List of allowed tool names. - `Optional never` A filter object to specify which tools are allowed. - `Optional readOnly` 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. - `Optional> toolNames` List of allowed tool names. - `enum McpToolApprovalSetting:` 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("always")` - `NEVER("never")` - `Optional serverDescription` Optional description of the MCP server, used to provide more context. - `Optional serverUrl` The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `Optional tunnelId` 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. - `CodeInterpreter` - `Container container` 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` - `class CodeInterpreterToolAuto:` Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `JsonValue; type "auto"constant` Always `auto`. - `AUTO("auto")` - `Optional> fileIds` An optional list of uploaded files to make available to your code. - `Optional memoryLimit` The memory limit for the code interpreter container. - `_1G("1g")` - `_4G("4g")` - `_16G("16g")` - `_64G("64g")` - `Optional networkPolicy` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled:` - `JsonValue; type "disabled"constant` Disable outbound network access. Always `disabled`. - `DISABLED("disabled")` - `class BetaContainerNetworkPolicyAllowlist:` - `List allowedDomains` A list of allowed domains when type is `allowlist`. - `JsonValue; type "allowlist"constant` Allow outbound network access only to specified domains. Always `allowlist`. - `ALLOWLIST("allowlist")` - `Optional> domainSecrets` Optional domain-scoped secrets for allowlisted domains. - `String domain` The domain associated with the secret. - `String name` The name of the secret to inject for the domain. - `String value` The secret value to inject for the domain. - `JsonValue; type "code_interpreter"constant` The type of the code interpreter tool. Always `code_interpreter`. - `CODE_INTERPRETER("code_interpreter")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `JsonValue;` - `JsonValue; type "programmatic_tool_calling"constant` The type of the tool. Always `programmatic_tool_calling`. - `PROGRAMMATIC_TOOL_CALLING("programmatic_tool_calling")` - `ImageGeneration` - `JsonValue; type "image_generation"constant` The type of the image generation tool. Always `image_generation`. - `IMAGE_GENERATION("image_generation")` - `Optional action` Whether to generate a new image or edit an existing image. Default: `auto`. - `GENERATE("generate")` - `EDIT("edit")` - `AUTO("auto")` - `Optional background` 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("transparent")` - `OPAQUE("opaque")` - `AUTO("auto")` - `Optional inputFidelity` 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("high")` - `LOW("low")` - `Optional inputImageMask` Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). - `Optional fileId` File ID for the mask image. - `Optional imageUrl` Base64-encoded mask image. - `Optional model` The image generation model to use. Default: `gpt-image-1`. - `GPT_IMAGE_1("gpt-image-1")` - `GPT_IMAGE_1_MINI("gpt-image-1-mini")` - `GPT_IMAGE_2("gpt-image-2")` - `GPT_IMAGE_2_2026_04_21("gpt-image-2-2026-04-21")` - `GPT_IMAGE_1_5("gpt-image-1.5")` - `CHATGPT_IMAGE_LATEST("chatgpt-image-latest")` - `Optional moderation` Moderation level for the generated image. Default: `auto`. - `AUTO("auto")` - `LOW("low")` - `Optional outputCompression` Compression level for the output image. Default: 100. - `Optional outputFormat` The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. - `PNG("png")` - `WEBP("webp")` - `JPEG("jpeg")` - `Optional partialImages` Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `Optional quality` The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. Default: `auto`. - `LOW("low")` - `MEDIUM("medium")` - `HIGH("high")` - `AUTO("auto")` - `Optional size` 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("1024x1024")` - `_1024X1536("1024x1536")` - `_1536X1024("1536x1024")` - `AUTO("auto")` - `JsonValue;` - `JsonValue; type "local_shell"constant` The type of the local shell tool. Always `local_shell`. - `LOCAL_SHELL("local_shell")` - `class BetaFunctionShellTool:` A tool that allows the model to execute shell commands. - `JsonValue; type "shell"constant` The type of the shell tool. Always `shell`. - `SHELL("shell")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional environment` - `class BetaContainerAuto:` - `JsonValue; type "container_auto"constant` Automatically creates a container for this request - `CONTAINER_AUTO("container_auto")` - `Optional> fileIds` An optional list of uploaded files to make available to your code. - `Optional memoryLimit` The memory limit for the container. - `_1G("1g")` - `_4G("4g")` - `_16G("16g")` - `_64G("64g")` - `Optional networkPolicy` Network access policy for the container. - `class BetaContainerNetworkPolicyDisabled:` - `class BetaContainerNetworkPolicyAllowlist:` - `Optional> skills` An optional list of skills referenced by id or inline data. - `class BetaSkillReference:` - `String skillId` The ID of the referenced skill. - `JsonValue; type "skill_reference"constant` References a skill created with the /v1/skills endpoint. - `SKILL_REFERENCE("skill_reference")` - `Optional version` Optional skill version. Use a positive integer or 'latest'. Omit for default. - `class BetaInlineSkill:` - `String description` The description of the skill. - `String name` The name of the skill. - `BetaInlineSkillSource source` Inline skill payload - `String data` Base64-encoded skill zip bundle. - `JsonValue; mediaType "application/zip"constant` The media type of the inline skill payload. Must be `application/zip`. - `APPLICATION_ZIP("application/zip")` - `JsonValue; type "base64"constant` The type of the inline skill source. Must be `base64`. - `BASE64("base64")` - `JsonValue; type "inline"constant` Defines an inline skill for this request. - `INLINE("inline")` - `class BetaLocalEnvironment:` - `JsonValue; type "local"constant` Use a local computer environment. - `LOCAL("local")` - `Optional> skills` An optional list of skills. - `String description` The description of the skill. - `String name` The name of the skill. - `String path` The path to the directory containing the skill. - `class BetaContainerReference:` - `String containerId` The ID of the referenced container. - `JsonValue; type "container_reference"constant` References a container created with the /v1/containers endpoint - `CONTAINER_REFERENCE("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) - `String name` The name of the custom tool, used to identify it in tool calls. - `JsonValue; type "custom"constant` The type of the custom tool. Always `custom`. - `CUSTOM("custom")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional deferLoading` Whether this tool should be deferred and discovered via tool search. - `Optional description` Optional description of the custom tool, used to provide more context. - `Optional format` The input format for the custom tool. Default is unconstrained text. - `JsonValue;` - `JsonValue; type "text"constant` Unconstrained text format. Always `text`. - `TEXT("text")` - `class Grammar:` A grammar defined by the user. - `String definition` The grammar definition. - `Syntax syntax` The syntax of the grammar definition. One of `lark` or `regex`. - `LARK("lark")` - `REGEX("regex")` - `JsonValue; type "grammar"constant` Grammar format. Always `grammar`. - `GRAMMAR("grammar")` - `class BetaNamespaceTool:` Groups function/custom tools under a shared namespace. - `String description` A description of the namespace shown to the model. - `String name` The namespace name used in tool calls (for example, `crm`). - `List tools` The function/custom tools available inside this namespace. - `class Function:` - `String name` - `JsonValue; type "function"constant` - `FUNCTION("function")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `Optional deferLoading` Whether this function should be deferred and discovered via tool search. - `Optional description` - `Optional outputSchema` A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - `Optional parameters` - `Optional strict` 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) - `JsonValue; type "namespace"constant` The type of the tool. Always `namespace`. - `NAMESPACE("namespace")` - `class BetaToolSearchTool:` Hosted or BYOT tool search configuration for deferred tools. - `JsonValue; type "tool_search"constant` The type of the tool. Always `tool_search`. - `TOOL_SEARCH("tool_search")` - `Optional description` Description shown to the model for a client-executed tool search tool. - `Optional execution` Whether tool search is executed by the server or by the client. - `SERVER("server")` - `CLIENT("client")` - `Optional parameters` 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 type` 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")` - `WEB_SEARCH_PREVIEW_2025_03_11("web_search_preview_2025_03_11")` - `Optional> searchContentTypes` - `TEXT("text")` - `IMAGE("image")` - `Optional searchContextSize` 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("low")` - `MEDIUM("medium")` - `HIGH("high")` - `Optional userLocation` The user's location. - `JsonValue; type "approximate"constant` The type of location approximation. Always `approximate`. - `APPROXIMATE("approximate")` - `Optional city` Free text input for the city of the user, e.g. `San Francisco`. - `Optional country` The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `Optional region` Free text input for the region of the user, e.g. `California`. - `Optional timezone` 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. - `JsonValue; type "apply_patch"constant` The type of the tool. Always `apply_patch`. - `APPLY_PATCH("apply_patch")` - `Optional> allowedCallers` The tool invocation context(s). - `DIRECT("direct")` - `PROGRAMMATIC("programmatic")` - `JsonValue; type "tool_search_output"constant` The type of the item. Always `tool_search_output`. - `TOOL_SEARCH_OUTPUT("tool_search_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional createdBy` The identifier of the actor that created the item. - `AdditionalTools` - `String id` The unique ID of the additional tools item. - `Role role` The role that provided the additional tools. - `UNKNOWN("unknown")` - `USER("user")` - `ASSISTANT("assistant")` - `SYSTEM("system")` - `CRITIC("critic")` - `DISCRIMINATOR("discriminator")` - `DEVELOPER("developer")` - `TOOL("tool")` - `List tools` 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). - `Mcp` - `CodeInterpreter` - `JsonValue;` - `ImageGeneration` - `JsonValue;` - `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. - `JsonValue; type "additional_tools"constant` The type of the item. Always `additional_tools`. - `ADDITIONAL_TOOLS("additional_tools")` - `Optional agent` The agent that produced this item. - `String agentName` 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). - `String id` The unique ID of the compaction item. - `String encryptedContent` The encrypted content that was produced by compaction. - `JsonValue; type "compaction"constant` The type of the item. Always `compaction`. - `COMPACTION("compaction")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional createdBy` The identifier of the actor that created the item. - `ImageGenerationCall` - `String id` The unique ID of the image generation call. - `Optional result` The generated image encoded in base64. - `Status status` The status of the image generation call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `GENERATING("generating")` - `FAILED("failed")` - `JsonValue; type "image_generation_call"constant` The type of the image generation call. Always `image_generation_call`. - `IMAGE_GENERATION_CALL("image_generation_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `class BetaResponseCodeInterpreterToolCall:` A tool call to run code. - `String id` The unique ID of the code interpreter tool call. - `Optional code` The code to run, or null if not available. - `String containerId` The ID of the container used to run the code. - `Optional> outputs` 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. - `String logs` The logs output from the code interpreter. - `JsonValue; type "logs"constant` The type of the output. Always `logs`. - `LOGS("logs")` - `class Image:` The image output from the code interpreter. - `JsonValue; type "image"constant` The type of the output. Always `image`. - `IMAGE("image")` - `String url` The URL of the image output from the code interpreter. - `Status status` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `INTERPRETING("interpreting")` - `FAILED("failed")` - `JsonValue; type "code_interpreter_call"constant` The type of the code interpreter tool call. Always `code_interpreter_call`. - `CODE_INTERPRETER_CALL("code_interpreter_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `LocalShellCall` - `String id` The unique ID of the local shell call. - `Action action` Execute a shell command on the server. - `List command` The command to run. - `Env env` Environment variables to set for the command. - `JsonValue; type "exec"constant` The type of the local shell action. Always `exec`. - `EXEC("exec")` - `Optional timeoutMs` Optional timeout in milliseconds for the command. - `Optional user` Optional user to run the command as. - `Optional workingDirectory` Optional working directory to run the command in. - `String callId` The unique ID of the local shell tool call generated by the model. - `Status status` The status of the local shell call. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "local_shell_call"constant` The type of the local shell call. Always `local_shell_call`. - `LOCAL_SHELL_CALL("local_shell_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `LocalShellCallOutput` - `String id` The unique ID of the local shell tool call generated by the model. - `String output` A JSON string of the output of the local shell tool call. - `JsonValue; type "local_shell_call_output"constant` The type of the local shell tool call output. Always `local_shell_call_output`. - `LOCAL_SHELL_CALL_OUTPUT("local_shell_call_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `class BetaResponseFunctionShellToolCall:` A tool call that executes one or more shell commands in a managed environment. - `String id` The unique ID of the shell tool call. Populated when this item is returned via API. - `Action action` The shell commands and limits that describe how to run the tool call. - `List commands` - `Optional maxOutputLength` Optional maximum number of characters to return from each command. - `Optional timeoutMs` Optional timeout in milliseconds for the commands. - `String callId` The unique ID of the shell tool call generated by the model. - `Optional environment` Represents the use of a local environment to perform shell actions. - `class BetaResponseLocalEnvironment:` Represents the use of a local environment to perform shell actions. - `JsonValue; type "local"constant` The environment type. Always `local`. - `LOCAL("local")` - `class BetaResponseContainerReference:` Represents a container created with /v1/containers. - `String containerId` - `JsonValue; type "container_reference"constant` The environment type. Always `container_reference`. - `CONTAINER_REFERENCE("container_reference")` - `Status status` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "shell_call"constant` The type of the item. Always `shell_call`. - `SHELL_CALL("shell_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional createdBy` The ID of the entity that created this tool call. - `class BetaResponseFunctionShellToolCallOutput:` The output of a shell tool call that was emitted. - `String id` The unique ID of the shell call output. Populated when this item is returned via API. - `String callId` The unique ID of the shell tool call generated by the model. - `Optional maxOutputLength` The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - `List output` An array of shell call output contents - `Outcome outcome` Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `JsonValue;` - `JsonValue; type "timeout"constant` The outcome type. Always `timeout`. - `TIMEOUT("timeout")` - `class Exit:` Indicates that the shell commands finished and returned an exit code. - `long exitCode` Exit code from the shell process. - `JsonValue; type "exit"constant` The outcome type. Always `exit`. - `EXIT("exit")` - `String stderr` The standard error output that was captured. - `String stdout` The standard output that was captured. - `Optional createdBy` The identifier of the actor that created the item. - `Status status` The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `JsonValue; type "shell_call_output"constant` The type of the shell call output. Always `shell_call_output`. - `SHELL_CALL_OUTPUT("shell_call_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional createdBy` The identifier of the actor that created the item. - `class BetaResponseApplyPatchToolCall:` A tool call that applies file diffs by creating, deleting, or updating files. - `String id` The unique ID of the apply patch tool call. Populated when this item is returned via API. - `String callId` The unique ID of the apply patch tool call generated by the model. - `Operation operation` 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. - `String diff` Diff to apply. - `String path` Path of the file to create. - `JsonValue; type "create_file"constant` Create a new file with the provided diff. - `CREATE_FILE("create_file")` - `class DeleteFile:` Instruction describing how to delete a file via the apply_patch tool. - `String path` Path of the file to delete. - `JsonValue; type "delete_file"constant` Delete the specified file. - `DELETE_FILE("delete_file")` - `class UpdateFile:` Instruction describing how to update a file via the apply_patch tool. - `String diff` Diff to apply. - `String path` Path of the file to update. - `JsonValue; type "update_file"constant` Update an existing file with the provided diff. - `UPDATE_FILE("update_file")` - `Status status` The status of the apply patch tool call. One of `in_progress` or `completed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `JsonValue; type "apply_patch_call"constant` The type of the item. Always `apply_patch_call`. - `APPLY_PATCH_CALL("apply_patch_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional createdBy` The ID of the entity that created this tool call. - `class BetaResponseApplyPatchToolCallOutput:` The output emitted by an apply patch tool call. - `String id` The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `String callId` The unique ID of the apply patch tool call generated by the model. - `Status status` The status of the apply patch tool call output. One of `completed` or `failed`. - `COMPLETED("completed")` - `FAILED("failed")` - `JsonValue; type "apply_patch_call_output"constant` The type of the item. Always `apply_patch_call_output`. - `APPLY_PATCH_CALL_OUTPUT("apply_patch_call_output")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional createdBy` The ID of the entity that created this tool call output. - `Optional output` Optional textual output returned by the apply patch tool. - `McpCall` - `String id` The unique ID of the tool call. - `String arguments` A JSON string of the arguments passed to the tool. - `String name` The name of the tool that was run. - `String serverLabel` The label of the MCP server running the tool. - `JsonValue; type "mcp_call"constant` The type of the item. Always `mcp_call`. - `MCP_CALL("mcp_call")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional approvalRequestId` 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. - `Optional error` The error from the tool call, if any. - `Optional output` The output from the tool call. - `Optional status` The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `CALLING("calling")` - `FAILED("failed")` - `McpListTools` - `String id` The unique ID of the list. - `String serverLabel` The label of the MCP server. - `List tools` The tools available on the server. - `JsonValue inputSchema` The JSON schema describing the tool's input. - `String name` The name of the tool. - `Optional annotations` Additional annotations about the tool. - `Optional description` The description of the tool. - `JsonValue; type "mcp_list_tools"constant` The type of the item. Always `mcp_list_tools`. - `MCP_LIST_TOOLS("mcp_list_tools")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional error` Error message if the server could not list tools. - `McpApprovalRequest` - `String id` The unique ID of the approval request. - `String arguments` A JSON string of arguments for the tool. - `String name` The name of the tool to run. - `String serverLabel` The label of the MCP server making the request. - `JsonValue; type "mcp_approval_request"constant` The type of the item. Always `mcp_approval_request`. - `MCP_APPROVAL_REQUEST("mcp_approval_request")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `McpApprovalResponse` - `String id` The unique ID of the approval response - `String approvalRequestId` The ID of the approval request being answered. - `boolean approve` Whether the request was approved. - `JsonValue; type "mcp_approval_response"constant` The type of the item. Always `mcp_approval_response`. - `MCP_APPROVAL_RESPONSE("mcp_approval_response")` - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional reason` Optional reason for the decision. - `class BetaResponseCustomToolCall:` A call to a custom tool created by the model. - `String callId` An identifier used to map this custom tool call to a tool call output. - `String input` The input for the custom tool call generated by the model. - `String name` The name of the custom tool being called. - `JsonValue; type "custom_tool_call"constant` The type of the custom tool call. Always `custom_tool_call`. - `CUSTOM_TOOL_CALL("custom_tool_call")` - `Optional id` The unique ID of the custom tool call in the OpenAI platform. - `Optional agent` The agent that produced this item. - `String agentName` The canonical name of the agent that produced this item. - `Optional caller` The execution context that produced this tool call. - `JsonValue;` - `JsonValue; type "direct"constant` - `DIRECT("direct")` - `class Program:` - `String callerId` The call ID of the program item that produced this tool call. - `JsonValue; type "program"constant` - `PROGRAM("program")` - `Optional namespace` 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. - `String id` The unique ID of the custom tool call output item. - `Status status` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `IN_PROGRESS("in_progress")` - `COMPLETED("completed")` - `INCOMPLETE("incomplete")` - `Optional createdBy` The identifier of the actor that created the item. - `BetaResponseUsage usage` Token accounting for the compaction pass, including cached, reasoning, and total tokens. - `long inputTokens` The number of input tokens. - `InputTokensDetails inputTokensDetails` A detailed breakdown of the input tokens. - `long cacheWriteTokens` The number of input tokens that were written to the cache. - `long cachedTokens` The number of tokens that were retrieved from the cache. [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - `long outputTokens` The number of output tokens. - `OutputTokensDetails outputTokensDetails` A detailed breakdown of the output tokens. - `long reasoningTokens` The number of reasoning tokens. - `long totalTokens` The total number of tokens used. ### Example ```java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.responses.BetaCompactedResponse; import com.openai.models.beta.responses.ResponseCompactParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ResponseCompactParams params = ResponseCompactParams.builder() .model(ResponseCompactParams.Model.GPT_5_6_SOL) .build(); BetaCompactedResponse betaCompactedResponse = client.beta().responses().compact(params); } } ``` #### 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 } } ```