diff --git a/en/cli/resources/beta/index.md b/en/cli/resources/beta/index.md index 6fa30619..20b407cc 100644 --- a/en/cli/resources/beta/index.md +++ b/en/cli/resources/beta/index.md @@ -1,4277 +1,3954 @@ # Beta -# ChatKit +# Responses -## Domain Types +## Create a model response -### ChatKit Workflow +`$ openai beta:responses create` -- `chatkit_workflow: object { id, state_variables, tracing, version }` +**post** `/responses?beta=true` - Workflow metadata and state returned for the session. +Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or +[image](https://platform.openai.com/docs/guides/images) inputs to generate [text](https://platform.openai.com/docs/guides/text) +or [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have the model call +your own [custom code](https://platform.openai.com/docs/guides/function-calling) or use built-in +[tools](https://platform.openai.com/docs/guides/tools) like [web search](https://platform.openai.com/docs/guides/tools-web-search) +or [file search](https://platform.openai.com/docs/guides/tools-file-search) to use your own data +as input for the model's response. - - `id: string` +### Parameters - Identifier of the workflow backing the session. +- `--background: optional boolean` - - `state_variables: map[string or boolean or number]` + Body param: Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. +- `--context-management: optional array of object { type, compact_threshold }` - - `union_member_0: string` + Body param: Context management configuration for this request. - - `union_member_1: boolean` +- `--conversation: optional string or BetaResponseConversationParam` - - `union_member_2: number` + Body param: The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - - `tracing: object { enabled }` +- `--include: optional array of BetaResponseIncludable` - Tracing settings applied to the workflow. + Body param: Specify additional output data to include in the model response. Currently supported values are: - - `enabled: boolean` + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - Indicates whether tracing is enabled. +- `--input: optional string or BetaResponseInput` - - `version: string` + Body param: Text, image, or file inputs to the model, used to generate a response. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + Learn more: -# Sessions + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) -## Cancel chat session +- `--instructions: optional string` -`$ openai beta:chatkit:sessions cancel` + Body param: A system (or developer) message inserted into the model's context. -**post** `/chatkit/sessions/{session_id}/cancel` + When using 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. -Cancel chat session +- `--max-output-tokens: optional number` -### Parameters + Body param: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). -- `--session-id: string` +- `--max-tool-calls: optional number` - Unique identifier for the ChatKit session to cancel. + Body param: The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. -### Returns +- `--metadata: optional map[string]` -- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }` + Body param: 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. - Represents a ChatKit session and its resolved configuration. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `id: string` +- `--model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - Identifier for the ChatKit session. + Body param: Model ID used to generate the response, like `gpt-4o` 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. - - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }` +- `--moderation: optional object { model, policy }` - Resolved ChatKit feature configuration for the session. + Body param: Configuration for running moderation on the input and output of this response. - - `automatic_thread_titling: object { enabled }` +- `--multi-agent: optional object { enabled, max_concurrent_subagents }` - Automatic thread titling preferences. + Body param: Configuration for server-hosted multi-agent execution. - - `enabled: boolean` +- `--parallel-tool-calls: optional boolean` - Whether automatic thread titling is enabled. + Body param: Whether to allow the model to run tool calls in parallel. - - `file_upload: object { enabled, max_file_size, max_files }` +- `--previous-response-id: optional string` - Upload settings for the session. + Body param: 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`. - - `enabled: boolean` +- `--prompt: optional object { id, variables, version }` - Indicates if uploads are enabled for the session. + Body param: Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `max_file_size: number` +- `--prompt-cache-key: optional string` - Maximum upload size in megabytes. + Body param: Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `max_files: number` +- `--prompt-cache-options: optional object { mode, ttl }` - Maximum number of uploads allowed during the session. + Body param: 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. - - `history: object { enabled, recent_threads }` +- `--prompt-cache-retention: optional "in_memory" or "24h"` - History retention configuration. + Body param: Deprecated. Use `prompt_cache_options.ttl` instead. - - `enabled: boolean` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - Indicates if chat history is persisted for the session. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `recent_threads: number` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. +- `--reasoning: optional object { context, effort, generate_summary, 2 more }` - - `client_secret: string` + Body param: **gpt-5 and o-series models only** - Ephemeral client secret that authenticates session requests. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `expires_at: number` +- `--safety-identifier: optional string` - Unix timestamp (in seconds) for when the session expires. + Body param: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `max_requests_per_1_minute: number` +- `--service-tier: optional "auto" or "default" or "flex" or 2 more` - Convenience copy of the per-minute request limit. + Body param: Specifies the processing type used for serving the request. - - `object: "chatkit.session"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - Type discriminator that is always `chatkit.session`. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `rate_limits: object { max_requests_per_1_minute }` +- `--store: optional boolean` - Resolved rate limit values. + Body param: Whether to store the generated model response for later retrieval via + API. - - `max_requests_per_1_minute: number` +- `--stream-options: optional object { include_obfuscation }` - Maximum allowed requests per one-minute window. + Body param: Options for streaming responses. Only set this when you set `stream: true`. - - `status: "active" or "expired" or "cancelled"` +- `--temperature: optional number` - Current lifecycle state of the session. + Body param: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `"active"` +- `--text: optional object { format, verbosity }` - - `"expired"` + Body param: Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"cancelled"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `user: string` +- `--tool-choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - User identifier associated with the session. + Body param: How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `workflow: object { id, state_variables, tracing, version }` +- `--tool: optional array of BetaTool` - Workflow metadata for the session. + Body param: An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `id: string` + We support the following categories of tools: - Identifier of the workflow backing the session. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `state_variables: map[string or boolean or number]` +- `--top-logprobs: optional number` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + Body param: An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `union_member_0: string` +- `--top-p: optional number` - - `union_member_1: boolean` + Body param: An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `union_member_2: number` + We generally recommend altering this or `temperature` but not both. - - `tracing: object { enabled }` +- `--truncation: optional "auto" or "disabled"` - Tracing settings applied to the workflow. + Body param: The truncation strategy to use for the model response. - - `enabled: boolean` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - Indicates whether tracing is enabled. +- `--user: optional string` - - `version: string` + Body param: This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - Specific workflow version used for the session. Defaults to null when using the latest deployment. +- `--beta: optional array of "responses_multi_agent=v1"` -### Example + Header param: Optional beta features to enable for this request. -```cli -openai beta:chatkit:sessions cancel \ - --api-key 'My API Key' \ - --session-id cksess_123 -``` +### Returns -#### Response +- `beta_response: object { id, created_at, error, 31 more }` -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` + - `id: string` -## Create ChatKit session + Unique identifier for this Response. -`$ openai beta:chatkit:sessions create` + - `created_at: number` -**post** `/chatkit/sessions` + Unix timestamp (in seconds) of when this Response was created. -Create ChatKit session + - `error: object { code, message }` -### Parameters + An error object returned when the model fails to generate a Response. -- `--user: string` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. + The error code for the response. -- `--workflow: object { id, state_variables, tracing, version }` + - `"server_error"` - Workflow that powers the session. + - `"rate_limit_exceeded"` -- `--chatkit-configuration: optional object { automatic_thread_titling, file_upload, history }` + - `"invalid_prompt"` - Optional overrides for ChatKit runtime configuration features + - `"bio_policy"` -- `--expires-after: optional object { anchor, seconds }` + - `"vector_store_timeout"` - Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. + - `"invalid_image"` -- `--rate-limits: optional object { max_requests_per_1_minute }` + - `"invalid_image_format"` - Optional override for per-minute request limits. When omitted, defaults to 10. + - `"invalid_base64_image"` -### Returns + - `"invalid_image_url"` -- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }` + - `"image_too_large"` - Represents a ChatKit session and its resolved configuration. + - `"image_too_small"` - - `id: string` + - `"image_parse_error"` - Identifier for the ChatKit session. + - `"image_content_policy_violation"` - - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }` + - `"invalid_image_mode"` - Resolved ChatKit feature configuration for the session. + - `"image_file_too_large"` - - `automatic_thread_titling: object { enabled }` + - `"unsupported_image_media_type"` - Automatic thread titling preferences. + - `"empty_image_file"` - - `enabled: boolean` + - `"failed_to_download_image"` - Whether automatic thread titling is enabled. + - `"image_file_not_found"` - - `file_upload: object { enabled, max_file_size, max_files }` + - `message: string` - Upload settings for the session. + A human-readable description of the error. - - `enabled: boolean` + - `incomplete_details: object { reason }` - Indicates if uploads are enabled for the session. + Details about why the response is incomplete. - - `max_file_size: number` + - `reason: optional "max_output_tokens" or "content_filter"` - Maximum upload size in megabytes. + The reason why the response is incomplete. - - `max_files: number` + - `"max_output_tokens"` - Maximum number of uploads allowed during the session. + - `"content_filter"` - - `history: object { enabled, recent_threads }` + - `instructions: string or array of BetaResponseInputItem` - History retention configuration. + A system (or developer) message inserted into the model's context. - - `enabled: boolean` + When using 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. - Indicates if chat history is persisted for the session. + - `union_member_0: string` - - `recent_threads: number` + A text input to the model, equivalent to a text input with the + `developer` role. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `Input item list: array of BetaResponseInputItem` - - `client_secret: string` + A list of one or many input items to the model, containing + different content types. - Ephemeral client secret that authenticates session requests. + - `beta_easy_input_message: object { content, role, phase, type }` - - `expires_at: number` + 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. - Unix timestamp (in seconds) for when the session expires. + - `content: string or BetaResponseInputMessageContentList` - - `max_requests_per_1_minute: number` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - Convenience copy of the per-minute request limit. + - `Text input: string` - - `object: "chatkit.session"` + A text input to the model. - Type discriminator that is always `chatkit.session`. + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - `rate_limits: object { max_requests_per_1_minute }` + A list of one or many input items to the model, containing different content + types. - Resolved rate limit values. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `max_requests_per_1_minute: number` + A text input to the model. - Maximum allowed requests per one-minute window. + - `text: string` - - `status: "active" or "expired" or "cancelled"` + The text input to the model. - Current lifecycle state of the session. + - `type: "input_text"` - - `"active"` + The type of the input item. Always `input_text`. - - `"expired"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"cancelled"` + 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. - - `user: string` + - `mode: "explicit"` - User identifier associated with the session. + The breakpoint mode. Always `explicit`. - - `workflow: object { id, state_variables, tracing, version }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - Workflow metadata for the session. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `id: string` + - `detail: "low" or "high" or "auto" or "original"` - Identifier of the workflow backing the session. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `state_variables: map[string or boolean or number]` + - `"low"` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `"high"` - - `union_member_0: string` + - `"auto"` - - `union_member_1: boolean` + - `"original"` - - `union_member_2: number` + - `type: "input_image"` - - `tracing: object { enabled }` + The type of the input item. Always `input_image`. - Tracing settings applied to the workflow. + - `file_id: optional string` - - `enabled: boolean` + The ID of the file to be sent to the model. - Indicates whether tracing is enabled. + - `image_url: optional string` - - `version: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `prompt_cache_breakpoint: optional object { mode }` -### Example + 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. -```cli -openai beta:chatkit:sessions create \ - --api-key 'My API Key' \ - --user x \ - --workflow '{id: id}' -``` + - `mode: "explicit"` -#### Response + The breakpoint mode. Always `explicit`. -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` -# Threads + A file input to the model. -## List ChatKit thread items + - `type: "input_file"` -`$ openai beta:chatkit:threads list-items` + The type of the input item. Always `input_file`. -**get** `/chatkit/threads/{thread_id}/items` + - `detail: optional "auto" or "low" or "high"` -List ChatKit thread items + 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`. -### Parameters + - `"auto"` -- `--thread-id: string` + - `"low"` - Identifier of the ChatKit thread whose items are requested. + - `"high"` -- `--after: optional string` + - `file_data: optional string` - List items created after this thread item ID. Defaults to null for the first page. + The content of the file to be sent to the model. -- `--before: optional string` + - `file_id: optional string` - List items created before this thread item ID. Defaults to null for the newest results. + The ID of the file to be sent to the model. -- `--limit: optional number` + - `file_url: optional string` - Maximum number of thread items to return. Defaults to 20. + The URL of the file to be sent to the model. -- `--order: optional "asc" or "desc"` + - `filename: optional string` - Sort order for results by creation time. Defaults to `desc`. + The name of the file to be sent to the model. -### Returns + - `prompt_cache_breakpoint: optional object { mode }` -- `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }` + 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. - A paginated list of thread items rendered for the ChatKit API. + - `mode: "explicit"` - - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` + The breakpoint mode. Always `explicit`. - A list of items + - `role: "user" or "assistant" or "system" or "developer"` - - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - User-authored messages within a thread. + - `"user"` - - `id: string` + - `"assistant"` - Identifier of the thread item. + - `"system"` - - `attachments: array of ChatKitAttachment` + - `"developer"` - Attachments associated with the user message. Defaults to an empty list. + - `phase: optional "commentary" or "final_answer"` - - `id: string` + 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. - Identifier for the attachment. + - `"commentary"` - - `mime_type: string` + - `"final_answer"` - MIME type of the attachment. + - `type: optional "message"` - - `name: string` + The type of the message input. Always `message`. - Original display name for the attachment. + - `"message"` - - `preview_url: string` + - `message: object { content, role, agent, 2 more }` - Preview URL for rendering the attachment inline. + 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. - - `type: "image" or "file"` + - `content: array of BetaResponseInputContent` - Attachment discriminator. + A list of one or many input items to the model, containing different content + types. - - `"image"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"file"` + A text input to the model. - - `content: array of object { text, type } or object { text, type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - Ordered content elements supplied by the user. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `input_text: object { text, type }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - Text block that a user contributed to the thread. + A file input to the model. - - `text: string` + - `role: "user" or "system" or "developer"` - Plain-text content supplied by the user. + The role of the message input. One of `user`, `system`, or `developer`. - - `type: "input_text"` + - `"user"` - Type discriminator that is always `input_text`. + - `"system"` - - `quoted_text: object { text, type }` + - `"developer"` - Quoted snippet that the user referenced in their message. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - Quoted text content. + - `agent_name: string` - - `type: "quoted_text"` + The canonical name of the agent that produced this item. - Type discriminator that is always `quoted_text`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `created_at: number` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Unix timestamp (in seconds) for when the item was created. + - `"in_progress"` - - `inference_options: object { model, tool_choice }` + - `"completed"` - Inference overrides applied to the message. Defaults to null when unset. + - `"incomplete"` - - `model: string` + - `type: optional "message"` - Model name that generated the response. Defaults to null when using the session default. + The type of the message input. Always set to `message`. - - `tool_choice: object { id }` + - `"message"` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. - `id: string` - Identifier of the requested tool. + The unique ID of the output message. - - `object: "chatkit.thread_item"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Type discriminator that is always `chatkit.thread_item`. + The content of the output message. - - `thread_id: string` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - Identifier of the parent thread. + A text output from the model. - - `type: "chatkit.user_message"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` + The annotations of the text output. - Assistant-authored message within a thread. + - `file_citation: object { file_id, filename, index, type }` - - `id: string` + A citation to a file. - Identifier of the thread item. + - `file_id: string` - - `content: array of ChatKitResponseOutputText` + The ID of the file. - Ordered assistant response segments. + - `filename: string` - - `annotations: array of object { source, type } or object { source, type }` + The filename of the file cited. - Ordered list of annotations attached to the response text. + - `index: number` - - `file: object { source, type }` + The index of the file in the list of files. - Annotation that references an uploaded file. + - `type: "file_citation"` - - `source: object { filename, type }` + The type of the file citation. Always `file_citation`. - File attachment referenced by the annotation. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `filename: string` + A citation for a web resource used to generate a model response. - Filename referenced by the annotation. + - `end_index: number` - - `type: "file"` + The index of the last character of the URL citation in the message. - Type discriminator that is always `file`. + - `start_index: number` - - `type: "file"` + The index of the first character of the URL citation in the message. - Type discriminator that is always `file` for this annotation. + - `title: string` - - `url: object { source, type }` + The title of the web resource. - Annotation that references a URL. + - `type: "url_citation"` - - `source: object { type, url }` + The type of the URL citation. Always `url_citation`. - URL referenced by the annotation. + - `url: string` - - `type: "url"` + The URL of the web resource. - Type discriminator that is always `url`. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `url: string` + A citation for a container file used to generate a model response. - URL referenced by the annotation. + - `container_id: string` - - `type: "url"` + The ID of the container file. - Type discriminator that is always `url` for this annotation. + - `end_index: number` - - `text: string` + The index of the last character of the container file citation in the message. - Assistant generated text. + - `file_id: string` - - `type: "output_text"` + The ID of the file. - Type discriminator that is always `output_text`. + - `filename: string` - - `created_at: number` + The filename of the container file cited. - Unix timestamp (in seconds) for when the item was created. + - `start_index: number` - - `object: "chatkit.thread_item"` + The index of the first character of the container file citation in the message. - Type discriminator that is always `chatkit.thread_item`. + - `type: "container_file_citation"` - - `thread_id: string` + The type of the container file citation. Always `container_file_citation`. - Identifier of the parent thread. + - `file_path: object { file_id, index, type }` - - `type: "chatkit.assistant_message"` + A path to a file. - Type discriminator that is always `chatkit.assistant_message`. + - `file_id: string` - - `chatkit_widget_item: object { id, created_at, object, 3 more }` + The ID of the file. - Thread item that renders a widget payload. + - `index: number` - - `id: string` + The index of the file in the list of files. - Identifier of the thread item. + - `type: "file_path"` - - `created_at: number` + The type of the file path. Always `file_path`. - Unix timestamp (in seconds) for when the item was created. + - `text: string` - - `object: "chatkit.thread_item"` + The text output from the model. - Type discriminator that is always `chatkit.thread_item`. + - `type: "output_text"` - - `thread_id: string` + The type of the output text. Always `output_text`. - Identifier of the parent thread. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "chatkit.widget"` + - `token: string` - Type discriminator that is always `chatkit.widget`. + - `bytes: array of number` - - `widget: string` + - `logprob: number` - Serialized widget payload rendered in the UI. + - `top_logprobs: array of object { token, bytes, logprob }` - - `chatkit.client_tool_call: object { id, arguments, call_id, 7 more }` + - `token: string` - Record of a client side tool invocation initiated by the assistant. + - `bytes: array of number` - - `id: string` + - `logprob: number` - Identifier of the thread item. + - `beta_response_output_refusal: object { refusal, type }` - - `arguments: string` + A refusal from the model. - JSON-encoded arguments that were sent to the tool. + - `refusal: string` - - `call_id: string` + The refusal explanation from the model. - Identifier for the client tool call. + - `type: "refusal"` - - `created_at: number` + The type of the refusal. Always `refusal`. - Unix timestamp (in seconds) for when the item was created. + - `role: "assistant"` - - `name: string` + The role of the output message. Always `assistant`. - Tool name that was invoked. + - `status: "in_progress" or "completed" or "incomplete"` - - `object: "chatkit.thread_item"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Type discriminator that is always `chatkit.thread_item`. + - `"in_progress"` - - `output: string` + - `"completed"` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `"incomplete"` - - `status: "in_progress" or "completed"` + - `type: "message"` - Execution status for the tool call. + The type of the output message. Always `message`. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `thread_id: string` + - `agent_name: string` - Identifier of the parent thread. + The canonical name of the agent that produced this item. - - `type: "chatkit.client_tool_call"` + - `phase: optional "commentary" or "final_answer"` - Type discriminator that is always `chatkit.client_tool_call`. + 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. - - `chatkit.task: object { id, created_at, heading, 5 more }` + - `"commentary"` - Task emitted by the workflow to show progress and status updates. + - `"final_answer"` + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` - Identifier of the thread item. + The unique ID of the file search tool call. - - `created_at: number` + - `queries: array of string` - Unix timestamp (in seconds) for when the item was created. + The queries used to search for files. - - `heading: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Optional heading for the task. Defaults to null when not provided. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `object: "chatkit.thread_item"` + - `"in_progress"` - Type discriminator that is always `chatkit.thread_item`. + - `"searching"` - - `summary: string` + - `"completed"` - Optional summary that describes the task. Defaults to null when omitted. + - `"incomplete"` - - `task_type: "custom" or "thought"` + - `"failed"` - Subtype for the task. + - `type: "file_search_call"` - - `"custom"` + The type of the file search tool call. Always `file_search_call`. - - `"thought"` + - `agent: optional object { agent_name }` - - `thread_id: string` + The agent that produced this item. - Identifier of the parent thread. + - `agent_name: string` - - `type: "chatkit.task"` + The canonical name of the agent that produced this item. - Type discriminator that is always `chatkit.task`. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `chatkit.task_group: object { id, created_at, object, 3 more }` + The results of the file search tool call. - Collection of workflow tasks grouped together in the thread. + - `attributes: optional map[string or number or boolean]` - - `id: string` + 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. - Identifier of the thread item. + - `union_member_0: string` - - `created_at: number` + - `union_member_1: number` - Unix timestamp (in seconds) for when the item was created. + - `union_member_2: boolean` - - `object: "chatkit.thread_item"` + - `file_id: optional string` - Type discriminator that is always `chatkit.thread_item`. + The unique ID of the file. - - `tasks: array of object { heading, summary, type }` + - `filename: optional string` - Tasks included in the group. + The name of the file. - - `heading: string` + - `score: optional number` - Optional heading for the grouped task. Defaults to null when not provided. + The relevance score of the file - a value between 0 and 1. - - `summary: string` + - `text: optional string` - Optional summary that describes the grouped task. Defaults to null when omitted. + The text that was retrieved from the file. - - `type: "custom" or "thought"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - Subtype for the grouped task. + 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. - - `"custom"` + - `id: string` - - `"thought"` + The unique ID of the computer call. - - `thread_id: string` + - `call_id: string` - Identifier of the parent thread. + An identifier used when responding to the tool call with output. - - `type: "chatkit.task_group"` + - `pending_safety_checks: array of object { id, code, message }` - Type discriminator that is always `chatkit.task_group`. + The pending safety checks for the computer call. - - `first_id: string` + - `id: string` - The ID of the first item in the list. + The ID of the pending safety check. - - `has_more: boolean` + - `code: optional string` - Whether there are more items available. + The type of the pending safety check. - - `last_id: string` + - `message: optional string` - The ID of the last item in the list. + Details about the pending safety check. - - `object: "list"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of object returned, must be `list`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -### Example + - `"in_progress"` -```cli -openai beta:chatkit:threads list-items \ - --api-key 'My API Key' \ - --thread-id cthr_123 -``` + - `"completed"` -#### Response + - `"incomplete"` -```json -{ - "data": [ - { - "id": "id", - "attachments": [ - { - "id": "id", - "mime_type": "mime_type", - "name": "name", - "preview_url": "https://example.com", - "type": "image" - } - ], - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "created_at": 0, - "inference_options": { - "model": "model", - "tool_choice": { - "id": "id" - } - }, - "object": "chatkit.thread_item", - "thread_id": "thread_id", - "type": "chatkit.user_message" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `type: "computer_call"` -## Retrieve ChatKit thread + The type of the computer call. Always `computer_call`. -`$ openai beta:chatkit:threads retrieve` + - `"computer_call"` -**get** `/chatkit/threads/{thread_id}` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` -Retrieve ChatKit thread + A click action. -### Parameters + - `click: object { button, type, x, 2 more }` -- `--thread-id: string` + A click action. - Identifier of the ChatKit thread to retrieve. + - `button: "left" or "right" or "wheel" or 2 more` -### Returns + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. -- `chatkit_thread: object { id, created_at, object, 3 more }` + - `"left"` - Represents a ChatKit thread and its current status. + - `"right"` - - `id: string` + - `"wheel"` - Identifier of the thread. + - `"back"` - - `created_at: number` + - `"forward"` - Unix timestamp (in seconds) for when the thread was created. + - `type: "click"` - - `object: "chatkit.thread"` + Specifies the event type. For a click action, this property is always `click`. - Type discriminator that is always `chatkit.thread`. + - `x: number` - - `status: object { type } or object { reason, type } or object { reason, type }` + The x-coordinate where the click occurred. - Current status for the thread. Defaults to `active` for newly created threads. + - `y: number` - - `active: object { type }` + The y-coordinate where the click occurred. - Indicates that a thread is active. + - `keys: optional array of string` - - `locked: object { reason, type }` + The keys being held while clicking. - Indicates that a thread is locked and cannot accept new input. + - `double_click: object { keys, type, x, y }` - - `reason: string` + A double click action. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `keys: array of string` - - `type: "locked"` + The keys being held while double-clicking. - Status discriminator that is always `locked`. + - `type: "double_click"` - - `closed: object { reason, type }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Indicates that a thread has been closed. + - `x: number` - - `reason: string` + The x-coordinate where the double click occurred. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `y: number` - - `type: "closed"` + The y-coordinate where the double click occurred. - Status discriminator that is always `closed`. + - `drag: object { path, type, keys }` - - `title: string` + A drag action. - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `path: array of object { x, y }` - - `user: string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Free-form string that identifies your end user who owns the thread. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` -### Example + - `x: number` -```cli -openai beta:chatkit:threads retrieve \ - --api-key 'My API Key' \ - --thread-id cthr_123 -``` + The x-coordinate. -#### Response + - `y: number` -```json -{ - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" -} -``` + The y-coordinate. -## Delete ChatKit thread + - `type: "drag"` -`$ openai beta:chatkit:threads delete` + Specifies the event type. For a drag action, this property is always set to `drag`. -**delete** `/chatkit/threads/{thread_id}` + - `keys: optional array of string` -Delete ChatKit thread + The keys being held while dragging the mouse. -### Parameters + - `keypress: object { keys, type }` -- `--thread-id: string` + A collection of keypresses the model would like to perform. - Identifier of the ChatKit thread to delete. + - `keys: array of string` -### Returns + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. -- `BetaChatKitThreadDeleteResponse: object { id, deleted, object }` + - `type: "keypress"` - Confirmation payload returned after deleting a thread. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `id: string` + - `move: object { type, x, y, keys }` - Identifier of the deleted thread. + A mouse move action. - - `deleted: boolean` + - `type: "move"` - Indicates that the thread has been deleted. + Specifies the event type. For a move action, this property is always set to `move`. - - `object: "chatkit.thread.deleted"` + - `x: number` - Type discriminator that is always `chatkit.thread.deleted`. + The x-coordinate to move to. -### Example + - `y: number` -```cli -openai beta:chatkit:threads delete \ - --api-key 'My API Key' \ - --thread-id cthr_123 -``` + The y-coordinate to move to. -#### Response + - `keys: optional array of string` -```json -{ - "id": "id", - "deleted": true, - "object": "chatkit.thread.deleted" -} -``` + The keys being held while moving the mouse. -## List ChatKit threads + - `screenshot: object { type }` -`$ openai beta:chatkit:threads list` + A screenshot action. -**get** `/chatkit/threads` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` -List ChatKit threads + A scroll action. -### Parameters + - `scroll_x: number` -- `--after: optional string` + The horizontal scroll distance. - List items created after this thread item ID. Defaults to null for the first page. + - `scroll_y: number` -- `--before: optional string` + The vertical scroll distance. - List items created before this thread item ID. Defaults to null for the newest results. + - `type: "scroll"` -- `--limit: optional number` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Maximum number of thread items to return. Defaults to 20. + - `x: number` -- `--order: optional "asc" or "desc"` + The x-coordinate where the scroll occurred. - Sort order for results by creation time. Defaults to `desc`. + - `y: number` -- `--user: optional string` + The y-coordinate where the scroll occurred. - Filter threads that belong to this user identifier. Defaults to null to return all users. + - `keys: optional array of string` -### Returns + The keys being held while scrolling. -- `Threads: object { data, first_id, has_more, 2 more }` + - `type: object { text, type }` - A paginated list of ChatKit threads. + An action to type in text. - - `data: array of ChatKitThread` + - `text: string` - A list of items + The text to type. - - `id: string` + - `type: "type"` - Identifier of the thread. + Specifies the event type. For a type action, this property is always set to `type`. - - `created_at: number` + - `wait: object { type }` - Unix timestamp (in seconds) for when the thread was created. + A wait action. - - `object: "chatkit.thread"` + - `actions: optional array of BetaComputerAction` - Type discriminator that is always `chatkit.thread`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `status: object { type } or object { reason, type } or object { reason, type }` + - `click: object { button, type, x, 2 more }` - Current status for the thread. Defaults to `active` for newly created threads. + A click action. - - `active: object { type }` + - `double_click: object { keys, type, x, y }` - Indicates that a thread is active. + A double click action. - - `locked: object { reason, type }` + - `drag: object { path, type, keys }` - Indicates that a thread is locked and cannot accept new input. + A drag action. - - `reason: string` + - `keypress: object { keys, type }` - Reason that the thread was locked. Defaults to null when no reason is recorded. + A collection of keypresses the model would like to perform. - - `type: "locked"` + - `move: object { type, x, y, keys }` - Status discriminator that is always `locked`. + A mouse move action. - - `closed: object { reason, type }` + - `screenshot: object { type }` - Indicates that a thread has been closed. + A screenshot action. - - `reason: string` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - Reason that the thread was closed. Defaults to null when no reason is recorded. + A scroll action. - - `type: "closed"` + - `type: object { text, type }` - Status discriminator that is always `closed`. + An action to type in text. - - `title: string` + - `wait: object { type }` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + A wait action. - - `user: string` + - `agent: optional object { agent_name }` - Free-form string that identifies your end user who owns the thread. + The agent that produced this item. - - `first_id: string` + - `agent_name: string` - The ID of the first item in the list. + The canonical name of the agent that produced this item. - - `has_more: boolean` + - `computer_call_output: object { call_id, output, type, 4 more }` - Whether there are more items available. + The output of a computer tool call. - - `last_id: string` + - `call_id: string` - The ID of the last item in the list. + The ID of the computer tool call that produced the output. - - `object: "list"` + - `output: object { type, file_id, image_url }` - The type of object returned, must be `list`. + A computer screenshot image used with the computer use tool. -### Example + - `type: "computer_screenshot"` -```cli -openai beta:chatkit:threads list \ - --api-key 'My API Key' -``` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. -#### Response + - `file_id: optional string` -```json -{ - "data": [ - { - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + The identifier of an uploaded file that contains the screenshot. -## Domain Types + - `image_url: optional string` -### Chat Session + The URL of the screenshot image. -- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }` + - `type: "computer_call_output"` - Represents a ChatKit session and its resolved configuration. + The type of the computer tool call output. Always `computer_call_output`. - - `id: string` + - `id: optional string` - Identifier for the ChatKit session. + The ID of the computer tool call output. - - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Resolved ChatKit feature configuration for the session. + The safety checks reported by the API that have been acknowledged by the developer. - - `automatic_thread_titling: object { enabled }` + - `id: string` - Automatic thread titling preferences. + The ID of the pending safety check. - - `enabled: boolean` + - `code: optional string` - Whether automatic thread titling is enabled. + The type of the pending safety check. - - `file_upload: object { enabled, max_file_size, max_files }` + - `message: optional string` - Upload settings for the session. + Details about the pending safety check. - - `enabled: boolean` + - `agent: optional object { agent_name }` - Indicates if uploads are enabled for the session. + The agent that produced this item. - - `max_file_size: number` + - `agent_name: string` - Maximum upload size in megabytes. + The canonical name of the agent that produced this item. - - `max_files: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - Maximum number of uploads allowed during the session. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `history: object { enabled, recent_threads }` + - `"in_progress"` - History retention configuration. + - `"completed"` - - `enabled: boolean` + - `"incomplete"` - Indicates if chat history is persisted for the session. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `recent_threads: number` + 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. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `id: string` - - `client_secret: string` + The unique ID of the web search tool call. - Ephemeral client secret that authenticates session requests. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `expires_at: number` + 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). - Unix timestamp (in seconds) for when the session expires. + - `search: object { type, queries, query, sources }` - - `max_requests_per_1_minute: number` + Action type "search" - Performs a web search query. - Convenience copy of the per-minute request limit. + - `type: "search"` - - `object: "chatkit.session"` + The action type. - Type discriminator that is always `chatkit.session`. + - `queries: optional array of string` - - `rate_limits: object { max_requests_per_1_minute }` + The search queries. - Resolved rate limit values. + - `query: optional string` - - `max_requests_per_1_minute: number` + The search query. - Maximum allowed requests per one-minute window. + - `sources: optional array of object { type, url }` - - `status: "active" or "expired" or "cancelled"` + The sources used in the search. - Current lifecycle state of the session. + - `type: "url"` - - `"active"` + The type of source. Always `url`. - - `"expired"` + - `url: string` - - `"cancelled"` + The URL of the source. - - `user: string` + - `open_page: object { type, url }` - User identifier associated with the session. + Action type "open_page" - Opens a specific URL from search results. - - `workflow: object { id, state_variables, tracing, version }` + - `type: "open_page"` - Workflow metadata for the session. + The action type. - - `id: string` + - `url: optional string` - Identifier of the workflow backing the session. + The URL opened by the model. - - `state_variables: map[string or boolean or number]` + - `find_in_page: object { pattern, type, url }` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `union_member_0: string` + - `pattern: string` - - `union_member_1: boolean` + The pattern or text to search for within the page. - - `union_member_2: number` + - `type: "find_in_page"` - - `tracing: object { enabled }` + The action type. - Tracing settings applied to the workflow. + - `url: string` - - `enabled: boolean` + The URL of the page searched for the pattern. - Indicates whether tracing is enabled. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `version: string` + The status of the web search tool call. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `"in_progress"` -### Chat Session Automatic Thread Titling + - `"searching"` -- `chat_session_automatic_thread_titling: object { enabled }` + - `"completed"` - Automatic thread title preferences for the session. + - `"failed"` - - `enabled: boolean` + - `type: "web_search_call"` - Whether automatic thread titling is enabled. + The type of the web search tool call. Always `web_search_call`. -### Chat Session ChatKit Configuration + - `agent: optional object { agent_name }` -- `chat_session_chatkit_configuration: object { automatic_thread_titling, file_upload, history }` + The agent that produced this item. - ChatKit configuration for the session. + - `agent_name: string` - - `automatic_thread_titling: object { enabled }` + The canonical name of the agent that produced this item. - Automatic thread titling preferences. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `enabled: boolean` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Whether automatic thread titling is enabled. + - `arguments: string` - - `file_upload: object { enabled, max_file_size, max_files }` + A JSON string of the arguments to pass to the function. - Upload settings for the session. + - `call_id: string` - - `enabled: boolean` + The unique ID of the function tool call generated by the model. - Indicates if uploads are enabled for the session. + - `name: string` - - `max_file_size: number` + The name of the function to run. - Maximum upload size in megabytes. + - `type: "function_call"` - - `max_files: number` + The type of the function tool call. Always `function_call`. - Maximum number of uploads allowed during the session. + - `id: optional string` - - `history: object { enabled, recent_threads }` + The unique ID of the function tool call. - History retention configuration. + - `agent: optional object { agent_name }` - - `enabled: boolean` + The agent that produced this item. - Indicates if chat history is persisted for the session. + - `agent_name: string` - - `recent_threads: number` + The canonical name of the agent that produced this item. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `caller: optional object { type } or object { caller_id, type }` -### Chat Session ChatKit Configuration Param + The execution context that produced this tool call. -- `chat_session_chatkit_configuration_param: object { automatic_thread_titling, file_upload, history }` + - `direct: object { type }` - Optional per-session configuration settings for ChatKit behavior. + - `program: object { caller_id, type }` - - `automatic_thread_titling: optional object { enabled }` + - `caller_id: string` - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + The call ID of the program item that produced this tool call. - - `enabled: optional boolean` + - `type: "program"` - Enable automatic thread title generation. Defaults to true. + - `namespace: optional string` - - `file_upload: optional object { enabled, max_file_size, max_files }` + The namespace of the function to run. - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `enabled: optional boolean` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Enable uploads for this session. Defaults to false. + - `"in_progress"` - - `max_file_size: optional number` + - `"completed"` - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + - `"incomplete"` - - `max_files: optional number` + - `function_call_output: object { call_id, output, type, 4 more }` - Maximum number of files that can be uploaded to the session. Defaults to 10. + The output of a function tool call. - - `history: optional object { enabled, recent_threads }` + - `call_id: string` - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + The unique ID of the function tool call generated by the model. - - `enabled: optional boolean` + - `output: string or BetaResponseFunctionCallOutputItemList` - Enables chat users to access previous ChatKit threads. Defaults to true. + Text, image, or file output of the function tool call. - - `recent_threads: optional number` + - `union_member_0: string` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + A JSON string of the output of the function tool call. -### Chat Session Expires After Param + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` -- `chat_session_expires_after_param: object { anchor, seconds }` + An array of content outputs (text, image, file) for the function tool call. - Controls when the session expires relative to an anchor timestamp. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `anchor: "created_at"` + A text input to the model. - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `text: string` - - `seconds: number` + The text input to the model. - Number of seconds after the anchor when the session expires. + - `type: "input_text"` -### Chat Session File Upload + The type of the input item. Always `input_text`. -- `chat_session_file_upload: object { enabled, max_file_size, max_files }` + - `prompt_cache_breakpoint: optional object { mode }` - Upload permissions and limits applied to the session. + 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. - - `enabled: boolean` + - `mode: "explicit"` - Indicates if uploads are enabled for the session. + The breakpoint mode. Always `explicit`. - - `max_file_size: number` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - Maximum upload size in megabytes. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `max_files: number` + - `type: "input_image"` - Maximum number of uploads allowed during the session. + The type of the input item. Always `input_image`. -### Chat Session History + - `detail: optional "low" or "high" or "auto" or "original"` -- `chat_session_history: object { enabled, recent_threads }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - History retention preferences returned for the session. + - `"low"` - - `enabled: boolean` + - `"high"` - Indicates if chat history is persisted for the session. + - `"auto"` - - `recent_threads: number` + - `"original"` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `file_id: optional string` -### Chat Session Rate Limits + The ID of the file to be sent to the model. -- `chat_session_rate_limits: object { max_requests_per_1_minute }` + - `image_url: optional string` - Active per-minute request limit for the session. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `max_requests_per_1_minute: number` + - `prompt_cache_breakpoint: optional object { mode }` - Maximum allowed requests per one-minute window. + 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. -### Chat Session Rate Limits Param + - `mode: "explicit"` -- `chat_session_rate_limits_param: object { max_requests_per_1_minute }` + The breakpoint mode. Always `explicit`. - Controls request rate limits for the session. + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `max_requests_per_1_minute: optional number` + A file input to the model. - Maximum number of requests allowed per minute for the session. Defaults to 10. + - `type: "input_file"` -### Chat Session Status + The type of the input item. Always `input_file`. -- `chat_session_status: "active" or "expired" or "cancelled"` + - `detail: optional "auto" or "low" or "high"` - - `"active"` + 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`. - - `"expired"` + - `"auto"` - - `"cancelled"` + - `"low"` -### Chat Session Workflow Param + - `"high"` -- `chat_session_workflow_param: object { id, state_variables, tracing, version }` + - `file_data: optional string` - Workflow reference and overrides applied to the chat session. + The base64-encoded data of the file to be sent to the model. - - `id: string` + - `file_id: optional string` - Identifier for the workflow invoked by the session. + The ID of the file to be sent to the model. - - `state_variables: optional map[string or boolean or number]` + - `file_url: optional string` - State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. + The URL of the file to be sent to the model. - - `union_member_0: string` + - `filename: optional string` - - `union_member_1: boolean` + The name of the file to be sent to the model. - - `union_member_2: number` + - `prompt_cache_breakpoint: optional object { mode }` - - `tracing: optional object { enabled }` + 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. - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + - `mode: "explicit"` - - `enabled: optional boolean` + The breakpoint mode. Always `explicit`. - Whether tracing is enabled during the session. Defaults to true. + - `type: "function_call_output"` - - `version: optional string` + The type of the function tool call output. Always `function_call_output`. - Specific workflow version to run. Defaults to the latest deployed version. + - `id: optional string` -### ChatKit Attachment + The unique ID of the function tool call output. Populated when this item is returned via API. -- `chatkit_attachment: object { id, mime_type, name, 2 more }` + - `agent: optional object { agent_name }` - Attachment metadata included on thread items. + The agent that produced this item. - - `id: string` + - `agent_name: string` - Identifier for the attachment. + The canonical name of the agent that produced this item. - - `mime_type: string` + - `caller: optional object { type } or object { caller_id, type }` - MIME type of the attachment. + The execution context that produced this tool call. - - `name: string` + - `direct: object { type }` - Original display name for the attachment. + - `program: object { caller_id, type }` - - `preview_url: string` + - `caller_id: string` - Preview URL for rendering the attachment inline. + The call ID of the program item that produced this tool call. - - `type: "image" or "file"` + - `type: "program"` - Attachment discriminator. + The caller type. Always `program`. - - `"image"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"file"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. -### ChatKit Response Output Text + - `"in_progress"` -- `chatkit_response_output_text: object { annotations, text, type }` + - `"completed"` - Assistant response text accompanied by optional annotations. + - `"incomplete"` - - `annotations: array of object { source, type } or object { source, type }` + - `agent_message: object { author, content, recipient, 3 more }` - Ordered list of annotations attached to the response text. + A message routed between agents. - - `file: object { source, type }` + - `author: string` - Annotation that references an uploaded file. + The sending agent identity. - - `source: object { filename, type }` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - File attachment referenced by the annotation. + Plaintext, image, or encrypted content sent between agents. - - `filename: string` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - Filename referenced by the annotation. + A text input to the model. - - `type: "file"` + - `text: string` - Type discriminator that is always `file`. + The text input to the model. - - `type: "file"` + - `type: "input_text"` - Type discriminator that is always `file` for this annotation. + The type of the input item. Always `input_text`. - - `url: object { source, type }` + - `prompt_cache_breakpoint: optional object { mode }` - Annotation that references a URL. + 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. - - `source: object { type, url }` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - URL referenced by the annotation. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `type: "url"` + - `type: "input_image"` - Type discriminator that is always `url`. + The type of the input item. Always `input_image`. - - `url: string` + - `detail: optional "low" or "high" or "auto" or "original"` - URL referenced by the annotation. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "url"` + - `file_id: optional string` - Type discriminator that is always `url` for this annotation. + The ID of the file to be sent to the model. - - `text: string` + - `image_url: optional string` - Assistant generated text. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: "output_text"` + - `prompt_cache_breakpoint: optional object { mode }` - Type discriminator that is always `output_text`. + 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. -### ChatKit Thread + - `encrypted_content: object { encrypted_content, type }` -- `chatkit_thread: object { id, created_at, object, 3 more }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - Represents a ChatKit thread and its current status. + - `encrypted_content: string` - - `id: string` + Opaque encrypted content. - Identifier of the thread. + - `type: "encrypted_content"` - - `created_at: number` + The type of the input item. Always `encrypted_content`. - Unix timestamp (in seconds) for when the thread was created. + - `recipient: string` - - `object: "chatkit.thread"` + The destination agent identity. - Type discriminator that is always `chatkit.thread`. + - `type: "agent_message"` - - `status: object { type } or object { reason, type } or object { reason, type }` + The item type. Always `agent_message`. - Current status for the thread. Defaults to `active` for newly created threads. + - `id: optional string` - - `active: object { type }` + The unique ID of this agent message item. - Indicates that a thread is active. + - `agent: optional object { agent_name }` - - `locked: object { reason, type }` + The agent that produced this item. - Indicates that a thread is locked and cannot accept new input. + - `agent_name: string` - - `reason: string` + The canonical name of the agent that produced this item. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - `type: "locked"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Status discriminator that is always `locked`. + The multi-agent action that was executed. - - `closed: object { reason, type }` + - `"spawn_agent"` - Indicates that a thread has been closed. + - `"interrupt_agent"` - - `reason: string` + - `"list_agents"` - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `"send_message"` - - `type: "closed"` + - `"followup_task"` - Status discriminator that is always `closed`. + - `"wait_agent"` - - `title: string` + - `arguments: string` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + The action arguments as a JSON string. - - `user: string` + - `call_id: string` - Free-form string that identifies your end user who owns the thread. + The unique ID linking this call to its output. -### ChatKit Thread Assistant Message Item + - `type: "multi_agent_call"` -- `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` + The item type. Always `multi_agent_call`. - Assistant-authored message within a thread. + - `id: optional string` - - `id: string` + The unique ID of this multi-agent call. - Identifier of the thread item. + - `agent: optional object { agent_name }` - - `content: array of ChatKitResponseOutputText` + The agent that produced this item. - Ordered assistant response segments. + - `agent_name: string` - - `annotations: array of object { source, type } or object { source, type }` + The canonical name of the agent that produced this item. - Ordered list of annotations attached to the response text. + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - `file: object { source, type }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Annotation that references an uploaded file. + The multi-agent action that produced this result. - - `source: object { filename, type }` + - `"spawn_agent"` - File attachment referenced by the annotation. + - `"interrupt_agent"` - - `filename: string` + - `"list_agents"` - Filename referenced by the annotation. + - `"send_message"` - - `type: "file"` + - `"followup_task"` - Type discriminator that is always `file`. + - `"wait_agent"` - - `type: "file"` + - `call_id: string` - Type discriminator that is always `file` for this annotation. + The unique ID of the multi-agent call. - - `url: object { source, type }` + - `output: array of object { text, type, annotations }` - Annotation that references a URL. + Text output returned by the multi-agent action. - - `source: object { type, url }` + - `text: string` - URL referenced by the annotation. + The text content. - - `type: "url"` + - `type: "output_text"` - Type discriminator that is always `url`. + The content type. Always `output_text`. - - `url: string` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - URL referenced by the annotation. + Citations associated with the text content. - - `type: "url"` + - `union_member_0: array of object { file_id, filename, index, type }` - Type discriminator that is always `url` for this annotation. + - `file_id: string` - - `text: string` + The ID of the file. - Assistant generated text. + - `filename: string` - - `type: "output_text"` + The filename of the file cited. - Type discriminator that is always `output_text`. + - `index: number` - - `created_at: number` + The index of the file in the list of files. - Unix timestamp (in seconds) for when the item was created. + - `type: "file_citation"` - - `object: "chatkit.thread_item"` + The citation type. Always `file_citation`. - Type discriminator that is always `chatkit.thread_item`. + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - `thread_id: string` + - `end_index: number` - Identifier of the parent thread. + The index of the last character of the citation in the message. - - `type: "chatkit.assistant_message"` + - `start_index: number` - Type discriminator that is always `chatkit.assistant_message`. + The index of the first character of the citation in the message. -### ChatKit Thread Item List + - `title: string` -- `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }` + The title of the cited resource. - A paginated list of thread items rendered for the ChatKit API. + - `type: "url_citation"` - - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` + The citation type. Always `url_citation`. - A list of items + - `url: string` - - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` + The URL of the cited resource. - User-authored messages within a thread. + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `id: string` + - `container_id: string` - Identifier of the thread item. + The ID of the container. - - `attachments: array of ChatKitAttachment` + - `end_index: number` - Attachments associated with the user message. Defaults to an empty list. + The index of the last character of the citation in the message. - - `id: string` + - `file_id: string` - Identifier for the attachment. + The ID of the container file. - - `mime_type: string` + - `filename: string` - MIME type of the attachment. + The filename of the container file cited. - - `name: string` + - `start_index: number` - Original display name for the attachment. + The index of the first character of the citation in the message. - - `preview_url: string` + - `type: "container_file_citation"` - Preview URL for rendering the attachment inline. + The citation type. Always `container_file_citation`. - - `type: "image" or "file"` + - `type: "multi_agent_call_output"` - Attachment discriminator. + The item type. Always `multi_agent_call_output`. - - `"image"` + - `id: optional string` - - `"file"` + The unique ID of this multi-agent call output. - - `content: array of object { text, type } or object { text, type }` + - `agent: optional object { agent_name }` - Ordered content elements supplied by the user. + The agent that produced this item. - - `input_text: object { text, type }` + - `agent_name: string` - Text block that a user contributed to the thread. + The canonical name of the agent that produced this item. - - `text: string` + - `tool_search_call: object { arguments, type, id, 4 more }` - Plain-text content supplied by the user. + - `arguments: unknown` - - `type: "input_text"` + The arguments supplied to the tool search call. - Type discriminator that is always `input_text`. + - `type: "tool_search_call"` - - `quoted_text: object { text, type }` + The item type. Always `tool_search_call`. - Quoted snippet that the user referenced in their message. + - `id: optional string` - - `text: string` + The unique ID of this tool search call. - Quoted text content. + - `agent: optional object { agent_name }` - - `type: "quoted_text"` + The agent that produced this item. - Type discriminator that is always `quoted_text`. + - `agent_name: string` - - `created_at: number` + The canonical name of the agent that produced this item. - Unix timestamp (in seconds) for when the item was created. + - `call_id: optional string` - - `inference_options: object { model, tool_choice }` + The unique ID of the tool search call generated by the model. - Inference overrides applied to the message. Defaults to null when unset. + - `execution: optional "server" or "client"` - - `model: string` + Whether tool search was executed by the server or by the client. - Model name that generated the response. Defaults to null when using the session default. + - `"server"` - - `tool_choice: object { id }` + - `"client"` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the tool search call. - Identifier of the requested tool. + - `"in_progress"` - - `object: "chatkit.thread_item"` + - `"completed"` - Type discriminator that is always `chatkit.thread_item`. + - `"incomplete"` - - `thread_id: string` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - Identifier of the parent thread. + - `tools: array of BetaTool` - - `type: "chatkit.user_message"` + The loaded tool definitions returned by the tool search output. - - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - Assistant-authored message within a thread. + 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). - - `id: string` + - `name: string` - Identifier of the thread item. + The name of the function to call. - - `content: array of ChatKitResponseOutputText` + - `parameters: map[unknown]` - Ordered assistant response segments. + A JSON schema object describing the parameters of the function. - - `annotations: array of object { source, type } or object { source, type }` + - `strict: boolean` - Ordered list of annotations attached to the response text. + Whether strict parameter validation is enforced for this function tool. - - `file: object { source, type }` + - `type: "function"` - Annotation that references an uploaded file. + The type of the function tool. Always `function`. - - `source: object { filename, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - File attachment referenced by the annotation. + The tool invocation context(s). - - `filename: string` + - `"direct"` - Filename referenced by the annotation. + - `"programmatic"` - - `type: "file"` + - `defer_loading: optional boolean` - Type discriminator that is always `file`. + Whether this function is deferred and loaded via tool search. - - `type: "file"` + - `description: optional string` - Type discriminator that is always `file` for this annotation. + A description of the function. Used by the model to determine whether or not to call the function. - - `url: object { source, type }` + - `output_schema: optional map[unknown]` - Annotation that references a URL. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `source: object { type, url }` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - URL referenced by the annotation. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "url"` + - `type: "file_search"` - Type discriminator that is always `url`. + The type of the file search tool. Always `file_search`. - - `url: string` + - `vector_store_ids: array of string` - URL referenced by the annotation. + The IDs of the vector stores to search. - - `type: "url"` + - `filters: optional object { key, type, value } or object { filters, type }` - Type discriminator that is always `url` for this annotation. + A filter to apply. - - `text: string` + - `Comparison Filter: object { key, type, value }` - Assistant generated text. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "output_text"` + - `key: string` - Type discriminator that is always `output_text`. + The key to compare against the value. - - `created_at: number` + - `type: "eq" or "ne" or "gt" or 5 more` - Unix timestamp (in seconds) for when the item was created. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `object: "chatkit.thread_item"` + - `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 - Type discriminator that is always `chatkit.thread_item`. + - `"eq"` - - `thread_id: string` + - `"ne"` - Identifier of the parent thread. + - `"gt"` - - `type: "chatkit.assistant_message"` + - `"gte"` - Type discriminator that is always `chatkit.assistant_message`. + - `"lt"` - - `chatkit_widget_item: object { id, created_at, object, 3 more }` + - `"lte"` - Thread item that renders a widget payload. + - `"in"` - - `id: string` + - `"nin"` - Identifier of the thread item. + - `value: string or number or boolean or array of string or number` - - `created_at: number` + The value to compare against the attribute key; supports string, number, or boolean types. - Unix timestamp (in seconds) for when the item was created. + - `union_member_0: string` - - `object: "chatkit.thread_item"` + - `union_member_1: number` - Type discriminator that is always `chatkit.thread_item`. + - `union_member_2: boolean` - - `thread_id: string` + - `union_member_3: array of string or number` - Identifier of the parent thread. + - `union_member_0: string` - - `type: "chatkit.widget"` + - `union_member_1: number` - Type discriminator that is always `chatkit.widget`. + - `Compound Filter: object { filters, type }` - - `widget: string` + Combine multiple filters using `and` or `or`. - Serialized widget payload rendered in the UI. + - `filters: array of object { key, type, value } or unknown` - - `chatkit.client_tool_call: object { id, arguments, call_id, 7 more }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Record of a client side tool invocation initiated by the assistant. + - `Comparison Filter: object { key, type, value }` - - `id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Identifier of the thread item. + - `key: string` - - `arguments: string` + The key to compare against the value. - JSON-encoded arguments that were sent to the tool. + - `type: "eq" or "ne" or "gt" or 5 more` - - `call_id: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Identifier for the client tool call. + - `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 - - `created_at: number` + - `"eq"` - Unix timestamp (in seconds) for when the item was created. + - `"ne"` - - `name: string` + - `"gt"` - Tool name that was invoked. + - `"gte"` - - `object: "chatkit.thread_item"` + - `"lt"` - Type discriminator that is always `chatkit.thread_item`. + - `"lte"` - - `output: string` + - `"in"` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `"nin"` - - `status: "in_progress" or "completed"` + - `value: string or number or boolean or array of string or number` - Execution status for the tool call. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"in_progress"` + - `union_member_0: string` - - `"completed"` + - `union_member_1: number` - - `thread_id: string` - - Identifier of the parent thread. - - - `type: "chatkit.client_tool_call"` - - Type discriminator that is always `chatkit.client_tool_call`. + - `union_member_2: boolean` - - `chatkit.task: object { id, created_at, heading, 5 more }` + - `union_member_3: array of string or number` - Task emitted by the workflow to show progress and status updates. + - `union_member_0: string` - - `id: string` + - `union_member_1: number` - Identifier of the thread item. + - `union_member_1: unknown` - - `created_at: number` + - `type: "and" or "or"` - Unix timestamp (in seconds) for when the item was created. + Type of operation: `and` or `or`. - - `heading: string` + - `"and"` - Optional heading for the task. Defaults to null when not provided. + - `"or"` - - `object: "chatkit.thread_item"` + - `max_num_results: optional number` - Type discriminator that is always `chatkit.thread_item`. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `summary: string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - Optional summary that describes the task. Defaults to null when omitted. + Ranking options for search. - - `task_type: "custom" or "thought"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Subtype for the task. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"custom"` + - `embedding_weight: number` - - `"thought"` + The weight of the embedding in the reciprocal ranking fusion. - - `thread_id: string` + - `text_weight: number` - Identifier of the parent thread. + The weight of the text in the reciprocal ranking fusion. - - `type: "chatkit.task"` + - `ranker: optional "auto" or "default-2024-11-15"` - Type discriminator that is always `chatkit.task`. + The ranker to use for the file search. - - `chatkit.task_group: object { id, created_at, object, 3 more }` + - `"auto"` - Collection of workflow tasks grouped together in the thread. + - `"default-2024-11-15"` - - `id: string` + - `score_threshold: optional number` - Identifier of the thread item. + 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. - - `created_at: number` + - `beta_computer_tool: object { type }` - Unix timestamp (in seconds) for when the item was created. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `object: "chatkit.thread_item"` + - `type: "computer"` - Type discriminator that is always `chatkit.thread_item`. + The type of the computer tool. Always `computer`. - - `tasks: array of object { heading, summary, type }` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - Tasks included in the group. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `heading: string` + - `display_height: number` - Optional heading for the grouped task. Defaults to null when not provided. + The height of the computer display. - - `summary: string` + - `display_width: number` - Optional summary that describes the grouped task. Defaults to null when omitted. + The width of the computer display. - - `type: "custom" or "thought"` + - `environment: "windows" or "mac" or "linux" or 2 more` - Subtype for the grouped task. + The type of computer environment to control. - - `"custom"` + - `"windows"` - - `"thought"` + - `"mac"` - - `thread_id: string` + - `"linux"` - Identifier of the parent thread. + - `"ubuntu"` - - `type: "chatkit.task_group"` + - `"browser"` - Type discriminator that is always `chatkit.task_group`. + - `type: "computer_use_preview"` - - `first_id: string` + The type of the computer use tool. Always `computer_use_preview`. - The ID of the first item in the list. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `has_more: boolean` + 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). - Whether there are more items available. + - `type: "web_search" or "web_search_2025_08_26"` - - `last_id: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The ID of the last item in the list. + - `"web_search"` - - `object: "list"` + - `"web_search_2025_08_26"` - The type of object returned, must be `list`. + - `filters: optional object { allowed_domains }` -### ChatKit Thread User Message Item + Filters for the search. -- `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` + - `allowed_domains: optional array of string` - User-authored messages within a thread. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `id: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Identifier of the thread item. + - `search_context_size: optional "low" or "medium" or "high"` - - `attachments: array of ChatKitAttachment` + 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. - Attachments associated with the user message. Defaults to an empty list. + - `"low"` - - `id: string` + - `"medium"` - Identifier for the attachment. + - `"high"` - - `mime_type: string` + - `user_location: optional object { city, country, region, 2 more }` - MIME type of the attachment. + The approximate location of the user. - - `name: string` + - `city: optional string` - Original display name for the attachment. + Free text input for the city of the user, e.g. `San Francisco`. - - `preview_url: string` + - `country: optional string` - Preview URL for rendering the attachment inline. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: "image" or "file"` + - `region: optional string` - Attachment discriminator. + Free text input for the region of the user, e.g. `California`. - - `"image"` + - `timezone: optional string` - - `"file"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `content: array of object { text, type } or object { text, type }` + - `type: optional "approximate"` - Ordered content elements supplied by the user. + The type of location approximation. Always `approximate`. - - `input_text: object { text, type }` + - `"approximate"` - Text block that a user contributed to the thread. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `text: string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Plain-text content supplied by the user. + - `server_label: string` - - `type: "input_text"` + A label for this MCP server, used to identify it in tool calls. - Type discriminator that is always `input_text`. + - `type: "mcp"` - - `quoted_text: object { text, type }` + The type of the MCP tool. Always `mcp`. - Quoted snippet that the user referenced in their message. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `text: string` + The tool invocation context(s). - Quoted text content. + - `"direct"` - - `type: "quoted_text"` + - `"programmatic"` - Type discriminator that is always `quoted_text`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `created_at: number` + List of allowed tool names or a filter object. - Unix timestamp (in seconds) for when the item was created. + - `MCP allowed tools: array of string` - - `inference_options: object { model, tool_choice }` + A string array of allowed tool names - Inference overrides applied to the message. Defaults to null when unset. + - `MCP tool filter: object { read_only, tool_names }` - - `model: string` + A filter object to specify which tools are allowed. - Model name that generated the response. Defaults to null when using the session default. + - `read_only: optional boolean` - - `tool_choice: object { id }` + 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. - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `tool_names: optional array of string` - - `id: string` + List of allowed tool names. - Identifier of the requested tool. + - `authorization: optional string` - - `object: "chatkit.thread_item"` + 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. - Type discriminator that is always `chatkit.thread_item`. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `thread_id: string` + 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). - Identifier of the parent thread. + Currently supported `connector_id` values are: - - `type: "chatkit.user_message"` + - 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` -### ChatKit Widget Item + - `"connector_dropbox"` -- `chatkit_widget_item: object { id, created_at, object, 3 more }` + - `"connector_gmail"` - Thread item that renders a widget payload. + - `"connector_googlecalendar"` - - `id: string` + - `"connector_googledrive"` - Identifier of the thread item. + - `"connector_microsoftteams"` - - `created_at: number` + - `"connector_outlookcalendar"` - Unix timestamp (in seconds) for when the item was created. + - `"connector_outlookemail"` - - `object: "chatkit.thread_item"` + - `"connector_sharepoint"` - Type discriminator that is always `chatkit.thread_item`. + - `defer_loading: optional boolean` - - `thread_id: string` + Whether this MCP tool is deferred and discovered via tool search. - Identifier of the parent thread. + - `headers: optional map[string]` - - `type: "chatkit.widget"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Type discriminator that is always `chatkit.widget`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `widget: string` + Specify which of the MCP server's tools require approval. - Serialized widget payload rendered in the UI. + - `MCP tool approval filter: object { always, never }` -# Assistants + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. -## List assistants + - `always: optional object { read_only, tool_names }` -`$ openai beta:assistants list` + A filter object to specify which tools are allowed. -**get** `/assistants` + - `read_only: optional boolean` -List assistants + 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. -### Parameters + - `tool_names: optional array of string` -- `--after: optional string` + List of allowed tool names. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `never: optional object { read_only, tool_names }` -- `--before: optional string` + A filter object to specify which tools are allowed. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `read_only: optional boolean` -- `--limit: optional number` + 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. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `tool_names: optional array of string` -- `--order: optional "asc" or "desc"` + List of allowed tool names. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `MCP tool approval setting: "always" or "never"` -### Returns + 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. -- `ListAssistantsResponse: object { data, first_id, has_more, 2 more }` + - `"always"` - - `data: array of Assistant` + - `"never"` - - `id: string` + - `server_description: optional string` - The identifier, which can be referenced in API endpoints. + Optional description of the MCP server, used to provide more context. - - `created_at: number` + - `server_url: optional string` - The Unix timestamp (in seconds) for when the assistant was created. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `description: string` + - `tunnel_id: optional string` - The description of the assistant. The maximum length is 512 characters. + 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. - - `instructions: string` + - `code_interpreter: object { container, type, allowed_callers }` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + A tool that runs Python code to help generate a response to a prompt. - - `metadata: map[string]` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - 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. + 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. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `union_member_0: string` - - `model: string` + The container ID. - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `name: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The name of the assistant. The maximum length is 256 characters. + - `type: "auto"` - - `object: "assistant"` + Always `auto`. - The object type, which is always `assistant`. + - `file_ids: optional array of string` - - `tools: array of unknown` + An optional list of uploaded files to make available to your code. - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The memory limit for the code interpreter container. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"1g"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"4g"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"16g"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"64g"` - - `union_member_0: "auto"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - `auto` is the default value + Network access policy for the container. - - `response_format_text: object { type }` + - `beta_container_network_policy_disabled: object { type }` - Default response format. Used to generate text responses. + - `type: "disabled"` - - `type: "text"` + Disable outbound network access. Always `disabled`. - The type of response format being defined. Always `text`. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `response_format_json_object: object { type }` + - `allowed_domains: array of string` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + A list of allowed domains when type is `allowlist`. - - `type: "json_object"` + - `type: "allowlist"` - The type of response format being defined. Always `json_object`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `response_format_json_schema: object { json_schema, type }` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Optional domain-scoped secrets for allowlisted domains. - - `json_schema: object { name, description, schema, strict }` + - `domain: string` - Structured Outputs configuration options, including a JSON Schema. + The domain associated with the secret. - `name: string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The name of the secret to inject for the domain. - - `description: optional string` + - `value: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The secret value to inject for the domain. - - `schema: optional map[unknown]` + - `type: "code_interpreter"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the code interpreter tool. Always `code_interpreter`. - - `strict: optional boolean` + - `allowed_callers: optional array of "direct" or "programmatic"` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The tool invocation context(s). - - `type: "json_schema"` + - `"direct"` - The type of response format being defined. Always `json_schema`. + - `"programmatic"` - - `temperature: optional number` + - `programmatic_tool_calling: object { type }` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `image_generation: object { type, action, background, 9 more }` - - `tool_resources: optional object { code_interpreter, file_search }` + A tool that generates images using the GPT image models. - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `type: "image_generation"` - - `code_interpreter: optional object { file_ids }` + The type of the image generation tool. Always `image_generation`. - - `file_ids: optional array of string` + - `action: optional "generate" or "edit" or "auto"` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `file_search: optional object { vector_store_ids }` + - `"generate"` - - `vector_store_ids: optional array of string` + - `"edit"` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `"auto"` - - `top_p: optional number` + - `background: optional "transparent" or "opaque" or "auto"` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + 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. - We generally recommend altering this or temperature but not both. + `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. - - `first_id: string` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `has_more: boolean` + - `"transparent"` - - `last_id: string` + - `"opaque"` - - `object: string` + - `"auto"` -### Example + - `input_fidelity: optional "high" or "low"` -```cli -openai beta:assistants list \ - --api-key 'My API Key' -``` + 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`. -#### Response + - `"high"` -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 - } - ], - "first_id": "asst_abc123", - "has_more": false, - "last_id": "asst_abc456", - "object": "list" -} -``` + - `"low"` -## Create assistant + - `input_image_mask: optional object { file_id, image_url }` -`$ openai beta:assistants create` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). -**post** `/assistants` + - `file_id: optional string` -Create assistant + File ID for the mask image. -### Parameters + - `image_url: optional string` -- `--model: string or ChatModel` + Base64-encoded mask image. - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` -- `--description: optional string` + The image generation model to use. Default: `gpt-image-1`. - The description of the assistant. The maximum length is 512 characters. + - `"gpt-image-1"` -- `--instructions: optional string` + - `"gpt-image-1-mini"` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `"gpt-image-2"` -- `--metadata: optional map[string]` + - `"gpt-image-2-2026-04-21"` - 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. + - `"gpt-image-1.5"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"chatgpt-image-latest"` -- `--name: optional string` + - `moderation: optional "auto" or "low"` - The name of the assistant. The maximum length is 256 characters. + Moderation level for the generated image. Default: `auto`. -- `--reasoning-effort: optional "none" or "minimal" or "low" or 4 more` + - `"auto"` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"low"` -- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `output_compression: optional number` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + Compression level for the output image. Default: 100. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `output_format: optional "png" or "webp" or "jpeg"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"png"` -- `--temperature: optional number` + - `"webp"` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `"jpeg"` -- `--tool-resources: optional object { code_interpreter, file_search }` + - `partial_images: optional number` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. -- `--tool: optional array of unknown` + - `quality: optional "low" or "medium" or "high" or "auto"` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. -- `--top-p: optional number` + - `"low"` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `"medium"` - We generally recommend altering this or temperature but not both. + - `"high"` -### Returns + - `"auto"` -- `assistant: object { id, created_at, description, 10 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Represents an `assistant` that can call the model and use tools. + 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`. - - `id: string` + - `"1024x1024"` - The identifier, which can be referenced in API endpoints. + - `"1024x1536"` - - `created_at: number` + - `"1536x1024"` - The Unix timestamp (in seconds) for when the assistant was created. + - `"auto"` - - `description: string` + - `local_shell: object { type }` - The description of the assistant. The maximum length is 512 characters. + A tool that allows the model to execute shell commands in a local environment. - - `instructions: string` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + A tool that allows the model to execute shell commands. - - `metadata: map[string]` + - `type: "shell"` - 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. + The type of the shell tool. Always `shell`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `model: string` + The tool invocation context(s). - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `"direct"` - - `name: string` + - `"programmatic"` - The name of the assistant. The maximum length is 256 characters. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `object: "assistant"` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - The object type, which is always `assistant`. + - `type: "container_auto"` - - `tools: array of unknown` + Automatically creates a container for this request - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `file_ids: optional array of string` - - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + An optional list of uploaded files to make available to your code. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The memory limit for the container. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"1g"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"4g"` - - `union_member_0: "auto"` + - `"16g"` - `auto` is the default value + - `"64g"` - - `response_format_text: object { type }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Default response format. Used to generate text responses. + Network access policy for the container. - - `type: "text"` + - `beta_container_network_policy_disabled: object { type }` - The type of response format being defined. Always `text`. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `response_format_json_object: object { type }` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + An optional list of skills referenced by id or inline data. - - `type: "json_object"` + - `beta_skill_reference: object { skill_id, type, version }` - The type of response format being defined. Always `json_object`. + - `skill_id: string` - - `response_format_json_schema: object { json_schema, type }` + The ID of the referenced skill. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "skill_reference"` - - `json_schema: object { name, description, schema, strict }` + References a skill created with the /v1/skills endpoint. - Structured Outputs configuration options, including a JSON Schema. + - `version: optional string` - - `name: string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `beta_inline_skill: object { description, name, source, type }` - - `description: optional string` + - `description: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The description of the skill. - - `schema: optional map[unknown]` + - `name: string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The name of the skill. - - `strict: optional boolean` + - `source: object { data, media_type, type }` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + Inline skill payload - - `type: "json_schema"` + - `data: string` - The type of response format being defined. Always `json_schema`. + Base64-encoded skill zip bundle. - - `temperature: optional number` + - `media_type: "application/zip"` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + The media type of the inline skill payload. Must be `application/zip`. - - `tool_resources: optional object { code_interpreter, file_search }` + - `type: "base64"` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The type of the inline skill source. Must be `base64`. - - `code_interpreter: optional object { file_ids }` + - `type: "inline"` - - `file_ids: optional array of string` + Defines an inline skill for this request. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `beta_local_environment: object { type, skills }` - - `file_search: optional object { vector_store_ids }` + - `type: "local"` - - `vector_store_ids: optional array of string` + Use a local computer environment. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `skills: optional array of BetaLocalSkill` - - `top_p: optional number` + An optional list of skills. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `description: string` - We generally recommend altering this or temperature but not both. + The description of the skill. -### Example + - `name: string` -```cli -openai beta:assistants create \ - --api-key 'My API Key' \ - --model gpt-4o -``` + The name of the skill. -#### Response + - `path: string` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + The path to the directory containing the skill. -## Retrieve assistant + - `beta_container_reference: object { container_id, type }` -`$ openai beta:assistants retrieve` + - `container_id: string` -**get** `/assistants/{assistant_id}` + The ID of the referenced container. -Retrieve assistant + - `type: "container_reference"` -### Parameters + References a container created with the /v1/containers endpoint -- `--assistant-id: string` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The ID of the assistant to retrieve. + 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) -### Returns + - `name: string` -- `assistant: object { id, created_at, description, 10 more }` + The name of the custom tool, used to identify it in tool calls. - Represents an `assistant` that can call the model and use tools. + - `type: "custom"` - - `id: string` + The type of the custom tool. Always `custom`. - The identifier, which can be referenced in API endpoints. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `created_at: number` + The tool invocation context(s). - The Unix timestamp (in seconds) for when the assistant was created. + - `"direct"` - - `description: string` + - `"programmatic"` - The description of the assistant. The maximum length is 512 characters. + - `defer_loading: optional boolean` - - `instructions: string` + Whether this tool should be deferred and discovered via tool search. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `description: optional string` - - `metadata: map[string]` + Optional description of the custom tool, used to provide more context. - 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. + - `format: optional object { type } or object { definition, syntax, type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The input format for the custom tool. Default is unconstrained text. - - `model: string` + - `text: object { type }` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + Unconstrained free-form text. - - `name: string` + - `grammar: object { definition, syntax, type }` - The name of the assistant. The maximum length is 256 characters. + A grammar defined by the user. - - `object: "assistant"` + - `definition: string` - The object type, which is always `assistant`. + The grammar definition. - - `tools: array of unknown` + - `syntax: "lark" or "regex"` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"lark"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"regex"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "grammar"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Grammar format. Always `grammar`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `beta_namespace_tool: object { description, name, tools, type }` - - `union_member_0: "auto"` + Groups function/custom tools under a shared namespace. - `auto` is the default value + - `description: string` - - `response_format_text: object { type }` + A description of the namespace shown to the model. - Default response format. Used to generate text responses. + - `name: string` - - `type: "text"` + The namespace name used in tool calls (for example, `crm`). - The type of response format being defined. Always `text`. + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `response_format_json_object: object { type }` + The function/custom tools available inside this namespace. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `function: object { name, type, allowed_callers, 5 more }` - - `type: "json_object"` + - `name: string` - The type of response format being defined. Always `json_object`. + - `type: "function"` - - `response_format_json_schema: object { json_schema, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The tool invocation context(s). - - `json_schema: object { name, description, schema, strict }` + - `"direct"` - Structured Outputs configuration options, including a JSON Schema. + - `"programmatic"` - - `name: string` + - `defer_loading: optional boolean` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + Whether this function should be deferred and discovered via tool search. - `description: optional string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `output_schema: optional map[unknown]` - - `schema: optional map[unknown]` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `parameters: optional unknown` - `strict: optional boolean` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + 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. - - `type: "json_schema"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The type of response format being defined. Always `json_schema`. + 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) - - `temperature: optional number` + - `name: string` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + The name of the custom tool, used to identify it in tool calls. - - `tool_resources: optional object { code_interpreter, file_search }` + - `type: "custom"` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The type of the custom tool. Always `custom`. - - `code_interpreter: optional object { file_ids }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_ids: optional array of string` + The tool invocation context(s). - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `defer_loading: optional boolean` - - `file_search: optional object { vector_store_ids }` + Whether this tool should be deferred and discovered via tool search. - - `vector_store_ids: optional array of string` + - `description: optional string` - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + Optional description of the custom tool, used to provide more context. - - `top_p: optional number` + - `format: optional object { type } or object { definition, syntax, type }` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + The input format for the custom tool. Default is unconstrained text. - We generally recommend altering this or temperature but not both. + - `type: "namespace"` -### Example + The type of the tool. Always `namespace`. -```cli -openai beta:assistants retrieve \ - --api-key 'My API Key' \ - --assistant-id assistant_id -``` + - `beta_tool_search_tool: object { type, description, execution, parameters }` -#### Response + Hosted or BYOT tool search configuration for deferred tools. -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `type: "tool_search"` -## Modify assistant + The type of the tool. Always `tool_search`. -`$ openai beta:assistants update` + - `description: optional string` -**post** `/assistants/{assistant_id}` + Description shown to the model for a client-executed tool search tool. -Modify assistant + - `execution: optional "server" or "client"` -### Parameters + Whether tool search is executed by the server or by the client. -- `--assistant-id: string` + - `"server"` - The ID of the assistant to modify. + - `"client"` -- `--description: optional string` + - `parameters: optional unknown` - The description of the assistant. The maximum length is 512 characters. + Parameter schema for a client-executed tool search tool. -- `--instructions: optional string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + 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). -- `--metadata: optional map[string]` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - 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. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"web_search_preview"` -- `--model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `"web_search_preview_2025_03_11"` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `search_content_types: optional array of "text" or "image"` -- `--name: optional string` + - `"text"` - The name of the assistant. The maximum length is 256 characters. + - `"image"` -- `--reasoning-effort: optional "none" or "minimal" or "low" or 4 more` + - `search_context_size: optional "low" or "medium" or "high"` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + 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. -- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"low"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"medium"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"high"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `user_location: optional object { type, city, country, 2 more }` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The user's location. -- `--temperature: optional number` + - `type: "approximate"` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + The type of location approximation. Always `approximate`. -- `--tool-resources: optional object { code_interpreter, file_search }` + - `city: optional string` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + Free text input for the city of the user, e.g. `San Francisco`. -- `--tool: optional array of unknown` + - `country: optional string` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. -- `--top-p: optional number` + - `region: optional string` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + Free text input for the region of the user, e.g. `California`. - We generally recommend altering this or temperature but not both. + - `timezone: optional string` -### Returns + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. -- `assistant: object { id, created_at, description, 10 more }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - Represents an `assistant` that can call the model and use tools. + Allows the assistant to create, delete, or update files using unified diffs. - - `id: string` + - `type: "apply_patch"` - The identifier, which can be referenced in API endpoints. + The type of the tool. Always `apply_patch`. - - `created_at: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The Unix timestamp (in seconds) for when the assistant was created. + The tool invocation context(s). - - `description: string` + - `"direct"` - The description of the assistant. The maximum length is 512 characters. + - `"programmatic"` - - `instructions: string` + - `type: "tool_search_output"` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The item type. Always `tool_search_output`. - - `metadata: map[string]` + - `id: optional string` - 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. + The unique ID of this tool search output. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `agent: optional object { agent_name }` - - `model: string` + The agent that produced this item. - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the assistant. The maximum length is 256 characters. + - `call_id: optional string` - - `object: "assistant"` + The unique ID of the tool search call generated by the model. - The object type, which is always `assistant`. + - `execution: optional "server" or "client"` - - `tools: array of unknown` + Whether tool search was executed by the server or by the client. - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `"server"` - - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"client"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `status: optional "in_progress" or "completed" or "incomplete"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The status of the tool search output. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"in_progress"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"completed"` - - `union_member_0: "auto"` + - `"incomplete"` - `auto` is the default value + - `additional_tools: object { role, tools, type, 2 more }` - - `response_format_text: object { type }` + - `role: "developer"` - Default response format. Used to generate text responses. + The role that provided the additional tools. Only `developer` is supported. - - `type: "text"` + - `tools: array of BetaTool` - The type of response format being defined. Always `text`. + A list of additional tools made available at this item. - - `response_format_json_object: object { type }` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + 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). - - `type: "json_object"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The type of response format being defined. Always `json_object`. + 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). - - `response_format_json_schema: object { json_schema, type }` + - `beta_computer_tool: object { type }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `json_schema: object { name, description, schema, strict }` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - Structured Outputs configuration options, including a JSON Schema. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `name: string` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + 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). - - `description: optional string` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `schema: optional map[unknown]` + - `code_interpreter: object { container, type, allowed_callers }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A tool that runs Python code to help generate a response to a prompt. - - `strict: optional boolean` + - `programmatic_tool_calling: object { type }` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `image_generation: object { type, action, background, 9 more }` - - `type: "json_schema"` + A tool that generates images using the GPT image models. - The type of response format being defined. Always `json_schema`. + - `local_shell: object { type }` - - `temperature: optional number` + A tool that allows the model to execute shell commands in a local environment. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `tool_resources: optional object { code_interpreter, file_search }` + A tool that allows the model to execute shell commands. - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `code_interpreter: optional object { file_ids }` + 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) - - `file_ids: optional array of string` + - `beta_namespace_tool: object { description, name, tools, type }` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + Groups function/custom tools under a shared namespace. - - `file_search: optional object { vector_store_ids }` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `vector_store_ids: optional array of string` + Hosted or BYOT tool search configuration for deferred tools. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `top_p: optional number` + 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). - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `beta_apply_patch_tool: object { type, allowed_callers }` - We generally recommend altering this or temperature but not both. + Allows the assistant to create, delete, or update files using unified diffs. -### Example + - `type: "additional_tools"` -```cli -openai beta:assistants update \ - --api-key 'My API Key' \ - --assistant-id assistant_id -``` + The item type. Always `additional_tools`. -#### Response + - `id: optional string` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - {} - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + The unique ID of this additional tools item. -## Delete assistant + - `agent: optional object { agent_name }` -`$ openai beta:assistants delete` + The agent that produced this item. -**delete** `/assistants/{assistant_id}` + - `agent_name: string` -Delete assistant + The canonical name of the agent that produced this item. -### Parameters + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` -- `--assistant-id: string` + 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). - The ID of the assistant to delete. + - `id: string` -### Returns + The unique identifier of the reasoning content. -- `assistant_deleted: object { id, deleted, object }` + - `summary: array of object { text, type }` - - `id: string` + Reasoning summary content. - - `deleted: boolean` + - `text: string` - - `object: "assistant.deleted"` + A summary of the reasoning output from the model so far. -### Example + - `type: "summary_text"` -```cli -openai beta:assistants delete \ - --api-key 'My API Key' \ - --assistant-id assistant_id -``` + The type of the object. Always `summary_text`. -#### Response + - `type: "reasoning"` -```json -{ - "id": "id", - "deleted": true, - "object": "assistant.deleted" -} -``` + The type of the object. Always `reasoning`. -## Domain Types + - `agent: optional object { agent_name }` -### Assistant + The agent that produced this item. -- `assistant: object { id, created_at, description, 10 more }` + - `agent_name: string` - Represents an `assistant` that can call the model and use tools. + The canonical name of the agent that produced this item. - - `id: string` + - `content: optional array of object { text, type }` - The identifier, which can be referenced in API endpoints. + Reasoning text content. - - `created_at: number` + - `text: string` - The Unix timestamp (in seconds) for when the assistant was created. + The reasoning text from the model. - - `description: string` + - `type: "reasoning_text"` - The description of the assistant. The maximum length is 512 characters. + The type of the reasoning text. Always `reasoning_text`. - - `instructions: string` + - `encrypted_content: optional string` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `metadata: map[string]` + - `status: optional "in_progress" or "completed" or "incomplete"` - 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. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"in_progress"` - - `model: string` + - `"completed"` - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. + - `"incomplete"` - - `name: string` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - The name of the assistant. The maximum length is 256 characters. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `object: "assistant"` + - `encrypted_content: string` - The object type, which is always `assistant`. + The encrypted content of the compaction summary. - - `tools: array of unknown` + - `type: "compaction"` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + The type of the item. Always `compaction`. - - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `id: optional string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The ID of the compaction item. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `agent: optional object { agent_name }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The agent that produced this item. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `agent_name: string` - - `union_member_0: "auto"` + The canonical name of the agent that produced this item. - `auto` is the default value + - `image_generation_call: object { id, result, status, 2 more }` - - `response_format_text: object { type }` + An image generation request made by the model. - Default response format. Used to generate text responses. + - `id: string` - - `type: "text"` + The unique ID of the image generation call. - The type of response format being defined. Always `text`. + - `result: string` - - `response_format_json_object: object { type }` + The generated image encoded in base64. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `type: "json_object"` + The status of the image generation call. - The type of response format being defined. Always `json_object`. + - `"in_progress"` - - `response_format_json_schema: object { json_schema, type }` + - `"completed"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"generating"` - - `json_schema: object { name, description, schema, strict }` + - `"failed"` - Structured Outputs configuration options, including a JSON Schema. + - `type: "image_generation_call"` - - `name: string` + The type of the image generation call. Always `image_generation_call`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent_name: string` - - `schema: optional map[unknown]` + The canonical name of the agent that produced this item. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `strict: optional boolean` + A tool call to run code. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `id: string` - - `type: "json_schema"` + The unique ID of the code interpreter tool call. - The type of response format being defined. Always `json_schema`. + - `code: string` - - `temperature: optional number` + The code to run, or null if not available. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `container_id: string` - - `tool_resources: optional object { code_interpreter, file_search }` + The ID of the container used to run the code. - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `outputs: array of object { logs, type } or object { type, url }` - - `code_interpreter: optional object { file_ids }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `file_ids: optional array of string` + - `logs: object { logs, type }` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + The logs output from the code interpreter. - - `file_search: optional object { vector_store_ids }` + - `logs: string` - - `vector_store_ids: optional array of string` + The logs output from the code interpreter. - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `type: "logs"` - - `top_p: optional number` + The type of the output. Always `logs`. - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `image: object { type, url }` - We generally recommend altering this or temperature but not both. + The image output from the code interpreter. -### Assistant Deleted + - `type: "image"` -- `assistant_deleted: object { id, deleted, object }` + The type of the output. Always `image`. - - `id: string` + - `url: string` - - `deleted: boolean` + The URL of the image output from the code interpreter. - - `object: "assistant.deleted"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` -### Assistant Stream Event + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. -- `assistant_stream_event: object { data, event, enabled } or object { data, event } or object { data, event } or 21 more` + - `"in_progress"` - Represents an event emitted when streaming a Run. + - `"completed"` - Each event in a server-sent events stream has an `event` and `data` property: + - `"incomplete"` - ``` - event: thread.created - data: {"id": "thread_123", "object": "thread", ...} - ``` + - `"interpreting"` - We emit events whenever a new object is created, transitions to a new state, or is being - streamed in parts (deltas). For example, we emit `thread.run.created` when a new run - is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses - to create a message during a run, we emit a `thread.message.created event`, a - `thread.message.in_progress` event, many `thread.message.delta` events, and finally a - `thread.message.completed` event. + - `"failed"` - We may add additional events over time, so we recommend handling unknown events gracefully - in your code. See the [Assistants API quickstart](https://platform.openai.com/docs/assistants/overview) to learn how to - integrate the Assistants API with streaming. + - `type: "code_interpreter_call"` - - `thread.created: object { data, event, enabled }` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + - `agent: optional object { agent_name }` - - `data: object { id, created_at, metadata, 2 more }` + The agent that produced this item. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. - `id: string` - The identifier, which can be referenced in API endpoints. + The unique ID of the local shell call. - - `created_at: number` + - `action: object { command, env, type, 3 more }` - The Unix timestamp (in seconds) for when the thread was created. + Execute a shell command on the server. - - `metadata: map[string]` + - `command: array of string` - 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. + The command to run. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `env: map[string]` - - `object: "thread"` + Environment variables to set for the command. - The object type, which is always `thread`. + - `type: "exec"` - - `tool_resources: object { code_interpreter, file_search }` + The type of the local shell action. Always `exec`. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `timeout_ms: optional number` - - `code_interpreter: optional object { file_ids }` + Optional timeout in milliseconds for the command. - - `file_ids: optional array of string` + - `user: optional string` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + Optional user to run the command as. - - `file_search: optional object { vector_store_ids }` + - `working_directory: optional string` - - `vector_store_ids: optional array of string` + Optional working directory to run the command in. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `call_id: string` - - `event: "thread.created"` + The unique ID of the local shell tool call generated by the model. - - `enabled: optional boolean` + - `status: "in_progress" or "completed" or "incomplete"` - Whether to enable input audio transcription. + The status of the local shell call. - - `thread.run.created: object { data, event }` + - `"in_progress"` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + - `"completed"` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `"incomplete"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: "local_shell_call"` - - `id: string` + The type of the local shell call. Always `local_shell_call`. - The identifier, which can be referenced in API endpoints. + - `agent: optional object { agent_name }` - - `assistant_id: string` + The agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `agent_name: string` - - `cancelled_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was cancelled. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `completed_at: number` + The output of a local shell tool call. - The Unix timestamp (in seconds) for when the run was completed. + - `id: string` - - `created_at: number` + The unique ID of the local shell tool call generated by the model. - The Unix timestamp (in seconds) for when the run was created. + - `output: string` - - `expires_at: number` + A JSON string of the output of the local shell tool call. - The Unix timestamp (in seconds) for when the run will expire. + - `type: "local_shell_call_output"` - - `failed_at: number` + The type of the local shell tool call output. Always `local_shell_call_output`. - The Unix timestamp (in seconds) for when the run failed. + - `agent: optional object { agent_name }` - - `incomplete_details: object { reason }` + The agent that produced this item. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `agent_name: string` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + The canonical name of the agent that produced this item. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"max_completion_tokens"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"max_prompt_tokens"` + - `"in_progress"` - - `instructions: string` + - `"completed"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"incomplete"` - - `last_error: object { code, message }` + - `shell_call: object { action, call_id, type, 5 more }` - The last error associated with this run. Will be `null` if there are no errors. + A tool representing a request to execute one or more shell commands. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `action: object { commands, max_output_length, timeout_ms }` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The shell commands and limits that describe how to run the tool call. - - `"server_error"` + - `commands: array of string` - - `"rate_limit_exceeded"` + Ordered shell commands for the execution environment to run. - - `"invalid_prompt"` + - `max_output_length: optional number` - - `message: string` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - A human-readable description of the error. + - `timeout_ms: optional number` - - `max_completion_tokens: number` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - The maximum number of completion tokens specified to have been used over the course of the run. + - `call_id: string` - - `max_prompt_tokens: number` + The unique ID of the shell tool call generated by the model. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: "shell_call"` - - `metadata: map[string]` + The type of the item. Always `shell_call`. - 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. + - `id: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `model: string` + - `agent: optional object { agent_name }` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The agent that produced this item. - - `object: "thread.run"` + - `agent_name: string` - The object type, which is always `thread.run`. + The canonical name of the agent that produced this item. - - `parallel_tool_calls: boolean` + - `caller: optional object { type } or object { caller_id, type }` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The execution context that produced this tool call. - - `required_action: object { submit_tool_outputs, type }` + - `direct: object { type }` - Details on the action required to continue the run. Will be `null` if no action is required. + - `program: object { caller_id, type }` - - `submit_tool_outputs: object { tool_calls }` + - `caller_id: string` - Details on the tool outputs needed for this run to continue. + The call ID of the program item that produced this tool call. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `type: "program"` - A list of the relevant tool calls. + The caller type. Always `program`. - - `id: string` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The environment to execute the shell commands in. - - `function: object { arguments, name }` + - `beta_local_environment: object { type, skills }` - The function definition. + - `beta_container_reference: object { container_id, type }` - - `arguments: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The arguments that the model expects you to pass to the function. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `name: string` + - `"in_progress"` - The name of the function. + - `"completed"` - - `type: "function"` + - `"incomplete"` - The type of tool call the output is required for. For now, this is always `function`. + - `shell_call_output: object { call_id, output, type, 5 more }` - - `type: "submit_tool_outputs"` + The streamed output items emitted by a shell tool call. - For now, this is always `submit_tool_outputs`. + - `call_id: string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The unique ID of the shell tool call generated by the model. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `output: array of BetaResponseFunctionShellCallOutputContent` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + Captured chunks of stdout and stderr output, along with their associated outcomes. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `outcome: object { type } or object { exit_code, type }` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The exit or timeout outcome associated with this shell call. - - `union_member_0: "auto"` + - `timeout: object { type }` - `auto` is the default value + Indicates that the shell call exceeded its configured time limit. - - `response_format_text: object { type }` + - `exit: object { exit_code, type }` - Default response format. Used to generate text responses. + Indicates that the shell commands finished and returned an exit code. - - `type: "text"` + - `exit_code: number` - The type of response format being defined. Always `text`. + The exit code returned by the shell process. - - `response_format_json_object: object { type }` + - `type: "exit"` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The outcome type. Always `exit`. - - `type: "json_object"` + - `stderr: string` - The type of response format being defined. Always `json_object`. + Captured stderr output for the shell call. - - `response_format_json_schema: object { json_schema, type }` + - `stdout: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Captured stdout output for the shell call. - - `json_schema: object { name, description, schema, strict }` + - `type: "shell_call_output"` - Structured Outputs configuration options, including a JSON Schema. + The type of the item. Always `shell_call_output`. - - `name: string` + - `id: optional string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `description: optional string` + - `agent: optional object { agent_name }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The agent that produced this item. - - `schema: optional map[unknown]` + - `agent_name: string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The canonical name of the agent that produced this item. - - `strict: optional boolean` + - `caller: optional object { type } or object { caller_id, type }` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The execution context that produced this tool call. - - `type: "json_schema"` + - `direct: object { type }` - The type of response format being defined. Always `json_schema`. + - `program: object { caller_id, type }` - - `started_at: number` + - `caller_id: string` - The Unix timestamp (in seconds) for when the run was started. + The call ID of the program item that produced this tool call. - - `status: unknown` + - `type: "program"` - - `thread_id: string` + The caller type. Always `program`. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `max_output_length: optional number` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The maximum number of UTF-8 characters captured for this shell call's combined output. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `Auto: "none" or "auto" or "required"` + The status of the shell call output. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `"in_progress"` - - `"none"` + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"required"` + - `apply_patch_call: object { call_id, operation, status, 4 more }` - - `assistant_tool_choice: object { type, function }` + A tool call representing a request to create, delete, or update files using diff patches. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `call_id: string` - - `type: "function" or "code_interpreter" or "file_search"` + The unique ID of the apply patch tool call generated by the model. - The type of the tool. If type is `function`, the function name must be set + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"function"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `"code_interpreter"` + - `create_file: object { diff, path, type }` - - `"file_search"` + Instruction for creating a new file via the apply_patch tool. - - `function: optional object { name }` + - `diff: string` - - `name: string` + Unified diff content to apply when creating the file. - The name of the function to call. + - `path: string` - - `tools: array of unknown` + Path of the file to create relative to the workspace root. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: "create_file"` - - `truncation_strategy: object { type, last_messages }` + The operation type. Always `create_file`. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `delete_file: object { path, type }` - - `type: "auto" or "last_messages"` + Instruction for deleting an existing file via the apply_patch tool. - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `path: string` - - `"auto"` + Path of the file to delete relative to the workspace root. - - `"last_messages"` + - `type: "delete_file"` - - `last_messages: optional number` + The operation type. Always `delete_file`. - The number of most recent messages from the thread when constructing the context for the run. + - `update_file: object { diff, path, type }` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + Instruction for updating an existing file via the apply_patch tool. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `diff: string` - - `completion_tokens: number` + Unified diff content to apply to the existing file. - Number of completion tokens used over the course of the run. + - `path: string` - - `prompt_tokens: number` + Path of the file to update relative to the workspace root. - Number of prompt tokens used over the course of the run. + - `type: "update_file"` - - `total_tokens: number` + The operation type. Always `update_file`. - Total number of tokens used (prompt + completion). + - `status: "in_progress" or "completed"` - - `temperature: optional number` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The sampling temperature used for this run. If not set, defaults to 1. + - `"in_progress"` - - `top_p: optional number` + - `"completed"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `type: "apply_patch_call"` - - `event: "thread.run.created"` + The type of the item. Always `apply_patch_call`. - - `thread.run.queued: object { data, event }` + - `id: optional string` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `agent: optional object { agent_name }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The agent that produced this item. - - `id: string` + - `agent_name: string` - The identifier, which can be referenced in API endpoints. + The canonical name of the agent that produced this item. - - `assistant_id: string` + - `caller: optional object { type } or object { caller_id, type }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The execution context that produced this tool call. - - `cancelled_at: number` + - `direct: object { type }` - The Unix timestamp (in seconds) for when the run was cancelled. + - `program: object { caller_id, type }` - - `completed_at: number` + - `caller_id: string` - The Unix timestamp (in seconds) for when the run was completed. + The call ID of the program item that produced this tool call. - - `created_at: number` + - `type: "program"` - The Unix timestamp (in seconds) for when the run was created. + The caller type. Always `program`. - - `expires_at: number` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The Unix timestamp (in seconds) for when the run will expire. + The streamed output emitted by an apply patch tool call. - - `failed_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the run failed. + The unique ID of the apply patch tool call generated by the model. - - `incomplete_details: object { reason }` + - `status: "completed" or "failed"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `instructions: string` + - `"completed"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"failed"` - - `last_error: object { code, message }` + - `type: "apply_patch_call_output"` - The last error associated with this run. Will be `null` if there are no errors. + The type of the item. Always `apply_patch_call_output`. - - `max_completion_tokens: number` + - `id: optional string` - The maximum number of completion tokens specified to have been used over the course of the run. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `max_prompt_tokens: number` + - `agent: optional object { agent_name }` - The maximum number of prompt tokens specified to have been used over the course of the run. + The agent that produced this item. - - `metadata: map[string]` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `caller: optional object { type } or object { caller_id, type }` - - `model: string` + The execution context that produced this tool call. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `direct: object { type }` - - `object: "thread.run"` + - `program: object { caller_id, type }` - The object type, which is always `thread.run`. + - `caller_id: string` - - `parallel_tool_calls: boolean` + The call ID of the program item that produced this tool call. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `type: "program"` - - `required_action: object { submit_tool_outputs, type }` + The caller type. Always `program`. - Details on the action required to continue the run. Will be `null` if no action is required. + - `output: optional string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + A list of tools available on an MCP server. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `id: string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The unique ID of the list. - - `started_at: number` + - `server_label: string` - The Unix timestamp (in seconds) for when the run was started. + The label of the MCP server. - - `status: unknown` + - `tools: array of object { input_schema, name, annotations, description }` - - `thread_id: string` + The tools available on the server. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `input_schema: unknown` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The JSON schema describing the tool's input. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `name: string` - - `tools: array of unknown` + The name of the tool. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `annotations: optional unknown` - - `truncation_strategy: object { type, last_messages }` + Additional annotations about the tool. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `description: optional string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The description of the tool. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `type: "mcp_list_tools"` - - `temperature: optional number` + The type of the item. Always `mcp_list_tools`. - The sampling temperature used for this run. If not set, defaults to 1. + - `agent: optional object { agent_name }` - - `top_p: optional number` + The agent that produced this item. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `agent_name: string` - - `event: "thread.run.queued"` + The canonical name of the agent that produced this item. - - `thread.run.in_progress: object { data, event }` + - `error: optional string` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + Error message if the server could not list tools. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + A request for human approval of a tool invocation. - `id: string` - The identifier, which can be referenced in API endpoints. + The unique ID of the approval request. - - `assistant_id: string` + - `arguments: string` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + A JSON string of arguments for the tool. - - `cancelled_at: number` + - `name: string` - The Unix timestamp (in seconds) for when the run was cancelled. + The name of the tool to run. - - `completed_at: number` + - `server_label: string` - The Unix timestamp (in seconds) for when the run was completed. + The label of the MCP server making the request. - - `created_at: number` + - `type: "mcp_approval_request"` - The Unix timestamp (in seconds) for when the run was created. + The type of the item. Always `mcp_approval_request`. - - `expires_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the run will expire. + The agent that produced this item. - - `failed_at: number` + - `agent_name: string` - The Unix timestamp (in seconds) for when the run failed. + The canonical name of the agent that produced this item. - - `incomplete_details: object { reason }` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + A response to an MCP approval request. - - `instructions: string` + - `approval_request_id: string` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The ID of the approval request being answered. - - `last_error: object { code, message }` + - `approve: boolean` - The last error associated with this run. Will be `null` if there are no errors. + Whether the request was approved. - - `max_completion_tokens: number` + - `type: "mcp_approval_response"` - The maximum number of completion tokens specified to have been used over the course of the run. + The type of the item. Always `mcp_approval_response`. - - `max_prompt_tokens: number` + - `id: optional string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The unique ID of the approval response - - `metadata: map[string]` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `agent_name: string` - - `model: string` + The canonical name of the agent that produced this item. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `reason: optional string` - - `object: "thread.run"` + Optional reason for the decision. - The object type, which is always `thread.run`. + - `mcp_call: object { id, arguments, name, 7 more }` - - `parallel_tool_calls: boolean` + An invocation of a tool on an MCP server. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `id: string` - - `required_action: object { submit_tool_outputs, type }` + The unique ID of the tool call. - Details on the action required to continue the run. Will be `null` if no action is required. + - `arguments: string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + A JSON string of the arguments passed to the tool. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `name: string` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The name of the tool that was run. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `server_label: string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The label of the MCP server running the tool. - - `started_at: number` + - `type: "mcp_call"` - The Unix timestamp (in seconds) for when the run was started. + The type of the item. Always `mcp_call`. - - `status: unknown` + - `agent: optional object { agent_name }` - - `thread_id: string` + The agent that produced this item. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `agent_name: string` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The canonical name of the agent that produced this item. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `approval_request_id: optional string` - - `tools: array of unknown` + 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. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `error: optional string` - - `truncation_strategy: object { type, last_messages }` + The error from the tool call, if any. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `output: optional string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The output from the tool call. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `temperature: optional number` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The sampling temperature used for this run. If not set, defaults to 1. + - `"in_progress"` - - `top_p: optional number` + - `"completed"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"incomplete"` - - `event: "thread.run.in_progress"` + - `"calling"` - - `thread.run.requires_action: object { data, event }` + - `"failed"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + The output of a custom tool call from your code, being sent back to the model. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `call_id: string` - - `id: string` + The call ID, used to map this custom tool call output to a custom tool call. - The identifier, which can be referenced in API endpoints. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `assistant_id: string` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - - `cancelled_at: number` - - The Unix timestamp (in seconds) for when the run was cancelled. - - - `completed_at: number` - - The Unix timestamp (in seconds) for when the run was completed. - - - `created_at: number` + - `string output: string` - The Unix timestamp (in seconds) for when the run was created. + A string of the output of the custom tool call. - - `expires_at: number` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The Unix timestamp (in seconds) for when the run will expire. + Text, image, or file output of the custom tool call. - - `failed_at: number` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The Unix timestamp (in seconds) for when the run failed. + A text input to the model. - - `incomplete_details: object { reason }` + - `text: string` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The text input to the model. - - `instructions: string` + - `type: "input_text"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the input item. Always `input_text`. - - `last_error: object { code, message }` + - `prompt_cache_breakpoint: optional object { mode }` - The last error associated with this run. Will be `null` if there are no errors. + 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. - - `max_completion_tokens: number` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The maximum number of completion tokens specified to have been used over the course of the run. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `max_prompt_tokens: number` + - `detail: "low" or "high" or "auto" or "original"` - The maximum number of prompt tokens specified to have been used over the course of the run. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `metadata: map[string]` + - `type: "input_image"` - 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. + The type of the input item. Always `input_image`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `file_id: optional string` - - `model: string` + The ID of the file to be sent to the model. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `image_url: optional string` - - `object: "thread.run"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The object type, which is always `thread.run`. + - `prompt_cache_breakpoint: optional object { mode }` - - `parallel_tool_calls: boolean` + 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. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `required_action: object { submit_tool_outputs, type }` + A file input to the model. - Details on the action required to continue the run. Will be `null` if no action is required. + - `type: "input_file"` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The type of the input item. Always `input_file`. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `detail: optional "auto" or "low" or "high"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + 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`. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `file_data: optional string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The content of the file to be sent to the model. - - `started_at: number` + - `file_id: optional string` - The Unix timestamp (in seconds) for when the run was started. + The ID of the file to be sent to the model. - - `status: unknown` + - `file_url: optional string` - - `thread_id: string` + The URL of the file to be sent to the model. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `filename: optional string` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The name of the file to be sent to the model. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `prompt_cache_breakpoint: optional object { mode }` - - `tools: array of unknown` + 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. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: "custom_tool_call_output"` - - `truncation_strategy: object { type, last_messages }` + The type of the custom tool call output. Always `custom_tool_call_output`. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `id: optional string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The unique ID of the custom tool call output in the OpenAI platform. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `agent: optional object { agent_name }` - - `temperature: optional number` + The agent that produced this item. - The sampling temperature used for this run. If not set, defaults to 1. + - `agent_name: string` - - `top_p: optional number` + The canonical name of the agent that produced this item. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `caller: optional object { type } or object { caller_id, type }` - - `event: "thread.run.requires_action"` + The execution context that produced this tool call. - - `thread.run.completed: object { data, event }` + - `direct: object { type }` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + - `program: object { caller_id, type }` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `caller_id: string` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The call ID of the program item that produced this tool call. - - `id: string` + - `type: "program"` - The identifier, which can be referenced in API endpoints. + The caller type. Always `program`. - - `assistant_id: string` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + A call to a custom tool created by the model. - - `cancelled_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the run was cancelled. + An identifier used to map this custom tool call to a tool call output. - - `completed_at: number` + - `input: string` - The Unix timestamp (in seconds) for when the run was completed. + The input for the custom tool call generated by the model. - - `created_at: number` + - `name: string` - The Unix timestamp (in seconds) for when the run was created. + The name of the custom tool being called. - - `expires_at: number` + - `type: "custom_tool_call"` - The Unix timestamp (in seconds) for when the run will expire. + The type of the custom tool call. Always `custom_tool_call`. - - `failed_at: number` + - `id: optional string` - The Unix timestamp (in seconds) for when the run failed. + The unique ID of the custom tool call in the OpenAI platform. - - `incomplete_details: object { reason }` + - `agent: optional object { agent_name }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The agent that produced this item. - - `instructions: string` + - `agent_name: string` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The canonical name of the agent that produced this item. - - `last_error: object { code, message }` + - `caller: optional object { type } or object { caller_id, type }` - The last error associated with this run. Will be `null` if there are no errors. + The execution context that produced this tool call. - - `max_completion_tokens: number` + - `direct: object { type }` - The maximum number of completion tokens specified to have been used over the course of the run. + - `program: object { caller_id, type }` - - `max_prompt_tokens: number` + - `caller_id: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The call ID of the program item that produced this tool call. - - `metadata: map[string]` + - `type: "program"` - 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. + - `namespace: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The namespace of the custom tool being called. - - `model: string` + - `compaction_trigger: object { type, agent }` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Compacts the current context. Must be the final input item. - - `object: "thread.run"` + - `type: "compaction_trigger"` - The object type, which is always `thread.run`. + The type of the item. Always `compaction_trigger`. - - `parallel_tool_calls: boolean` + - `agent: optional object { agent_name }` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The agent that produced this item. - - `required_action: object { submit_tool_outputs, type }` + - `agent_name: string` - Details on the action required to continue the run. Will be `null` if no action is required. + The canonical name of the agent that produced this item. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `item_reference: object { id, agent, type }` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + An internal identifier for an item to reference. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `id: string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The ID of the item to reference. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `agent: optional object { agent_name }` - - `started_at: number` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run was started. + - `agent_name: string` - - `status: unknown` + The canonical name of the agent that produced this item. - - `thread_id: string` + - `type: optional "item_reference"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The type of item to reference. Always `item_reference`. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `"item_reference"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `program: object { id, call_id, code, 3 more }` - - `tools: array of unknown` + - `id: string` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID of this program item. - - `truncation_strategy: object { type, last_messages }` + - `call_id: string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The stable call ID of the program item. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `code: string` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The JavaScript source executed by programmatic tool calling. - - `temperature: optional number` + - `fingerprint: string` - The sampling temperature used for this run. If not set, defaults to 1. + Opaque program replay fingerprint that must be round-tripped. - - `top_p: optional number` + - `type: "program"` - The nucleus sampling value used for this run. If not set, defaults to 1. + The item type. Always `program`. - - `event: "thread.run.completed"` + - `agent: optional object { agent_name }` - - `thread.run.incomplete: object { data, event }` + The agent that produced this item. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + - `agent_name: string` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + The canonical name of the agent that produced this item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `program_output: object { id, call_id, result, 3 more }` - `id: string` - The identifier, which can be referenced in API endpoints. - - - `assistant_id: string` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - - `cancelled_at: number` - - The Unix timestamp (in seconds) for when the run was cancelled. - - - `completed_at: number` - - The Unix timestamp (in seconds) for when the run was completed. - - - `created_at: number` - - The Unix timestamp (in seconds) for when the run was created. + The unique ID of this program output item. - - `expires_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the run will expire. + The call ID of the program item. - - `failed_at: number` + - `result: string` - The Unix timestamp (in seconds) for when the run failed. + The result produced by the program item. - - `incomplete_details: object { reason }` + - `status: "completed" or "incomplete"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The terminal status of the program output. - - `instructions: string` + - `"completed"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"incomplete"` - - `last_error: object { code, message }` + - `type: "program_output"` - The last error associated with this run. Will be `null` if there are no errors. + The item type. Always `program_output`. - - `max_completion_tokens: number` + - `agent: optional object { agent_name }` - The maximum number of completion tokens specified to have been used over the course of the run. + The agent that produced this item. - - `max_prompt_tokens: number` + - `agent_name: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The canonical name of the agent that produced this item. - `metadata: map[string]` @@ -4282,10867 +3959,9808 @@ openai beta:assistants delete \ Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: string` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Model ID used to generate the response, like `gpt-4o` 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. - - `object: "thread.run"` + - `"gpt-5.6-sol"` - The object type, which is always `thread.run`. + - `"gpt-5.6-terra"` - - `parallel_tool_calls: boolean` + - `"gpt-5.6-luna"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"gpt-5.4"` - - `required_action: object { submit_tool_outputs, type }` + - `"gpt-5.4-mini"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"gpt-5.4-nano"` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"gpt-5.4-mini-2026-03-17"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"gpt-5.4-nano-2026-03-17"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"gpt-5.3-chat-latest"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"gpt-5.2"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"gpt-5.2-2025-12-11"` - - `started_at: number` + - `"gpt-5.2-chat-latest"` - The Unix timestamp (in seconds) for when the run was started. + - `"gpt-5.2-pro"` - - `status: unknown` + - `"gpt-5.2-pro-2025-12-11"` - - `thread_id: string` + - `"gpt-5.1"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"gpt-5.1-2025-11-13"` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `"gpt-5.1-codex"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `"gpt-5.1-mini"` - - `tools: array of unknown` + - `"gpt-5.1-chat-latest"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-5"` - - `truncation_strategy: object { type, last_messages }` + - `"gpt-5-mini"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"gpt-5-nano"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"gpt-5-2025-08-07"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"gpt-5-mini-2025-08-07"` - - `temperature: optional number` + - `"gpt-5-nano-2025-08-07"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"gpt-5-chat-latest"` - - `top_p: optional number` + - `"gpt-4.1"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"gpt-4.1-mini"` - - `event: "thread.run.incomplete"` + - `"gpt-4.1-nano"` - - `thread.run.failed: object { data, event }` + - `"gpt-4.1-2025-04-14"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + - `"gpt-4.1-mini-2025-04-14"` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `"gpt-4.1-nano-2025-04-14"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"o4-mini"` - - `id: string` + - `"o4-mini-2025-04-16"` - The identifier, which can be referenced in API endpoints. + - `"o3"` - - `assistant_id: string` + - `"o3-2025-04-16"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"o3-mini"` - - `cancelled_at: number` + - `"o3-mini-2025-01-31"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `"o1"` - - `completed_at: number` + - `"o1-2024-12-17"` - The Unix timestamp (in seconds) for when the run was completed. + - `"o1-preview"` - - `created_at: number` + - `"o1-preview-2024-09-12"` - The Unix timestamp (in seconds) for when the run was created. + - `"o1-mini"` - - `expires_at: number` + - `"o1-mini-2024-09-12"` - The Unix timestamp (in seconds) for when the run will expire. + - `"gpt-4o"` - - `failed_at: number` + - `"gpt-4o-2024-11-20"` - The Unix timestamp (in seconds) for when the run failed. + - `"gpt-4o-2024-08-06"` - - `incomplete_details: object { reason }` + - `"gpt-4o-2024-05-13"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"gpt-4o-audio-preview"` - - `instructions: string` + - `"gpt-4o-audio-preview-2024-10-01"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-4o-audio-preview-2024-12-17"` - - `last_error: object { code, message }` + - `"gpt-4o-audio-preview-2025-06-03"` - The last error associated with this run. Will be `null` if there are no errors. + - `"gpt-4o-mini-audio-preview"` - - `max_completion_tokens: number` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"gpt-4o-search-preview"` - - `max_prompt_tokens: number` + - `"gpt-4o-mini-search-preview"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"gpt-4o-search-preview-2025-03-11"` - - `metadata: map[string]` + - `"gpt-4o-mini-search-preview-2025-03-11"` - 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. + - `"chatgpt-4o-latest"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"codex-mini-latest"` - - `model: string` + - `"gpt-4o-mini"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-4o-mini-2024-07-18"` - - `object: "thread.run"` + - `"gpt-4-turbo"` - The object type, which is always `thread.run`. + - `"gpt-4-turbo-2024-04-09"` - - `parallel_tool_calls: boolean` + - `"gpt-4-0125-preview"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"gpt-4-turbo-preview"` - - `required_action: object { submit_tool_outputs, type }` + - `"gpt-4-1106-preview"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"gpt-4-vision-preview"` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"gpt-4"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"gpt-4-0314"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"gpt-4-0613"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"gpt-4-32k"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"gpt-4-32k-0314"` - - `started_at: number` + - `"gpt-4-32k-0613"` - The Unix timestamp (in seconds) for when the run was started. + - `"gpt-3.5-turbo"` - - `status: unknown` + - `"gpt-3.5-turbo-16k"` - - `thread_id: string` + - `"gpt-3.5-turbo-0301"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"gpt-3.5-turbo-0613"` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `"gpt-3.5-turbo-1106"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `"gpt-3.5-turbo-0125"` - - `tools: array of unknown` + - `"gpt-3.5-turbo-16k-0613"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"o1-pro"` - - `truncation_strategy: object { type, last_messages }` + - `"o1-pro-2025-03-19"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"o3-pro"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"o3-pro-2025-06-10"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"o3-deep-research"` - - `temperature: optional number` + - `"o3-deep-research-2025-06-26"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"o4-mini-deep-research"` - - `top_p: optional number` + - `"o4-mini-deep-research-2025-06-26"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"computer-use-preview"` - - `event: "thread.run.failed"` + - `"computer-use-preview-2025-03-11"` - - `thread.run.cancelling: object { data, event }` + - `"gpt-5-codex"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. + - `"gpt-5-pro"` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `"gpt-5-pro-2025-10-06"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"gpt-5.1-codex-max"` - - `id: string` + - `object: "response"` - The identifier, which can be referenced in API endpoints. + The object type of this resource - always set to `response`. - - `assistant_id: string` + - `output: array of BetaResponseOutputItem` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + An array of content items generated by the model. - - `cancelled_at: number` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - The Unix timestamp (in seconds) for when the run was cancelled. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `completed_at: number` + An output message from the model. - The Unix timestamp (in seconds) for when the run was completed. + - `id: string` - - `created_at: number` + The unique ID of the output message. - The Unix timestamp (in seconds) for when the run was created. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `expires_at: number` + The content of the output message. - The Unix timestamp (in seconds) for when the run will expire. + - `role: "assistant"` - - `failed_at: number` + The role of the output message. Always `assistant`. - The Unix timestamp (in seconds) for when the run failed. + - `status: "in_progress" or "completed" or "incomplete"` - - `incomplete_details: object { reason }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `type: "message"` - - `instructions: string` + The type of the output message. Always `message`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `agent: optional object { agent_name }` - - `last_error: object { code, message }` + The agent that produced this item. - The last error associated with this run. Will be `null` if there are no errors. + - `phase: optional "commentary" or "final_answer"` - - `max_completion_tokens: number` + 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. - The maximum number of completion tokens specified to have been used over the course of the run. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `max_prompt_tokens: number` + 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. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `id: string` - - `metadata: map[string]` + The unique ID of the file search tool call. - 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. + - `queries: array of string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The queries used to search for files. - - `model: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `object: "thread.run"` + - `type: "file_search_call"` - The object type, which is always `thread.run`. + The type of the file search tool call. Always `file_search_call`. - - `parallel_tool_calls: boolean` + - `agent: optional object { agent_name }` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The agent that produced this item. - - `required_action: object { submit_tool_outputs, type }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Details on the action required to continue the run. Will be `null` if no action is required. + The results of the file search tool call. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `arguments: string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + A JSON string of the arguments to pass to the function. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `call_id: string` - - `started_at: number` + The unique ID of the function tool call generated by the model. - The Unix timestamp (in seconds) for when the run was started. + - `name: string` - - `status: unknown` + The name of the function to run. - - `thread_id: string` + - `type: "function_call"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The type of the function tool call. Always `function_call`. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `id: optional string` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The unique ID of the function tool call. - - `tools: array of unknown` + - `agent: optional object { agent_name }` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The agent that produced this item. - - `truncation_strategy: object { type, last_messages }` + - `caller: optional object { type } or object { caller_id, type }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The execution context that produced this tool call. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `namespace: optional string` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The namespace of the function to run. - - `temperature: optional number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The sampling temperature used for this run. If not set, defaults to 1. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `top_p: optional number` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `id: string` - - `event: "thread.run.cancelling"` + The unique ID of the function call tool output. - - `thread.run.cancelled: object { data, event }` + - `call_id: string` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + The unique ID of the function tool call generated by the model. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The output from the function call generated by your code. + Can be a string or an list of output content. - - `id: string` + - `string output: string` - The identifier, which can be referenced in API endpoints. + A string of the output of the function call. - - `assistant_id: string` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + Text, image, or file output of the function call. - - `cancelled_at: number` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The Unix timestamp (in seconds) for when the run was cancelled. + A text input to the model. - - `completed_at: number` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The Unix timestamp (in seconds) for when the run was completed. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `created_at: number` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The Unix timestamp (in seconds) for when the run was created. + A file input to the model. - - `expires_at: number` + - `status: "in_progress" or "completed" or "incomplete"` - The Unix timestamp (in seconds) for when the run will expire. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `failed_at: number` + - `"in_progress"` - The Unix timestamp (in seconds) for when the run failed. + - `"completed"` - - `incomplete_details: object { reason }` + - `"incomplete"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `type: "function_call_output"` - - `instructions: string` + The type of the function tool call output. Always `function_call_output`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `agent: optional object { agent_name }` - - `last_error: object { code, message }` + The agent that produced this item. - The last error associated with this run. Will be `null` if there are no errors. + - `agent_name: string` - - `max_completion_tokens: number` + The canonical name of the agent that produced this item. - The maximum number of completion tokens specified to have been used over the course of the run. + - `caller: optional object { type } or object { caller_id, type }` - - `max_prompt_tokens: number` + The execution context that produced this tool call. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `direct: object { type }` - - `metadata: map[string]` + - `program: object { caller_id, type }` - 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. + - `caller_id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The call ID of the program item that produced this tool call. - - `model: string` + - `type: "program"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The caller type. Always `program`. - - `object: "thread.run"` + - `created_by: optional string` - The object type, which is always `thread.run`. + The identifier of the actor that created the item. - - `parallel_tool_calls: boolean` + - `agent_message: object { id, author, content, 3 more }` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `id: string` - - `required_action: object { submit_tool_outputs, type }` + The unique ID of the agent message. - Details on the action required to continue the run. Will be `null` if no action is required. + - `author: string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The sending agent identity. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + Encrypted content sent between agents. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + A text input to the model. - - `started_at: number` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - The Unix timestamp (in seconds) for when the run was started. + A text output from the model. - - `status: unknown` + - `text: object { text, type }` - - `thread_id: string` + A text content. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `text: string` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `type: "text"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `summary_text: object { text, type }` - - `tools: array of unknown` + A summary text from the model. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `text: string` - - `truncation_strategy: object { type, last_messages }` + A summary of the reasoning output from the model so far. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: "summary_text"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The type of the object. Always `summary_text`. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `reasoning_text: object { text, type }` - - `temperature: optional number` + Reasoning text from the model. - The sampling temperature used for this run. If not set, defaults to 1. + - `text: string` - - `top_p: optional number` + The reasoning text from the model. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `type: "reasoning_text"` - - `event: "thread.run.cancelled"` + The type of the reasoning text. Always `reasoning_text`. - - `thread.run.expired: object { data, event }` + - `beta_response_output_refusal: object { refusal, type }` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. + A refusal from the model. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `id: string` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - The identifier, which can be referenced in API endpoints. + A screenshot of a computer. - - `assistant_id: string` + - `detail: "low" or "high" or "auto" or "original"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `cancelled_at: number` + - `"low"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `"high"` - - `completed_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run was completed. + - `"original"` - - `created_at: number` + - `file_id: string` - The Unix timestamp (in seconds) for when the run was created. + The identifier of an uploaded file that contains the screenshot. - - `expires_at: number` + - `image_url: string` - The Unix timestamp (in seconds) for when the run will expire. + The URL of the screenshot image. - - `failed_at: number` + - `type: "computer_screenshot"` - The Unix timestamp (in seconds) for when the run failed. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `incomplete_details: object { reason }` + - `prompt_cache_breakpoint: optional object { mode }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + 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. - - `instructions: string` + - `mode: "explicit"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The breakpoint mode. Always `explicit`. - - `last_error: object { code, message }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The last error associated with this run. Will be `null` if there are no errors. + A file input to the model. - - `max_completion_tokens: number` + - `encrypted_content: object { encrypted_content, type }` - The maximum number of completion tokens specified to have been used over the course of the run. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `max_prompt_tokens: number` + - `encrypted_content: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + Opaque encrypted content. - - `metadata: map[string]` + - `type: "encrypted_content"` - 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. + The type of the input item. Always `encrypted_content`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `recipient: string` - - `model: string` + The destination agent identity. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: "agent_message"` - - `object: "thread.run"` + The type of the item. Always `agent_message`. - The object type, which is always `thread.run`. + - `agent: optional object { agent_name }` - - `parallel_tool_calls: boolean` + The agent that produced this item. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `agent_name: string` - - `required_action: object { submit_tool_outputs, type }` + The canonical name of the agent that produced this item. - Details on the action required to continue the run. Will be `null` if no action is required. + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `id: string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The unique ID of the multi-agent call item. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The multi-agent action to execute. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"spawn_agent"` - - `started_at: number` + - `"interrupt_agent"` - The Unix timestamp (in seconds) for when the run was started. + - `"list_agents"` - - `status: unknown` + - `"send_message"` - - `thread_id: string` + - `"followup_task"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"wait_agent"` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `arguments: string` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The JSON string of arguments generated for the action. - - `tools: array of unknown` + - `call_id: string` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID linking this call to its output. - - `truncation_strategy: object { type, last_messages }` + - `type: "multi_agent_call"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The type of the multi-agent call. Always `multi_agent_call`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `agent: optional object { agent_name }` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The agent that produced this item. - - `temperature: optional number` + - `agent_name: string` - The sampling temperature used for this run. If not set, defaults to 1. + The canonical name of the agent that produced this item. - - `top_p: optional number` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `id: string` - - `event: "thread.run.expired"` + The unique ID of the multi-agent call output item. - - `thread.run.step.created: object { data, event }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + The multi-agent action that produced this result. - - `data: object { id, assistant_id, cancelled_at, 13 more }` + - `"spawn_agent"` - Represents a step in execution of a run. + - `"interrupt_agent"` - - `id: string` + - `"list_agents"` - The identifier of the run step, which can be referenced in API endpoints. + - `"send_message"` - - `assistant_id: string` + - `"followup_task"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `"wait_agent"` - - `cancelled_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the run step was cancelled. + The unique ID of the multi-agent call. - - `completed_at: number` + - `output: array of BetaResponseOutputText` - The Unix timestamp (in seconds) for when the run step completed. + Text output returned by the multi-agent action. - - `created_at: number` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The Unix timestamp (in seconds) for when the run step was created. + The annotations of the text output. - - `expired_at: number` + - `text: string` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The text output from the model. - - `failed_at: number` + - `type: "output_text"` - The Unix timestamp (in seconds) for when the run step failed. + The type of the output text. Always `output_text`. - - `last_error: object { code, message }` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - The last error associated with this run step. Will be `null` if there are no errors. + - `type: "multi_agent_call_output"` - - `code: "server_error" or "rate_limit_exceeded"` + The type of the multi-agent result. Always `multi_agent_call_output`. - One of `server_error` or `rate_limit_exceeded`. + - `agent: optional object { agent_name }` - - `"server_error"` + The agent that produced this item. - - `"rate_limit_exceeded"` + - `agent_name: string` - - `message: string` + The canonical name of the agent that produced this item. - A human-readable description of the error. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `metadata: map[string]` + 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. - 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. + - `id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The unique ID of the web search tool call. - - `object: "thread.run.step"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The object type, which is always `thread.run.step`. + 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). - - `run_id: string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + The status of the web search tool call. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `type: "web_search_call"` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + The type of the web search tool call. Always `web_search_call`. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"cancelled"` + The agent that produced this item. - - `"failed"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `"completed"` + 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. - - `"expired"` + - `id: string` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + The unique ID of the computer call. - The details of the run step. + - `call_id: string` - - `message_creation_step_details: object { message_creation, type }` + An identifier used when responding to the tool call with output. - Details of the message creation by the run step. + - `pending_safety_checks: array of object { id, code, message }` - - `message_creation: object { message_id }` + The pending safety checks for the computer call. - - `message_id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The ID of the message that was created by this run step. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "message_creation"` + - `type: "computer_call"` - Always `message_creation`. + The type of the computer call. Always `computer_call`. - - `tool_calls_step_details: object { tool_calls, type }` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - Details of the tool call. + A click action. - - `tool_calls: array of unknown` + - `actions: optional array of BetaComputerAction` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `type: "tool_calls"` + - `agent: optional object { agent_name }` - Always `tool_calls`. + The agent that produced this item. - - `thread_id: string` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `id: string` - - `type: "message_creation" or "tool_calls"` + The unique ID of the computer call tool output. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `call_id: string` - - `"message_creation"` + The ID of the computer tool call that produced the output. - - `"tool_calls"` + - `output: object { type, file_id, image_url }` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + A computer screenshot image used with the computer use tool. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `type: "computer_screenshot"` - - `completion_tokens: number` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Number of completion tokens used over the course of the run step. + - `file_id: optional string` - - `prompt_tokens: number` + The identifier of an uploaded file that contains the screenshot. - Number of prompt tokens used over the course of the run step. + - `image_url: optional string` - - `total_tokens: number` + The URL of the screenshot image. - Total number of tokens used (prompt + completion). + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `event: "thread.run.step.created"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `thread.run.step.in_progress: object { data, event }` + - `"completed"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `"incomplete"` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + - `"failed"` - Represents a step in execution of a run. + - `"in_progress"` - - `id: string` + - `type: "computer_call_output"` - The identifier of the run step, which can be referenced in API endpoints. + The type of the computer tool call output. Always `computer_call_output`. - - `assistant_id: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + The safety checks reported by the API that have been acknowledged by the + developer. - - `cancelled_at: number` + - `id: string` - The Unix timestamp (in seconds) for when the run step was cancelled. + The ID of the pending safety check. - - `completed_at: number` + - `code: optional string` - The Unix timestamp (in seconds) for when the run step completed. + The type of the pending safety check. - - `created_at: number` + - `message: optional string` - The Unix timestamp (in seconds) for when the run step was created. + Details about the pending safety check. - - `expired_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The agent that produced this item. - - `failed_at: number` + - `agent_name: string` - The Unix timestamp (in seconds) for when the run step failed. + The canonical name of the agent that produced this item. - - `last_error: object { code, message }` + - `created_by: optional string` - The last error associated with this run step. Will be `null` if there are no errors. + The identifier of the actor that created the item. - - `metadata: map[string]` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - 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. + 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). - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: string` - - `object: "thread.run.step"` + The unique identifier of the reasoning content. - The object type, which is always `thread.run.step`. + - `summary: array of object { text, type }` - - `run_id: string` + Reasoning summary content. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `type: "reasoning"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + The type of the object. Always `reasoning`. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `agent: optional object { agent_name }` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + The agent that produced this item. - The details of the run step. + - `content: optional array of object { text, type }` - - `thread_id: string` + Reasoning text content. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `encrypted_content: optional string` - - `type: "message_creation" or "tool_calls"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `program: object { id, call_id, code, 3 more }` - - `event: "thread.run.step.in_progress"` + - `id: string` - - `thread.run.step.delta: object { data, event }` + The unique ID of the program item. - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + - `call_id: string` - - `data: object { id, delta, object }` + The stable call ID of the program item. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `code: string` - - `id: string` + The JavaScript source executed by programmatic tool calling. - The identifier of the run step, which can be referenced in API endpoints. + - `fingerprint: string` - - `delta: unknown` + Opaque program replay fingerprint that must be round-tripped. - - `object: "thread.run.step.delta"` + - `type: "program"` - The object type, which is always `thread.run.step.delta`. + The type of the item. Always `program`. - - `event: "thread.run.step.delta"` + - `agent: optional object { agent_name }` - - `thread.run.step.completed: object { data, event }` + The agent that produced this item. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + - `agent_name: string` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + The canonical name of the agent that produced this item. - Represents a step in execution of a run. + - `program_output: object { id, call_id, result, 3 more }` - `id: string` - The identifier of the run step, which can be referenced in API endpoints. - - - `assistant_id: string` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - - `cancelled_at: number` + The unique ID of the program output item. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `call_id: string` - - `completed_at: number` + The call ID of the program item. - The Unix timestamp (in seconds) for when the run step completed. + - `result: string` - - `created_at: number` + The result produced by the program item. - The Unix timestamp (in seconds) for when the run step was created. + - `status: "completed" or "incomplete"` - - `expired_at: number` + The terminal status of the program output item. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"completed"` - - `failed_at: number` + - `"incomplete"` - The Unix timestamp (in seconds) for when the run step failed. + - `type: "program_output"` - - `last_error: object { code, message }` + The type of the item. Always `program_output`. - The last error associated with this run step. Will be `null` if there are no errors. + - `agent: optional object { agent_name }` - - `metadata: map[string]` + The agent that produced this item. - 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. + - `agent_name: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The canonical name of the agent that produced this item. - - `object: "thread.run.step"` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - The object type, which is always `thread.run.step`. + - `id: string` - - `run_id: string` + The unique ID of the tool search call item. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `arguments: unknown` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + Arguments used for the tool search call. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `call_id: string` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + The unique ID of the tool search call generated by the model. - The details of the run step. + - `execution: "server" or "client"` - - `thread_id: string` + Whether tool search was executed by the server or by the client. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"server"` - - `type: "message_creation" or "tool_calls"` + - `"client"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `status: "in_progress" or "completed" or "incomplete"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The status of the tool search call item that was recorded. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `"in_progress"` - - `event: "thread.run.step.completed"` + - `"completed"` - - `thread.run.step.failed: object { data, event }` + - `"incomplete"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + - `type: "tool_search_call"` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + The type of the item. Always `tool_search_call`. - Represents a step in execution of a run. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - The identifier of the run step, which can be referenced in API endpoints. + - `agent_name: string` - - `assistant_id: string` + The canonical name of the agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `created_by: optional string` - - `cancelled_at: number` + The identifier of the actor that created the item. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `completed_at: number` + - `id: string` - The Unix timestamp (in seconds) for when the run step completed. + The unique ID of the tool search output item. - - `created_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the run step was created. + The unique ID of the tool search call generated by the model. - - `expired_at: number` + - `execution: "server" or "client"` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + Whether tool search was executed by the server or by the client. - - `failed_at: number` + - `"server"` - The Unix timestamp (in seconds) for when the run step failed. + - `"client"` - - `last_error: object { code, message }` + - `status: "in_progress" or "completed" or "incomplete"` - The last error associated with this run step. Will be `null` if there are no errors. + The status of the tool search output item that was recorded. - - `metadata: map[string]` + - `"in_progress"` - 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. + - `"completed"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"incomplete"` - - `object: "thread.run.step"` + - `tools: array of BetaTool` - The object type, which is always `thread.run.step`. + The loaded tool definitions returned by tool search. - - `run_id: string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + 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). - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + 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). - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `beta_computer_tool: object { type }` - The details of the run step. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `thread_id: string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "message_creation" or "tool_calls"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of run step, which can be either `message_creation` or `tool_calls`. + 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). - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `event: "thread.run.step.failed"` + - `code_interpreter: object { container, type, allowed_callers }` - - `thread.run.step.cancelled: object { data, event }` + A tool that runs Python code to help generate a response to a prompt. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + - `programmatic_tool_calling: object { type }` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + - `image_generation: object { type, action, background, 9 more }` - Represents a step in execution of a run. + A tool that generates images using the GPT image models. - - `id: string` + - `local_shell: object { type }` - The identifier of the run step, which can be referenced in API endpoints. + A tool that allows the model to execute shell commands in a local environment. - - `assistant_id: string` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + A tool that allows the model to execute shell commands. - - `cancelled_at: number` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The Unix timestamp (in seconds) for when the run step was cancelled. + 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) - - `completed_at: number` + - `beta_namespace_tool: object { description, name, tools, type }` - The Unix timestamp (in seconds) for when the run step completed. + Groups function/custom tools under a shared namespace. - - `created_at: number` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The Unix timestamp (in seconds) for when the run step was created. + Hosted or BYOT tool search configuration for deferred tools. - - `expired_at: number` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + 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). - - `failed_at: number` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The Unix timestamp (in seconds) for when the run step failed. + Allows the assistant to create, delete, or update files using unified diffs. - - `last_error: object { code, message }` + - `type: "tool_search_output"` - The last error associated with this run step. Will be `null` if there are no errors. + The type of the item. Always `tool_search_output`. - - `metadata: map[string]` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `agent_name: string` - - `object: "thread.run.step"` + The canonical name of the agent that produced this item. - The object type, which is always `thread.run.step`. + - `created_by: optional string` - - `run_id: string` + The identifier of the actor that created the item. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `additional_tools: object { id, role, tools, 2 more }` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `id: string` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + The unique ID of the additional tools item. - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `role: "unknown" or "user" or "assistant" or 5 more` - The details of the run step. + The role that provided the additional tools. - - `thread_id: string` + - `"unknown"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"user"` - - `type: "message_creation" or "tool_calls"` + - `"assistant"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"system"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"critic"` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `"discriminator"` - - `event: "thread.run.step.cancelled"` + - `"developer"` - - `thread.run.step.expired: object { data, event }` + - `"tool"` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. + - `tools: array of BetaTool` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + The additional tool definitions made available at this item. - Represents a step in execution of a run. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `id: string` + 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). - The identifier of the run step, which can be referenced in API endpoints. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `assistant_id: string` + 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). - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `beta_computer_tool: object { type }` - - `cancelled_at: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The Unix timestamp (in seconds) for when the run step was cancelled. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `completed_at: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The Unix timestamp (in seconds) for when the run step completed. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `created_at: number` + 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). - The Unix timestamp (in seconds) for when the run step was created. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `expired_at: number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `code_interpreter: object { container, type, allowed_callers }` - - `failed_at: number` + A tool that runs Python code to help generate a response to a prompt. - The Unix timestamp (in seconds) for when the run step failed. + - `programmatic_tool_calling: object { type }` - - `last_error: object { code, message }` + - `image_generation: object { type, action, background, 9 more }` - The last error associated with this run step. Will be `null` if there are no errors. + A tool that generates images using the GPT image models. - - `metadata: map[string]` + - `local_shell: object { type }` - 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. + A tool that allows the model to execute shell commands in a local environment. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `object: "thread.run.step"` + A tool that allows the model to execute shell commands. - The object type, which is always `thread.run.step`. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `run_id: string` + 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) - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `beta_namespace_tool: object { description, name, tools, type }` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + Groups function/custom tools under a shared namespace. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + Hosted or BYOT tool search configuration for deferred tools. - The details of the run step. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `thread_id: string` + 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). - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `type: "message_creation" or "tool_calls"` + Allows the assistant to create, delete, or update files using unified diffs. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `type: "additional_tools"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The type of the item. Always `additional_tools`. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `agent: optional object { agent_name }` - - `event: "thread.run.step.expired"` + The agent that produced this item. - - `thread.message.created: object { data, event }` + - `agent_name: string` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + The canonical name of the agent that produced this item. - - `data: object { id, assistant_id, attachments, 11 more }` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: string` - The identifier, which can be referenced in API endpoints. + The unique ID of the compaction item. - - `assistant_id: string` + - `encrypted_content: string` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The encrypted content that was produced by compaction. - - `attachments: array of object { file_id, tools }` + - `type: "compaction"` - A list of files attached to the message, and the tools they were added to. + The type of the item. Always `compaction`. - - `file_id: optional string` + - `agent: optional object { agent_name }` - The ID of the file to attach to the message. + The agent that produced this item. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `agent_name: string` - The tools to add this file to. + The canonical name of the agent that produced this item. - - `code_interpreter_tool: object { type }` + - `created_by: optional string` - - `type: "code_interpreter"` + The identifier of the actor that created the item. - The type of tool being defined: `code_interpreter` + - `image_generation_call: object { id, result, status, 2 more }` - - `AssistantToolsFileSearchTypeOnly: object { type }` + An image generation request made by the model. - - `completed_at: number` + - `id: string` - The Unix timestamp (in seconds) for when the message was completed. + The unique ID of the image generation call. - - `content: array of unknown` + - `result: string` - The content of the message in array of text and/or images. + The generated image encoded in base64. - - `created_at: number` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The Unix timestamp (in seconds) for when the message was created. + The status of the image generation call. - - `incomplete_at: number` + - `"in_progress"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `"completed"` - - `incomplete_details: object { reason }` + - `"generating"` - On an incomplete message, details about why the message is incomplete. + - `"failed"` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `type: "image_generation_call"` - The reason the message is incomplete. + The type of the image generation call. Always `image_generation_call`. - - `"content_filter"` + - `agent: optional object { agent_name }` - - `"max_tokens"` + The agent that produced this item. - - `"run_cancelled"` + - `agent_name: string` - - `"run_expired"` + The canonical name of the agent that produced this item. - - `"run_failed"` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `metadata: map[string]` + A tool call to run code. - 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. + - `id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The unique ID of the code interpreter tool call. - - `object: "thread.message"` + - `code: string` - The object type, which is always `thread.message`. + The code to run, or null if not available. - - `role: "user" or "assistant"` + - `container_id: string` - The entity that produced the message. One of `user` or `assistant`. + The ID of the container used to run the code. - - `"user"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"assistant"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `run_id: string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `status: "in_progress" or "incomplete" or "completed"` + - `type: "code_interpreter_call"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"incomplete"` + The agent that produced this item. - - `"completed"` + - `local_shell_call: object { id, action, call_id, 3 more }` - - `thread_id: string` + A tool call to run a command on the local shell. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `id: string` - - `event: "thread.message.created"` + The unique ID of the local shell call. - - `thread.message.in_progress: object { data, event }` + - `action: object { command, env, type, 3 more }` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + Execute a shell command on the server. - - `data: object { id, assistant_id, attachments, 11 more }` + - `command: array of string` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + The command to run. - - `id: string` + - `env: map[string]` - The identifier, which can be referenced in API endpoints. + Environment variables to set for the command. - - `assistant_id: string` + - `type: "exec"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The type of the local shell action. Always `exec`. - - `attachments: array of object { file_id, tools }` + - `timeout_ms: optional number` - A list of files attached to the message, and the tools they were added to. + Optional timeout in milliseconds for the command. - - `completed_at: number` + - `user: optional string` - The Unix timestamp (in seconds) for when the message was completed. + Optional user to run the command as. - - `content: array of unknown` + - `working_directory: optional string` - The content of the message in array of text and/or images. + Optional working directory to run the command in. - - `created_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the message was created. + The unique ID of the local shell tool call generated by the model. - - `incomplete_at: number` + - `status: "in_progress" or "completed" or "incomplete"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The status of the local shell call. - - `incomplete_details: object { reason }` + - `"in_progress"` - On an incomplete message, details about why the message is incomplete. + - `"completed"` - - `metadata: map[string]` + - `"incomplete"` - 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. + - `type: "local_shell_call"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the local shell call. Always `local_shell_call`. - - `object: "thread.message"` + - `agent: optional object { agent_name }` - The object type, which is always `thread.message`. + The agent that produced this item. - - `role: "user" or "assistant"` + - `agent_name: string` - The entity that produced the message. One of `user` or `assistant`. + The canonical name of the agent that produced this item. - - `run_id: string` + - `local_shell_call_output: object { id, output, type, 2 more }` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The output of a local shell tool call. - - `status: "in_progress" or "incomplete" or "completed"` + - `id: string` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The unique ID of the local shell tool call generated by the model. - - `thread_id: string` + - `output: string` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + A JSON string of the output of the local shell tool call. - - `event: "thread.message.in_progress"` + - `type: "local_shell_call_output"` - - `thread.message.delta: object { data, event }` + The type of the local shell tool call output. Always `local_shell_call_output`. - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + - `agent: optional object { agent_name }` - - `data: object { id, delta, object }` + The agent that produced this item. - Represents a message delta i.e. any changed fields on a message during streaming. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The identifier of the message, which can be referenced in API endpoints. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `delta: object { content, role }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The delta containing the fields that have changed on the Message. + - `"in_progress"` - - `content: optional array of unknown` + - `"completed"` - The content of the message in array of text and/or images. + - `"incomplete"` - - `role: optional "user" or "assistant"` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - The entity that produced the message. One of `user` or `assistant`. + A tool call that executes one or more shell commands in a managed environment. - - `"user"` + - `id: string` - - `"assistant"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `object: "thread.message.delta"` + - `action: object { commands, max_output_length, timeout_ms }` - The object type, which is always `thread.message.delta`. + The shell commands and limits that describe how to run the tool call. - - `event: "thread.message.delta"` + - `commands: array of string` - - `thread.message.completed: object { data, event }` + - `max_output_length: number` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + Optional maximum number of characters to return from each command. - - `data: object { id, assistant_id, attachments, 11 more }` + - `timeout_ms: number` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Optional timeout in milliseconds for the commands. - - `id: string` + - `call_id: string` - The identifier, which can be referenced in API endpoints. + The unique ID of the shell tool call generated by the model. - - `assistant_id: string` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + Represents the use of a local environment to perform shell actions. - - `attachments: array of object { file_id, tools }` + - `beta_response_local_environment: object { type }` - A list of files attached to the message, and the tools they were added to. + Represents the use of a local environment to perform shell actions. - - `completed_at: number` + - `type: "local"` - The Unix timestamp (in seconds) for when the message was completed. + The environment type. Always `local`. - - `content: array of unknown` + - `beta_response_container_reference: object { container_id, type }` - The content of the message in array of text and/or images. + Represents a container created with /v1/containers. - - `created_at: number` + - `container_id: string` - The Unix timestamp (in seconds) for when the message was created. + - `type: "container_reference"` - - `incomplete_at: number` + The environment type. Always `container_reference`. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `status: "in_progress" or "completed" or "incomplete"` - - `incomplete_details: object { reason }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - On an incomplete message, details about why the message is incomplete. + - `"in_progress"` - - `metadata: map[string]` + - `"completed"` - 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. + - `"incomplete"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "shell_call"` - - `object: "thread.message"` + The type of the item. Always `shell_call`. - The object type, which is always `thread.message`. + - `agent: optional object { agent_name }` - - `role: "user" or "assistant"` + The agent that produced this item. - The entity that produced the message. One of `user` or `assistant`. + - `agent_name: string` - - `run_id: string` + The canonical name of the agent that produced this item. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `caller: optional object { type } or object { caller_id, type }` - - `status: "in_progress" or "incomplete" or "completed"` + The execution context that produced this tool call. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `direct: object { type }` - - `thread_id: string` + - `program: object { caller_id, type }` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `caller_id: string` - - `event: "thread.message.completed"` + The call ID of the program item that produced this tool call. - - `thread.message.incomplete: object { data, event }` + - `type: "program"` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + - `created_by: optional string` - - `data: object { id, assistant_id, attachments, 11 more }` + The ID of the entity that created this tool call. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + + The output of a shell tool call that was emitted. - `id: string` - The identifier, which can be referenced in API endpoints. + The unique ID of the shell call output. Populated when this item is returned via API. - - `assistant_id: string` + - `call_id: string` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The unique ID of the shell tool call generated by the model. - - `attachments: array of object { file_id, tools }` + - `max_output_length: number` - A list of files attached to the message, and the tools they were added to. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `completed_at: number` + - `output: array of object { outcome, stderr, stdout, created_by }` - The Unix timestamp (in seconds) for when the message was completed. + An array of shell call output contents - - `content: array of unknown` + - `outcome: object { type } or object { exit_code, type }` - The content of the message in array of text and/or images. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `created_at: number` + - `timeout: object { type }` - The Unix timestamp (in seconds) for when the message was created. + Indicates that the shell call exceeded its configured time limit. - - `incomplete_at: number` + - `exit: object { exit_code, type }` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Indicates that the shell commands finished and returned an exit code. - - `incomplete_details: object { reason }` + - `exit_code: number` - On an incomplete message, details about why the message is incomplete. + Exit code from the shell process. - - `metadata: map[string]` + - `type: "exit"` - 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. + The outcome type. Always `exit`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `stderr: string` - - `object: "thread.message"` + The standard error output that was captured. - The object type, which is always `thread.message`. + - `stdout: string` - - `role: "user" or "assistant"` + The standard output that was captured. - The entity that produced the message. One of `user` or `assistant`. + - `created_by: optional string` - - `run_id: string` + The identifier of the actor that created the item. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `status: "in_progress" or "completed" or "incomplete"` - - `status: "in_progress" or "incomplete" or "completed"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"in_progress"` - - `thread_id: string` + - `"completed"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `"incomplete"` - - `event: "thread.message.incomplete"` + - `type: "shell_call_output"` - - `error_event: object { data, event }` + The type of the shell call output. Always `shell_call_output`. - Occurs when an [error](https://platform.openai.com/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. + - `agent: optional object { agent_name }` - - `data: object { code, message, param, type }` + The agent that produced this item. - - `code: string` + - `agent_name: string` - - `message: string` + The canonical name of the agent that produced this item. - - `param: string` + - `caller: optional object { type } or object { caller_id, type }` - - `type: string` + The execution context that produced this tool call. - - `event: "error"` + - `direct: object { type }` -### Assistant Tool + - `program: object { caller_id, type }` -- `assistant_tool: unknown` + - `caller_id: string` -### Code Interpreter Tool + The call ID of the program item that produced this tool call. -- `code_interpreter_tool: object { type }` + - `type: "program"` - - `type: "code_interpreter"` + - `created_by: optional string` - The type of tool being defined: `code_interpreter` + The identifier of the actor that created the item. -### File Search Tool + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` -- `file_search_tool: object { type, file_search }` + A tool call that applies file diffs by creating, deleting, or updating files. - - `type: "file_search"` + - `id: string` - The type of tool being defined: `file_search` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `file_search: optional object { max_num_results, ranking_options }` + - `call_id: string` - Overrides for the file search tool. + The unique ID of the apply patch tool call generated by the model. - - `max_num_results: optional number` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `create_file: object { diff, path, type }` - - `ranking_options: optional object { score_threshold, ranker }` + Instruction describing how to create a file via the apply_patch tool. - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `diff: string` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Diff to apply. - - `score_threshold: number` + - `path: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Path of the file to create. - - `ranker: optional "auto" or "default_2024_08_21"` + - `type: "create_file"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Create a new file with the provided diff. - - `"auto"` + - `delete_file: object { path, type }` - - `"default_2024_08_21"` + Instruction describing how to delete a file via the apply_patch tool. -### Function Tool + - `path: string` -- `function_tool: object { function, type }` + Path of the file to delete. - - `function: object { name, description, parameters, strict }` + - `type: "delete_file"` - - `name: string` + Delete the specified file. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `update_file: object { diff, path, type }` - - `description: optional string` + Instruction describing how to update a file via the apply_patch tool. - A description of what the function does, used by the model to choose when and how to call the function. + - `diff: string` - - `parameters: optional map[unknown]` + Diff to apply. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `path: string` - Omitting `parameters` defines a function with an empty parameter list. + Path of the file to update. - - `strict: optional boolean` + - `type: "update_file"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + Update an existing file with the provided diff. - - `type: "function"` + - `status: "in_progress" or "completed"` - The type of tool being defined: `function` + The status of the apply patch tool call. One of `in_progress` or `completed`. -### Message Stream Event + - `"in_progress"` -- `message_stream_event: object { data, event } or object { data, event } or object { data, event } or 2 more` + - `"completed"` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `type: "apply_patch_call"` - - `thread.message.created: object { data, event }` + The type of the item. Always `apply_patch_call`. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. + - `agent: optional object { agent_name }` - - `data: object { id, assistant_id, attachments, 11 more }` + The agent that produced this item. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The identifier, which can be referenced in API endpoints. + - `caller: optional object { type } or object { caller_id, type }` - - `assistant_id: string` + The execution context that produced this tool call. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `direct: object { type }` - - `attachments: array of object { file_id, tools }` + - `program: object { caller_id, type }` - A list of files attached to the message, and the tools they were added to. + - `caller_id: string` - - `file_id: optional string` + The call ID of the program item that produced this tool call. - The ID of the file to attach to the message. + - `type: "program"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `created_by: optional string` - The tools to add this file to. + The ID of the entity that created this tool call. - - `code_interpreter_tool: object { type }` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `type: "code_interpreter"` + The output emitted by an apply patch tool call. - The type of tool being defined: `code_interpreter` + - `id: string` - - `AssistantToolsFileSearchTypeOnly: object { type }` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `completed_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the message was completed. + The unique ID of the apply patch tool call generated by the model. - - `content: array of unknown` + - `status: "completed" or "failed"` - The content of the message in array of text and/or images. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `created_at: number` + - `"completed"` - The Unix timestamp (in seconds) for when the message was created. + - `"failed"` - - `incomplete_at: number` + - `type: "apply_patch_call_output"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The type of the item. Always `apply_patch_call_output`. - - `incomplete_details: object { reason }` + - `agent: optional object { agent_name }` - On an incomplete message, details about why the message is incomplete. + The agent that produced this item. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `agent_name: string` - The reason the message is incomplete. + The canonical name of the agent that produced this item. - - `"content_filter"` + - `caller: optional object { type } or object { caller_id, type }` - - `"max_tokens"` + The execution context that produced this tool call. - - `"run_cancelled"` + - `direct: object { type }` - - `"run_expired"` + - `program: object { caller_id, type }` - - `"run_failed"` + - `caller_id: string` - - `metadata: map[string]` + The call ID of the program item that produced this tool call. - 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. + - `type: "program"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `created_by: optional string` - - `object: "thread.message"` + The ID of the entity that created this tool call output. - The object type, which is always `thread.message`. + - `output: optional string` - - `role: "user" or "assistant"` + Optional textual output returned by the apply patch tool. - The entity that produced the message. One of `user` or `assistant`. + - `mcp_call: object { id, arguments, name, 7 more }` - - `"user"` + An invocation of a tool on an MCP server. - - `"assistant"` + - `id: string` - - `run_id: string` + The unique ID of the tool call. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `arguments: string` - - `status: "in_progress" or "incomplete" or "completed"` + A JSON string of the arguments passed to the tool. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `name: string` - - `"in_progress"` + The name of the tool that was run. - - `"incomplete"` + - `server_label: string` - - `"completed"` + The label of the MCP server running the tool. - - `thread_id: string` + - `type: "mcp_call"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The type of the item. Always `mcp_call`. - - `event: "thread.message.created"` + - `agent: optional object { agent_name }` - - `thread.message.in_progress: object { data, event }` + The agent that produced this item. - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. + - `agent_name: string` - - `data: object { id, assistant_id, attachments, 11 more }` + The canonical name of the agent that produced this item. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `approval_request_id: optional string` - - `id: string` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The identifier, which can be referenced in API endpoints. + - `error: optional string` - - `assistant_id: string` + The error from the tool call, if any. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `output: optional string` - - `attachments: array of object { file_id, tools }` + The output from the tool call. - A list of files attached to the message, and the tools they were added to. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `completed_at: number` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The Unix timestamp (in seconds) for when the message was completed. - - - `content: array of unknown` - - The content of the message in array of text and/or images. - - - `created_at: number` - - The Unix timestamp (in seconds) for when the message was created. - - - `incomplete_at: number` - - The Unix timestamp (in seconds) for when the message was marked as incomplete. - - - `incomplete_details: object { reason }` - - On an incomplete message, details about why the message is incomplete. - - - `metadata: map[string]` - - 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. - - - `object: "thread.message"` - - The object type, which is always `thread.message`. - - - `role: "user" or "assistant"` - - The entity that produced the message. One of `user` or `assistant`. - - - `run_id: string` - - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - - `status: "in_progress" or "incomplete" or "completed"` - - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - - `thread_id: string` + - `"in_progress"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `"completed"` - - `event: "thread.message.in_progress"` + - `"incomplete"` - - `thread.message.delta: object { data, event }` + - `"calling"` - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. + - `"failed"` - - `data: object { id, delta, object }` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - Represents a message delta i.e. any changed fields on a message during streaming. + A list of tools available on an MCP server. - `id: string` - The identifier of the message, which can be referenced in API endpoints. - - - `delta: object { content, role }` - - The delta containing the fields that have changed on the Message. - - - `content: optional array of unknown` - - The content of the message in array of text and/or images. - - - `role: optional "user" or "assistant"` - - The entity that produced the message. One of `user` or `assistant`. - - - `"user"` - - - `"assistant"` - - - `object: "thread.message.delta"` - - The object type, which is always `thread.message.delta`. - - - `event: "thread.message.delta"` + The unique ID of the list. - - `thread.message.completed: object { data, event }` + - `server_label: string` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. + The label of the MCP server. - - `data: object { id, assistant_id, attachments, 11 more }` + - `tools: array of object { input_schema, name, annotations, description }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + The tools available on the server. - - `id: string` + - `input_schema: unknown` - The identifier, which can be referenced in API endpoints. + The JSON schema describing the tool's input. - - `assistant_id: string` + - `name: string` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The name of the tool. - - `attachments: array of object { file_id, tools }` + - `annotations: optional unknown` - A list of files attached to the message, and the tools they were added to. + Additional annotations about the tool. - - `completed_at: number` + - `description: optional string` - The Unix timestamp (in seconds) for when the message was completed. + The description of the tool. - - `content: array of unknown` + - `type: "mcp_list_tools"` - The content of the message in array of text and/or images. + The type of the item. Always `mcp_list_tools`. - - `created_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the message was created. + The agent that produced this item. - - `incomplete_at: number` + - `agent_name: string` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The canonical name of the agent that produced this item. - - `incomplete_details: object { reason }` + - `error: optional string` - On an incomplete message, details about why the message is incomplete. + Error message if the server could not list tools. - - `metadata: map[string]` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - 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. + A request for human approval of a tool invocation. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: string` - - `object: "thread.message"` + The unique ID of the approval request. - The object type, which is always `thread.message`. + - `arguments: string` - - `role: "user" or "assistant"` + A JSON string of arguments for the tool. - The entity that produced the message. One of `user` or `assistant`. + - `name: string` - - `run_id: string` + The name of the tool to run. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `server_label: string` - - `status: "in_progress" or "incomplete" or "completed"` + The label of the MCP server making the request. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `type: "mcp_approval_request"` - - `thread_id: string` + The type of the item. Always `mcp_approval_request`. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `agent: optional object { agent_name }` - - `event: "thread.message.completed"` + The agent that produced this item. - - `thread.message.incomplete: object { data, event }` + - `agent_name: string` - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. + The canonical name of the agent that produced this item. - - `data: object { id, assistant_id, attachments, 11 more }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + A response to an MCP approval request. - `id: string` - The identifier, which can be referenced in API endpoints. - - - `assistant_id: string` - - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - - `attachments: array of object { file_id, tools }` + The unique ID of the approval response - A list of files attached to the message, and the tools they were added to. + - `approval_request_id: string` - - `completed_at: number` + The ID of the approval request being answered. - The Unix timestamp (in seconds) for when the message was completed. + - `approve: boolean` - - `content: array of unknown` + Whether the request was approved. - The content of the message in array of text and/or images. + - `type: "mcp_approval_response"` - - `created_at: number` + The type of the item. Always `mcp_approval_response`. - The Unix timestamp (in seconds) for when the message was created. + - `agent: optional object { agent_name }` - - `incomplete_at: number` + The agent that produced this item. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `agent_name: string` - - `incomplete_details: object { reason }` + The canonical name of the agent that produced this item. - On an incomplete message, details about why the message is incomplete. + - `reason: optional string` - - `metadata: map[string]` + Optional reason for the decision. - 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. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A call to a custom tool created by the model. - - `object: "thread.message"` + - `call_id: string` - The object type, which is always `thread.message`. + An identifier used to map this custom tool call to a tool call output. - - `role: "user" or "assistant"` + - `input: string` - The entity that produced the message. One of `user` or `assistant`. + The input for the custom tool call generated by the model. - - `run_id: string` + - `name: string` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The name of the custom tool being called. - - `status: "in_progress" or "incomplete" or "completed"` + - `type: "custom_tool_call"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The type of the custom tool call. Always `custom_tool_call`. - - `thread_id: string` + - `id: optional string` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The unique ID of the custom tool call in the OpenAI platform. - - `event: "thread.message.incomplete"` + - `agent: optional object { agent_name }` -### Run Step Stream Event + The agent that produced this item. -- `run_step_stream_event: object { data, event } or object { data, event } or object { data, event } or 4 more` + - `caller: optional object { type } or object { caller_id, type }` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + The execution context that produced this tool call. - - `thread.run.step.created: object { data, event }` + - `namespace: optional string` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. + The namespace of the custom tool being called. - - `data: object { id, assistant_id, cancelled_at, 13 more }` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - Represents a step in execution of a run. + The output of a custom tool call from your code, being sent back to the model. - `id: string` - The identifier of the run step, which can be referenced in API endpoints. - - - `assistant_id: string` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - - `cancelled_at: number` - - The Unix timestamp (in seconds) for when the run step was cancelled. - - - `completed_at: number` - - The Unix timestamp (in seconds) for when the run step completed. + The unique ID of the custom tool call output item. - - `created_at: number` + - `status: "in_progress" or "completed" or "incomplete"` - The Unix timestamp (in seconds) for when the run step was created. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `expired_at: number` + - `"in_progress"` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"completed"` - - `failed_at: number` + - `"incomplete"` - The Unix timestamp (in seconds) for when the run step failed. + - `created_by: optional string` - - `last_error: object { code, message }` + The identifier of the actor that created the item. - The last error associated with this run step. Will be `null` if there are no errors. + - `parallel_tool_calls: boolean` - - `code: "server_error" or "rate_limit_exceeded"` + Whether to allow the model to run tool calls in parallel. - One of `server_error` or `rate_limit_exceeded`. + - `temperature: number` - - `"server_error"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `"rate_limit_exceeded"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `message: string` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - A human-readable description of the error. + - `beta_tool_choice_options: "none" or "auto" or "required"` - - `metadata: map[string]` + Controls which (if any) tool is called by the model. - 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. + `none` means the model will not call any tool and instead generates a message. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `object: "thread.run.step"` + `required` means the model must call one or more tools. - The object type, which is always `thread.run.step`. + - `"none"` - - `run_id: string` + - `"auto"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `"required"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `beta_tool_choice_allowed: object { mode, tools, type }` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + Constrains the tools available to the model to a pre-defined set. - - `"in_progress"` + - `mode: "auto" or "required"` - - `"cancelled"` + Constrains the tools available to the model to a pre-defined set. - - `"failed"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"completed"` + `required` requires the model to call one or more of the allowed tools. - - `"expired"` + - `"auto"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `"required"` - The details of the run step. + - `tools: array of map[unknown]` - - `message_creation_step_details: object { message_creation, type }` + A list of tool definitions that the model should be allowed to call. - Details of the message creation by the run step. + For the Responses API, the list of tool definitions might look like: - - `message_creation: object { message_id }` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `message_id: string` + - `type: "allowed_tools"` - The ID of the message that was created by this run step. + Allowed tool configuration type. Always `allowed_tools`. - - `type: "message_creation"` + - `beta_tool_choice_types: object { type }` - Always `message_creation`. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `tool_calls_step_details: object { tool_calls, type }` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - Details of the tool call. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `tool_calls: array of unknown` + Allowed values are: - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `type: "tool_calls"` + - `"file_search"` - Always `tool_calls`. + - `"web_search_preview"` - - `thread_id: string` + - `"computer"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"computer_use_preview"` - - `type: "message_creation" or "tool_calls"` + - `"computer_use"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"web_search_preview_2025_03_11"` - - `"message_creation"` + - `"image_generation"` - - `"tool_calls"` + - `"code_interpreter"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `beta_tool_choice_function: object { name, type }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + Use this option to force the model to call a specific function. - - `completion_tokens: number` + - `name: string` - Number of completion tokens used over the course of the run step. + The name of the function to call. - - `prompt_tokens: number` + - `type: "function"` - Number of prompt tokens used over the course of the run step. + For function calling, the type is always `function`. - - `total_tokens: number` + - `beta_tool_choice_mcp: object { server_label, type, name }` - Total number of tokens used (prompt + completion). + Use this option to force the model to call a specific tool on a remote MCP server. - - `event: "thread.run.step.created"` + - `server_label: string` - - `thread.run.step.in_progress: object { data, event }` + The label of the MCP server to use. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `type: "mcp"` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + For MCP tools, the type is always `mcp`. - Represents a step in execution of a run. + - `name: optional string` - - `id: string` + The name of the tool to call on the server. - The identifier of the run step, which can be referenced in API endpoints. + - `beta_tool_choice_custom: object { name, type }` - - `assistant_id: string` + Use this option to force the model to call a specific custom tool. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `name: string` - - `cancelled_at: number` + The name of the custom tool to call. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `type: "custom"` - - `completed_at: number` + For custom tool calling, the type is always `custom`. - The Unix timestamp (in seconds) for when the run step completed. + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - - `created_at: number` + - `beta_tool_choice_apply_patch: object { type }` - The Unix timestamp (in seconds) for when the run step was created. + Forces the model to call the apply_patch tool when executing a tool call. - - `expired_at: number` + - `type: "apply_patch"` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The tool to call. Always `apply_patch`. - - `failed_at: number` + - `beta_tool_choice_shell: object { type }` - The Unix timestamp (in seconds) for when the run step failed. + Forces the model to call the shell tool when a tool call is required. - - `last_error: object { code, message }` + - `type: "shell"` - The last error associated with this run step. Will be `null` if there are no errors. + The tool to call. Always `shell`. - - `metadata: map[string]` + - `tools: array of BetaTool` - 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. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + We support the following categories of tools: - - `object: "thread.run.step"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - The object type, which is always `thread.run.step`. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `run_id: string` + 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). - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + 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). - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `beta_computer_tool: object { type }` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The details of the run step. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `thread_id: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `type: "message_creation" or "tool_calls"` + 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). - The type of run step, which can be either `message_creation` or `tool_calls`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `code_interpreter: object { container, type, allowed_callers }` - - `event: "thread.run.step.in_progress"` + A tool that runs Python code to help generate a response to a prompt. - - `thread.run.step.delta: object { data, event }` + - `programmatic_tool_calling: object { type }` - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. + - `image_generation: object { type, action, background, 9 more }` - - `data: object { id, delta, object }` + A tool that generates images using the GPT image models. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `local_shell: object { type }` - - `id: string` + A tool that allows the model to execute shell commands in a local environment. - The identifier of the run step, which can be referenced in API endpoints. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `delta: unknown` + A tool that allows the model to execute shell commands. - - `object: "thread.run.step.delta"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The object type, which is always `thread.run.step.delta`. + 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) - - `event: "thread.run.step.delta"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `thread.run.step.completed: object { data, event }` + Groups function/custom tools under a shared namespace. - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + Hosted or BYOT tool search configuration for deferred tools. - Represents a step in execution of a run. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `id: string` + 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). - The identifier of the run step, which can be referenced in API endpoints. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `assistant_id: string` + Allows the assistant to create, delete, or update files using unified diffs. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `top_p: number` - - `cancelled_at: number` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - The Unix timestamp (in seconds) for when the run step was cancelled. + We generally recommend altering this or `temperature` but not both. - - `completed_at: number` + - `background: optional boolean` - The Unix timestamp (in seconds) for when the run step completed. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `created_at: number` + - `completed_at: optional number` - The Unix timestamp (in seconds) for when the run step was created. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `expired_at: number` + - `conversation: optional object { id }` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `failed_at: number` + - `id: string` - The Unix timestamp (in seconds) for when the run step failed. + The unique ID of the conversation that this response was associated with. - - `last_error: object { code, message }` + - `max_output_tokens: optional number` - The last error associated with this run step. Will be `null` if there are no errors. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `metadata: map[string]` + - `max_tool_calls: optional number` - 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. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `moderation: optional object { input, output }` - - `object: "thread.run.step"` + Moderation results for the response input and output, if moderated completions were requested. - The object type, which is always `thread.run.step`. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `run_id: string` + Moderation for the response input. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + A moderation result produced for the response input or output. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `categories: map[boolean]` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The details of the run step. + - `category_applied_input_types: map[array of "text" or "image"]` - - `thread_id: string` + Which modalities of input are reflected by the score for each category. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"text"` - - `type: "message_creation" or "tool_calls"` + - `"image"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `category_scores: map[number]` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + A dictionary of moderation categories to scores. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `flagged: boolean` - - `event: "thread.run.step.completed"` + A boolean indicating whether the content was flagged by any category. - - `thread.run.step.failed: object { data, event }` + - `model: string` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. + The moderation model that produced this result. - - `data: object { id, assistant_id, cancelled_at, 13 more }` + - `type: "moderation_result"` - Represents a step in execution of a run. + The object type, which was always `moderation_result` for successful moderation results. - - `id: string` + - `error: object { code, message, type }` - The identifier of the run step, which can be referenced in API endpoints. + An error produced while attempting moderation for the response input or output. - - `assistant_id: string` + - `code: string` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + The error code. - - `cancelled_at: number` + - `message: string` - The Unix timestamp (in seconds) for when the run step was cancelled. + The error message. - - `completed_at: number` + - `type: "error"` - The Unix timestamp (in seconds) for when the run step completed. + The object type, which was always `error` for moderation failures. - - `created_at: number` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The Unix timestamp (in seconds) for when the run step was created. + Moderation for the response output. - - `expired_at: number` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + A moderation result produced for the response input or output. - - `failed_at: number` + - `categories: map[boolean]` - The Unix timestamp (in seconds) for when the run step failed. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `last_error: object { code, message }` + - `category_applied_input_types: map[array of "text" or "image"]` - The last error associated with this run step. Will be `null` if there are no errors. + Which modalities of input are reflected by the score for each category. - - `metadata: map[string]` + - `"text"` - 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. + - `"image"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `category_scores: map[number]` - - `object: "thread.run.step"` + A dictionary of moderation categories to scores. - The object type, which is always `thread.run.step`. + - `flagged: boolean` - - `run_id: string` + A boolean indicating whether the content was flagged by any category. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `model: string` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + The moderation model that produced this result. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `type: "moderation_result"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + The object type, which was always `moderation_result` for successful moderation results. - The details of the run step. + - `error: object { code, message, type }` - - `thread_id: string` + An error produced while attempting moderation for the response input or output. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `code: string` - - `type: "message_creation" or "tool_calls"` + The error code. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `message: string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The error message. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `type: "error"` - - `event: "thread.run.step.failed"` + The object type, which was always `error` for moderation failures. - - `thread.run.step.cancelled: object { data, event }` + - `previous_response_id: optional string` - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + 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`. - - `data: object { id, assistant_id, cancelled_at, 13 more }` + - `prompt: optional object { id, variables, version }` - Represents a step in execution of a run. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - The identifier of the run step, which can be referenced in API endpoints. - - - `assistant_id: string` + The unique identifier of the prompt template to use. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `cancelled_at: number` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `union_member_0: string` - - `completed_at: number` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The Unix timestamp (in seconds) for when the run step completed. + A text input to the model. - - `created_at: number` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The Unix timestamp (in seconds) for when the run step was created. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `expired_at: number` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + A file input to the model. - - `failed_at: number` + - `version: optional string` - The Unix timestamp (in seconds) for when the run step failed. + Optional version of the prompt template. - - `last_error: object { code, message }` + - `prompt_cache_key: optional string` - The last error associated with this run step. Will be `null` if there are no errors. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `metadata: map[string]` + - `prompt_cache_options: optional object { mode, ttl }` - 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. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `mode: "implicit" or "explicit"` - - `object: "thread.run.step"` + Whether implicit prompt-cache breakpoints were enabled. - The object type, which is always `thread.run.step`. + - `"implicit"` - - `run_id: string` + - `"explicit"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `ttl: "30m"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + The minimum lifetime applied to each cache breakpoint. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `"30m"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The details of the run step. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `thread_id: string` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: "message_creation" or "tool_calls"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"in_memory"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"24h"` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `event: "thread.run.step.cancelled"` + **gpt-5 and o-series models only** - - `thread.run.step.expired: object { data, event }` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `data: object { id, assistant_id, cancelled_at, 13 more }` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - Represents a step in execution of a run. + - `"auto"` - - `id: string` + - `"current_turn"` - The identifier of the run step, which can be referenced in API endpoints. + - `"all_turns"` - - `assistant_id: string` + - `effort: optional "none" or "minimal" or "low" or 4 more` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `cancelled_at: number` + - `"none"` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `"minimal"` - - `completed_at: number` + - `"low"` - The Unix timestamp (in seconds) for when the run step completed. + - `"medium"` - - `created_at: number` + - `"high"` - The Unix timestamp (in seconds) for when the run step was created. + - `"xhigh"` - - `expired_at: number` + - `"max"` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `failed_at: number` + **Deprecated:** use `summary` instead. - The Unix timestamp (in seconds) for when the run step failed. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `last_error: object { code, message }` + - `"auto"` - The last error associated with this run step. Will be `null` if there are no errors. + - `"concise"` - - `metadata: map[string]` + - `"detailed"` - 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. + - `mode: optional string or "standard" or "pro"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Controls the reasoning execution mode for the request. - - `object: "thread.run.step"` + When returned on a response, this is the effective execution mode. - The object type, which is always `thread.run.step`. + - `"standard"` - - `run_id: string` + - `"pro"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `summary: optional "auto" or "concise" or "detailed"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `"auto"` - The details of the run step. + - `"concise"` - - `thread_id: string` + - `"detailed"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `safety_identifier: optional string` - - `type: "message_creation" or "tool_calls"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The type of run step, which can be either `message_creation` or `tool_calls`. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + Specifies the processing type used for serving the request. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `event: "thread.run.step.expired"` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. -### Run Stream Event + - `"auto"` -- `run_stream_event: object { data, event } or object { data, event } or object { data, event } or 7 more` + - `"default"` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + - `"flex"` - - `thread.run.created: object { data, event }` + - `"scale"` - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. + - `"priority"` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `id: string` + - `"completed"` - The identifier, which can be referenced in API endpoints. + - `"failed"` - - `assistant_id: string` + - `"in_progress"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"cancelled"` - - `cancelled_at: number` + - `"queued"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `"incomplete"` - - `completed_at: number` + - `text: optional object { format, verbosity }` - The Unix timestamp (in seconds) for when the run was completed. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `created_at: number` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The Unix timestamp (in seconds) for when the run was created. + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - `expires_at: number` + An object specifying the format that the model must output. - The Unix timestamp (in seconds) for when the run will expire. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `failed_at: number` + The default format is `{ "type": "text" }` with no additional options. - The Unix timestamp (in seconds) for when the run failed. + **Not recommended for gpt-4o and newer models:** - - `incomplete_details: object { reason }` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `text: object { type }` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + Default response format. Used to generate text responses. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - - `"max_completion_tokens"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"max_prompt_tokens"` + - `name: string` - - `instructions: string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `schema: map[unknown]` - - `last_error: object { code, message }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The last error associated with this run. Will be `null` if there are no errors. + - `type: "json_schema"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + The type of response format being defined. Always `json_schema`. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `description: optional string` - - `"server_error"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"rate_limit_exceeded"` + - `strict: optional boolean` - - `"invalid_prompt"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `message: string` + - `json_object: object { type }` - A human-readable description of the error. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `max_completion_tokens: number` + - `verbosity: optional "low" or "medium" or "high"` - The maximum number of completion tokens specified to have been used over the course of the run. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `max_prompt_tokens: number` + - `"low"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"medium"` - - `metadata: map[string]` + - `"high"` - 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. + - `top_logprobs: optional number` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `model: string` + - `truncation: optional "auto" or "disabled"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The truncation strategy to use for the model response. - - `object: "thread.run"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The object type, which is always `thread.run`. + - `"auto"` - - `parallel_tool_calls: boolean` + - `"disabled"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `required_action: object { submit_tool_outputs, type }` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - Details on the action required to continue the run. Will be `null` if no action is required. + - `input_tokens: number` - - `submit_tool_outputs: object { tool_calls }` + The number of input tokens. - Details on the tool outputs needed for this run to continue. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `tool_calls: array of RequiredActionFunctionToolCall` + A detailed breakdown of the input tokens. - A list of the relevant tool calls. + - `cache_write_tokens: number` - - `id: string` + The number of input tokens that were written to the cache. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `cached_tokens: number` - - `function: object { arguments, name }` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The function definition. + - `output_tokens: number` - - `arguments: string` + The number of output tokens. - The arguments that the model expects you to pass to the function. + - `output_tokens_details: object { reasoning_tokens }` - - `name: string` + A detailed breakdown of the output tokens. - The name of the function. + - `reasoning_tokens: number` - - `type: "function"` + The number of reasoning tokens. - The type of tool call the output is required for. For now, this is always `function`. + - `total_tokens: number` - - `type: "submit_tool_outputs"` + The total number of tokens used. - For now, this is always `submit_tool_outputs`. + - `user: optional string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. +### Example - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). +```cli +openai beta:responses create \ + --api-key 'My API Key' +``` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. +#### Response - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "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" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "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 + }, + "user": "user-1234" +} +``` - - `union_member_0: "auto"` +## Get a model response - `auto` is the default value +`$ openai beta:responses retrieve` - - `response_format_text: object { type }` +**get** `/responses/{response_id}?beta=true` - Default response format. Used to generate text responses. +Retrieves a model response with the given ID. - - `type: "text"` +### Parameters - The type of response format being defined. Always `text`. +- `--response-id: string` - - `response_format_json_object: object { type }` + Path param: The ID of the response to retrieve. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. +- `--include: optional array of BetaResponseIncludable` - - `type: "json_object"` + Query param: Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - The type of response format being defined. Always `json_object`. +- `--include-obfuscation: optional boolean` - - `response_format_json_schema: object { json_schema, type }` + Query param: When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events + to normalize payload sizes as a mitigation to certain side-channel + attacks. These obfuscation fields are included by default, but add a + small amount of overhead to the data stream. You can set + `include_obfuscation` to false to optimize for bandwidth if you trust + the network links between your application and the OpenAI API. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). +- `--starting-after: optional number` - - `json_schema: object { name, description, schema, strict }` + Query param: The sequence number of the event after which to start streaming. - Structured Outputs configuration options, including a JSON Schema. +- `--beta: optional array of "responses_multi_agent=v1"` - - `name: string` + Header param: Optional beta features to enable for this request. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. +### Returns - - `description: optional string` +- `beta_response: object { id, created_at, error, 31 more }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `id: string` - - `schema: optional map[unknown]` + Unique identifier for this Response. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `created_at: number` - - `strict: optional boolean` + Unix timestamp (in seconds) of when this Response was created. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `error: object { code, message }` - - `type: "json_schema"` + An error object returned when the model fails to generate a Response. - The type of response format being defined. Always `json_schema`. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `started_at: number` + The error code for the response. - The Unix timestamp (in seconds) for when the run was started. + - `"server_error"` - - `status: unknown` + - `"rate_limit_exceeded"` - - `thread_id: string` + - `"invalid_prompt"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"bio_policy"` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `"vector_store_timeout"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `"invalid_image"` - - `Auto: "none" or "auto" or "required"` + - `"invalid_image_format"` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `"invalid_base64_image"` - - `"none"` + - `"invalid_image_url"` - - `"auto"` + - `"image_too_large"` - - `"required"` + - `"image_too_small"` - - `assistant_tool_choice: object { type, function }` + - `"image_parse_error"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `"image_content_policy_violation"` - - `type: "function" or "code_interpreter" or "file_search"` + - `"invalid_image_mode"` - The type of the tool. If type is `function`, the function name must be set + - `"image_file_too_large"` - - `"function"` + - `"unsupported_image_media_type"` - - `"code_interpreter"` + - `"empty_image_file"` - - `"file_search"` + - `"failed_to_download_image"` - - `function: optional object { name }` + - `"image_file_not_found"` - - `name: string` + - `message: string` - The name of the function to call. + A human-readable description of the error. - - `tools: array of unknown` + - `incomplete_details: object { reason }` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + Details about why the response is incomplete. - - `truncation_strategy: object { type, last_messages }` + - `reason: optional "max_output_tokens" or "content_filter"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The reason why the response is incomplete. - - `type: "auto" or "last_messages"` + - `"max_output_tokens"` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `"content_filter"` - - `"auto"` + - `instructions: string or array of BetaResponseInputItem` - - `"last_messages"` + A system (or developer) message inserted into the model's context. - - `last_messages: optional number` + When using 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. - The number of most recent messages from the thread when constructing the context for the run. + - `union_member_0: string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + A text input to the model, equivalent to a text input with the + `developer` role. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `Input item list: array of BetaResponseInputItem` - - `completion_tokens: number` + A list of one or many input items to the model, containing + different content types. - Number of completion tokens used over the course of the run. + - `beta_easy_input_message: object { content, role, phase, type }` - - `prompt_tokens: number` + 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. - Number of prompt tokens used over the course of the run. + - `content: string or BetaResponseInputMessageContentList` - - `total_tokens: number` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - Total number of tokens used (prompt + completion). + - `Text input: string` - - `temperature: optional number` + A text input to the model. - The sampling temperature used for this run. If not set, defaults to 1. + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - `top_p: optional number` + A list of one or many input items to the model, containing different content + types. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `event: "thread.run.created"` + A text input to the model. - - `thread.run.queued: object { data, event }` + - `text: string` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. + The text input to the model. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `type: "input_text"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The type of the input item. Always `input_text`. - - `id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The identifier, which can be referenced in API endpoints. + 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. - - `assistant_id: string` + - `mode: "explicit"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The breakpoint mode. Always `explicit`. - - `cancelled_at: number` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The Unix timestamp (in seconds) for when the run was cancelled. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `completed_at: number` + - `detail: "low" or "high" or "auto" or "original"` - The Unix timestamp (in seconds) for when the run was completed. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `created_at: number` + - `"low"` - The Unix timestamp (in seconds) for when the run was created. + - `"high"` - - `expires_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run will expire. + - `"original"` - - `failed_at: number` + - `type: "input_image"` - The Unix timestamp (in seconds) for when the run failed. + The type of the input item. Always `input_image`. - - `incomplete_details: object { reason }` + - `file_id: optional string` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The ID of the file to be sent to the model. - - `instructions: string` + - `image_url: optional string` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `last_error: object { code, message }` + - `prompt_cache_breakpoint: optional object { mode }` - The last error associated with this run. Will be `null` if there are no errors. + 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. - - `max_completion_tokens: number` + - `mode: "explicit"` - The maximum number of completion tokens specified to have been used over the course of the run. + The breakpoint mode. Always `explicit`. - - `max_prompt_tokens: number` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The maximum number of prompt tokens specified to have been used over the course of the run. + A file input to the model. - - `metadata: map[string]` + - `type: "input_file"` - 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. + The type of the input item. Always `input_file`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `detail: optional "auto" or "low" or "high"` - - `model: string` + 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`. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"auto"` - - `object: "thread.run"` + - `"low"` - The object type, which is always `thread.run`. + - `"high"` - - `parallel_tool_calls: boolean` + - `file_data: optional string` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The content of the file to be sent to the model. - - `required_action: object { submit_tool_outputs, type }` + - `file_id: optional string` - Details on the action required to continue the run. Will be `null` if no action is required. + The ID of the file to be sent to the model. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `file_url: optional string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The URL of the file to be sent to the model. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `filename: optional string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The name of the file to be sent to the model. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `prompt_cache_breakpoint: optional object { mode }` - - `started_at: number` + 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. - The Unix timestamp (in seconds) for when the run was started. + - `mode: "explicit"` - - `status: unknown` + The breakpoint mode. Always `explicit`. - - `thread_id: string` + - `role: "user" or "assistant" or "system" or "developer"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `"user"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `"assistant"` - - `tools: array of unknown` + - `"system"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"developer"` - - `truncation_strategy: object { type, last_messages }` + - `phase: optional "commentary" or "final_answer"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + 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. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"commentary"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"final_answer"` - - `temperature: optional number` + - `type: optional "message"` - The sampling temperature used for this run. If not set, defaults to 1. + The type of the message input. Always `message`. - - `top_p: optional number` + - `"message"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `message: object { content, role, agent, 2 more }` - - `event: "thread.run.queued"` + 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. - - `thread.run.in_progress: object { data, event }` + - `content: array of BetaResponseInputContent` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. + A list of one or many input items to the model, containing different content + types. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + A text input to the model. - - `id: string` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The identifier, which can be referenced in API endpoints. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `assistant_id: string` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + A file input to the model. - - `cancelled_at: number` + - `role: "user" or "system" or "developer"` - The Unix timestamp (in seconds) for when the run was cancelled. + The role of the message input. One of `user`, `system`, or `developer`. - - `completed_at: number` + - `"user"` - The Unix timestamp (in seconds) for when the run was completed. + - `"system"` - - `created_at: number` + - `"developer"` - The Unix timestamp (in seconds) for when the run was created. + - `agent: optional object { agent_name }` - - `expires_at: number` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run will expire. + - `agent_name: string` - - `failed_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run failed. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `incomplete_details: object { reason }` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"in_progress"` - - `instructions: string` + - `"completed"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"incomplete"` - - `last_error: object { code, message }` + - `type: optional "message"` - The last error associated with this run. Will be `null` if there are no errors. + The type of the message input. Always set to `message`. - - `max_completion_tokens: number` + - `"message"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `max_prompt_tokens: number` + An output message from the model. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `id: string` - - `metadata: map[string]` + The unique ID of the output message. - 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. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The content of the output message. - - `model: string` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + A text output from the model. - - `object: "thread.run"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The object type, which is always `thread.run`. + The annotations of the text output. - - `parallel_tool_calls: boolean` + - `file_citation: object { file_id, filename, index, type }` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + A citation to a file. - - `required_action: object { submit_tool_outputs, type }` + - `file_id: string` - Details on the action required to continue the run. Will be `null` if no action is required. + The ID of the file. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `filename: string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The filename of the file cited. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `index: number` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The index of the file in the list of files. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `type: "file_citation"` - - `started_at: number` + The type of the file citation. Always `file_citation`. - The Unix timestamp (in seconds) for when the run was started. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `status: unknown` + A citation for a web resource used to generate a model response. - - `thread_id: string` + - `end_index: number` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The index of the last character of the URL citation in the message. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `start_index: number` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The index of the first character of the URL citation in the message. - - `tools: array of unknown` + - `title: string` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The title of the web resource. - - `truncation_strategy: object { type, last_messages }` + - `type: "url_citation"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The type of the URL citation. Always `url_citation`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `url: string` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The URL of the web resource. - - `temperature: optional number` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - The sampling temperature used for this run. If not set, defaults to 1. + A citation for a container file used to generate a model response. - - `top_p: optional number` + - `container_id: string` - The nucleus sampling value used for this run. If not set, defaults to 1. + The ID of the container file. - - `event: "thread.run.in_progress"` + - `end_index: number` - - `thread.run.requires_action: object { data, event }` + The index of the last character of the container file citation in the message. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. + - `file_id: string` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + The ID of the file. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `filename: string` - - `id: string` + The filename of the container file cited. - The identifier, which can be referenced in API endpoints. + - `start_index: number` - - `assistant_id: string` + The index of the first character of the container file citation in the message. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `type: "container_file_citation"` - - `cancelled_at: number` + The type of the container file citation. Always `container_file_citation`. - The Unix timestamp (in seconds) for when the run was cancelled. + - `file_path: object { file_id, index, type }` - - `completed_at: number` + A path to a file. - The Unix timestamp (in seconds) for when the run was completed. + - `file_id: string` - - `created_at: number` + The ID of the file. - The Unix timestamp (in seconds) for when the run was created. + - `index: number` - - `expires_at: number` + The index of the file in the list of files. - The Unix timestamp (in seconds) for when the run will expire. + - `type: "file_path"` - - `failed_at: number` + The type of the file path. Always `file_path`. - The Unix timestamp (in seconds) for when the run failed. + - `text: string` - - `incomplete_details: object { reason }` + The text output from the model. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `type: "output_text"` - - `instructions: string` + The type of the output text. Always `output_text`. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `last_error: object { code, message }` + - `token: string` - The last error associated with this run. Will be `null` if there are no errors. + - `bytes: array of number` - - `max_completion_tokens: number` + - `logprob: number` - The maximum number of completion tokens specified to have been used over the course of the run. + - `top_logprobs: array of object { token, bytes, logprob }` - - `max_prompt_tokens: number` + - `token: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `bytes: array of number` - - `metadata: map[string]` + - `logprob: number` - 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. + - `beta_response_output_refusal: object { refusal, type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A refusal from the model. - - `model: string` + - `refusal: string` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The refusal explanation from the model. - - `object: "thread.run"` + - `type: "refusal"` - The object type, which is always `thread.run`. + The type of the refusal. Always `refusal`. - - `parallel_tool_calls: boolean` + - `role: "assistant"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The role of the output message. Always `assistant`. - - `required_action: object { submit_tool_outputs, type }` + - `status: "in_progress" or "completed" or "incomplete"` - Details on the action required to continue the run. Will be `null` if no action is required. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"in_progress"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"completed"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"incomplete"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `type: "message"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The type of the output message. Always `message`. - - `started_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the run was started. + The agent that produced this item. - - `status: unknown` + - `agent_name: string` - - `thread_id: string` + The canonical name of the agent that produced this item. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `phase: optional "commentary" or "final_answer"` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + 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. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `"commentary"` - - `tools: array of unknown` + - `"final_answer"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `truncation_strategy: object { type, last_messages }` + 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. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `id: string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The unique ID of the file search tool call. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `queries: array of string` - - `temperature: optional number` + The queries used to search for files. - The sampling temperature used for this run. If not set, defaults to 1. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `top_p: optional number` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"in_progress"` - - `event: "thread.run.requires_action"` + - `"searching"` - - `thread.run.completed: object { data, event }` + - `"completed"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. + - `"incomplete"` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `"failed"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: "file_search_call"` - - `id: string` + The type of the file search tool call. Always `file_search_call`. - The identifier, which can be referenced in API endpoints. + - `agent: optional object { agent_name }` - - `assistant_id: string` + The agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `agent_name: string` - - `cancelled_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was cancelled. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `completed_at: number` + The results of the file search tool call. - The Unix timestamp (in seconds) for when the run was completed. + - `attributes: optional map[string or number or boolean]` - - `created_at: number` + 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. - The Unix timestamp (in seconds) for when the run was created. + - `union_member_0: string` - - `expires_at: number` + - `union_member_1: number` - The Unix timestamp (in seconds) for when the run will expire. + - `union_member_2: boolean` - - `failed_at: number` + - `file_id: optional string` - The Unix timestamp (in seconds) for when the run failed. + The unique ID of the file. - - `incomplete_details: object { reason }` + - `filename: optional string` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The name of the file. - - `instructions: string` + - `score: optional number` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The relevance score of the file - a value between 0 and 1. - - `last_error: object { code, message }` + - `text: optional string` - The last error associated with this run. Will be `null` if there are no errors. + The text that was retrieved from the file. - - `max_completion_tokens: number` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - The maximum number of completion tokens specified to have been used over the course of the run. + 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. - - `max_prompt_tokens: number` + - `id: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The unique ID of the computer call. - - `metadata: map[string]` + - `call_id: string` - 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. + An identifier used when responding to the tool call with output. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `pending_safety_checks: array of object { id, code, message }` - - `model: string` + The pending safety checks for the computer call. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `id: string` - - `object: "thread.run"` + The ID of the pending safety check. - The object type, which is always `thread.run`. + - `code: optional string` - - `parallel_tool_calls: boolean` + The type of the pending safety check. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `message: optional string` - - `required_action: object { submit_tool_outputs, type }` + Details about the pending safety check. - Details on the action required to continue the run. Will be `null` if no action is required. + - `status: "in_progress" or "completed" or "incomplete"` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"in_progress"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"completed"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"incomplete"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `type: "computer_call"` - - `started_at: number` + The type of the computer call. Always `computer_call`. - The Unix timestamp (in seconds) for when the run was started. + - `"computer_call"` - - `status: unknown` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `thread_id: string` + A click action. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `click: object { button, type, x, 2 more }` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + A click action. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `button: "left" or "right" or "wheel" or 2 more` - - `tools: array of unknown` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"left"` - - `truncation_strategy: object { type, last_messages }` + - `"right"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"wheel"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"back"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"forward"` - - `temperature: optional number` + - `type: "click"` - The sampling temperature used for this run. If not set, defaults to 1. + Specifies the event type. For a click action, this property is always `click`. - - `top_p: optional number` + - `x: number` - The nucleus sampling value used for this run. If not set, defaults to 1. + The x-coordinate where the click occurred. - - `event: "thread.run.completed"` + - `y: number` - - `thread.run.incomplete: object { data, event }` + The y-coordinate where the click occurred. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. + - `keys: optional array of string` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + The keys being held while clicking. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `double_click: object { keys, type, x, y }` - - `id: string` + A double click action. - The identifier, which can be referenced in API endpoints. + - `keys: array of string` - - `assistant_id: string` + The keys being held while double-clicking. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `type: "double_click"` - - `cancelled_at: number` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The Unix timestamp (in seconds) for when the run was cancelled. + - `x: number` - - `completed_at: number` + The x-coordinate where the double click occurred. - The Unix timestamp (in seconds) for when the run was completed. + - `y: number` - - `created_at: number` + The y-coordinate where the double click occurred. - The Unix timestamp (in seconds) for when the run was created. + - `drag: object { path, type, keys }` - - `expires_at: number` + A drag action. - The Unix timestamp (in seconds) for when the run will expire. + - `path: array of object { x, y }` - - `failed_at: number` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The Unix timestamp (in seconds) for when the run failed. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `incomplete_details: object { reason }` + - `x: number` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The x-coordinate. - - `instructions: string` + - `y: number` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The y-coordinate. - - `last_error: object { code, message }` + - `type: "drag"` - The last error associated with this run. Will be `null` if there are no errors. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `max_completion_tokens: number` + - `keys: optional array of string` - The maximum number of completion tokens specified to have been used over the course of the run. + The keys being held while dragging the mouse. - - `max_prompt_tokens: number` + - `keypress: object { keys, type }` - The maximum number of prompt tokens specified to have been used over the course of the run. + A collection of keypresses the model would like to perform. - - `metadata: map[string]` + - `keys: array of string` - 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. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "keypress"` - - `model: string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `move: object { type, x, y, keys }` - - `object: "thread.run"` + A mouse move action. - The object type, which is always `thread.run`. + - `type: "move"` - - `parallel_tool_calls: boolean` + Specifies the event type. For a move action, this property is always set to `move`. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `x: number` - - `required_action: object { submit_tool_outputs, type }` + The x-coordinate to move to. - Details on the action required to continue the run. Will be `null` if no action is required. + - `y: number` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The y-coordinate to move to. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `keys: optional array of string` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The keys being held while moving the mouse. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `screenshot: object { type }` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + A screenshot action. - - `started_at: number` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The Unix timestamp (in seconds) for when the run was started. + A scroll action. - - `status: unknown` + - `scroll_x: number` - - `thread_id: string` + The horizontal scroll distance. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `scroll_y: number` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The vertical scroll distance. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `type: "scroll"` - - `tools: array of unknown` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `x: number` - - `truncation_strategy: object { type, last_messages }` + The x-coordinate where the scroll occurred. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `y: number` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The y-coordinate where the scroll occurred. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `keys: optional array of string` - - `temperature: optional number` + The keys being held while scrolling. - The sampling temperature used for this run. If not set, defaults to 1. + - `type: object { text, type }` - - `top_p: optional number` + An action to type in text. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `text: string` - - `event: "thread.run.incomplete"` + The text to type. - - `thread.run.failed: object { data, event }` + - `type: "type"` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. + Specifies the event type. For a type action, this property is always set to `type`. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `wait: object { type }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + A wait action. - - `id: string` + - `actions: optional array of BetaComputerAction` - The identifier, which can be referenced in API endpoints. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `assistant_id: string` + - `click: object { button, type, x, 2 more }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + A click action. - - `cancelled_at: number` + - `double_click: object { keys, type, x, y }` - The Unix timestamp (in seconds) for when the run was cancelled. + A double click action. - - `completed_at: number` + - `drag: object { path, type, keys }` - The Unix timestamp (in seconds) for when the run was completed. + A drag action. - - `created_at: number` + - `keypress: object { keys, type }` - The Unix timestamp (in seconds) for when the run was created. + A collection of keypresses the model would like to perform. - - `expires_at: number` + - `move: object { type, x, y, keys }` - The Unix timestamp (in seconds) for when the run will expire. + A mouse move action. - - `failed_at: number` + - `screenshot: object { type }` - The Unix timestamp (in seconds) for when the run failed. + A screenshot action. - - `incomplete_details: object { reason }` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + A scroll action. - - `instructions: string` + - `type: object { text, type }` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + An action to type in text. - - `last_error: object { code, message }` + - `wait: object { type }` - The last error associated with this run. Will be `null` if there are no errors. + A wait action. - - `max_completion_tokens: number` + - `agent: optional object { agent_name }` - The maximum number of completion tokens specified to have been used over the course of the run. + The agent that produced this item. - - `max_prompt_tokens: number` + - `agent_name: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The canonical name of the agent that produced this item. - - `metadata: map[string]` + - `computer_call_output: object { call_id, output, type, 4 more }` - 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. + The output of a computer tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `call_id: string` - - `model: string` + The ID of the computer tool call that produced the output. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `output: object { type, file_id, image_url }` - - `object: "thread.run"` + A computer screenshot image used with the computer use tool. - The object type, which is always `thread.run`. + - `type: "computer_screenshot"` - - `parallel_tool_calls: boolean` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `file_id: optional string` - - `required_action: object { submit_tool_outputs, type }` + The identifier of an uploaded file that contains the screenshot. - Details on the action required to continue the run. Will be `null` if no action is required. + - `image_url: optional string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The URL of the screenshot image. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `type: "computer_call_output"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The type of the computer tool call output. Always `computer_call_output`. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `id: optional string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The ID of the computer tool call output. - - `started_at: number` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The Unix timestamp (in seconds) for when the run was started. + The safety checks reported by the API that have been acknowledged by the developer. - - `status: unknown` + - `id: string` - - `thread_id: string` + The ID of the pending safety check. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `code: optional string` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The type of the pending safety check. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `message: optional string` - - `tools: array of unknown` + Details about the pending safety check. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `agent: optional object { agent_name }` - - `truncation_strategy: object { type, last_messages }` + The agent that produced this item. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `agent_name: string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The canonical name of the agent that produced this item. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `temperature: optional number` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The sampling temperature used for this run. If not set, defaults to 1. + - `"in_progress"` - - `top_p: optional number` + - `"completed"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"incomplete"` - - `event: "thread.run.failed"` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `thread.run.cancelling: object { data, event }` + 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. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. + - `id: string` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + The unique ID of the web search tool call. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `id: string` + 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). - The identifier, which can be referenced in API endpoints. + - `search: object { type, queries, query, sources }` - - `assistant_id: string` + Action type "search" - Performs a web search query. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `type: "search"` - - `cancelled_at: number` + The action type. - The Unix timestamp (in seconds) for when the run was cancelled. + - `queries: optional array of string` - - `completed_at: number` + The search queries. - The Unix timestamp (in seconds) for when the run was completed. + - `query: optional string` - - `created_at: number` + The search query. - The Unix timestamp (in seconds) for when the run was created. + - `sources: optional array of object { type, url }` - - `expires_at: number` + The sources used in the search. - The Unix timestamp (in seconds) for when the run will expire. + - `type: "url"` - - `failed_at: number` + The type of source. Always `url`. - The Unix timestamp (in seconds) for when the run failed. + - `url: string` - - `incomplete_details: object { reason }` + The URL of the source. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `open_page: object { type, url }` - - `instructions: string` + Action type "open_page" - Opens a specific URL from search results. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `type: "open_page"` - - `last_error: object { code, message }` + The action type. - The last error associated with this run. Will be `null` if there are no errors. + - `url: optional string` - - `max_completion_tokens: number` + The URL opened by the model. - The maximum number of completion tokens specified to have been used over the course of the run. + - `find_in_page: object { pattern, type, url }` - - `max_prompt_tokens: number` + Action type "find_in_page": Searches for a pattern within a loaded page. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `pattern: string` - - `metadata: map[string]` + The pattern or text to search for within the page. - 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. + - `type: "find_in_page"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The action type. - - `model: string` + - `url: string` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The URL of the page searched for the pattern. - - `object: "thread.run"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The object type, which is always `thread.run`. + The status of the web search tool call. - - `parallel_tool_calls: boolean` + - `"in_progress"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"searching"` - - `required_action: object { submit_tool_outputs, type }` + - `"completed"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"failed"` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `type: "web_search_call"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The type of the web search tool call. Always `web_search_call`. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `agent: optional object { agent_name }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The agent that produced this item. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `agent_name: string` - - `started_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run was started. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `status: unknown` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `thread_id: string` + - `arguments: string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + A JSON string of the arguments to pass to the function. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `call_id: string` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The unique ID of the function tool call generated by the model. - - `tools: array of unknown` + - `name: string` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The name of the function to run. - - `truncation_strategy: object { type, last_messages }` + - `type: "function_call"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The type of the function tool call. Always `function_call`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `id: optional string` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The unique ID of the function tool call. - - `temperature: optional number` + - `agent: optional object { agent_name }` - The sampling temperature used for this run. If not set, defaults to 1. + The agent that produced this item. - - `top_p: optional number` + - `agent_name: string` - The nucleus sampling value used for this run. If not set, defaults to 1. + The canonical name of the agent that produced this item. - - `event: "thread.run.cancelling"` + - `caller: optional object { type } or object { caller_id, type }` - - `thread.run.cancelled: object { data, event }` + The execution context that produced this tool call. - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. + - `direct: object { type }` - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `program: object { caller_id, type }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `caller_id: string` - - `id: string` + The call ID of the program item that produced this tool call. - The identifier, which can be referenced in API endpoints. + - `type: "program"` - - `assistant_id: string` + - `namespace: optional string` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + The namespace of the function to run. - - `cancelled_at: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The Unix timestamp (in seconds) for when the run was cancelled. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `completed_at: number` + - `"in_progress"` - The Unix timestamp (in seconds) for when the run was completed. + - `"completed"` - - `created_at: number` + - `"incomplete"` - The Unix timestamp (in seconds) for when the run was created. + - `function_call_output: object { call_id, output, type, 4 more }` - - `expires_at: number` + The output of a function tool call. - The Unix timestamp (in seconds) for when the run will expire. + - `call_id: string` - - `failed_at: number` + The unique ID of the function tool call generated by the model. - The Unix timestamp (in seconds) for when the run failed. + - `output: string or BetaResponseFunctionCallOutputItemList` - - `incomplete_details: object { reason }` + Text, image, or file output of the function tool call. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `union_member_0: string` - - `instructions: string` + A JSON string of the output of the function tool call. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - - `last_error: object { code, message }` + An array of content outputs (text, image, file) for the function tool call. - The last error associated with this run. Will be `null` if there are no errors. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `max_completion_tokens: number` + A text input to the model. - The maximum number of completion tokens specified to have been used over the course of the run. + - `text: string` - - `max_prompt_tokens: number` + The text input to the model. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: "input_text"` - - `metadata: map[string]` + The type of the input item. Always `input_text`. - 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. + - `prompt_cache_breakpoint: optional object { mode }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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. - - `model: string` + - `mode: "explicit"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The breakpoint mode. Always `explicit`. - - `object: "thread.run"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The object type, which is always `thread.run`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `parallel_tool_calls: boolean` + - `type: "input_image"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The type of the input item. Always `input_image`. - - `required_action: object { submit_tool_outputs, type }` + - `detail: optional "low" or "high" or "auto" or "original"` - Details on the action required to continue the run. Will be `null` if no action is required. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"low"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"high"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"auto"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"original"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `file_id: optional string` - - `started_at: number` + The ID of the file to be sent to the model. - The Unix timestamp (in seconds) for when the run was started. + - `image_url: optional string` - - `status: unknown` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `thread_id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + 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. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `mode: "explicit"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The breakpoint mode. Always `explicit`. - - `tools: array of unknown` + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + A file input to the model. - - `truncation_strategy: object { type, last_messages }` + - `type: "input_file"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The type of the input item. Always `input_file`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `detail: optional "auto" or "low" or "high"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + 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`. - - `temperature: optional number` + - `"auto"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"low"` - - `top_p: optional number` + - `"high"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `file_data: optional string` - - `event: "thread.run.cancelled"` + The base64-encoded data of the file to be sent to the model. - - `thread.run.expired: object { data, event }` + - `file_id: optional string` - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. + The ID of the file to be sent to the model. - - `data: object { id, assistant_id, cancelled_at, 24 more }` + - `file_url: optional string` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - The identifier, which can be referenced in API endpoints. + The name of the file to be sent to the model. - - `assistant_id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + 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. - - `cancelled_at: number` + - `mode: "explicit"` - The Unix timestamp (in seconds) for when the run was cancelled. + The breakpoint mode. Always `explicit`. - - `completed_at: number` + - `type: "function_call_output"` - The Unix timestamp (in seconds) for when the run was completed. + The type of the function tool call output. Always `function_call_output`. - - `created_at: number` + - `id: optional string` - The Unix timestamp (in seconds) for when the run was created. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `expires_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the run will expire. + The agent that produced this item. - - `failed_at: number` + - `agent_name: string` - The Unix timestamp (in seconds) for when the run failed. + The canonical name of the agent that produced this item. - - `incomplete_details: object { reason }` + - `caller: optional object { type } or object { caller_id, type }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The execution context that produced this tool call. - - `instructions: string` + - `direct: object { type }` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `program: object { caller_id, type }` - - `last_error: object { code, message }` + - `caller_id: string` - The last error associated with this run. Will be `null` if there are no errors. + The call ID of the program item that produced this tool call. - - `max_completion_tokens: number` + - `type: "program"` - The maximum number of completion tokens specified to have been used over the course of the run. + The caller type. Always `program`. - - `max_prompt_tokens: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The maximum number of prompt tokens specified to have been used over the course of the run. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `metadata: map[string]` + - `"in_progress"` - 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. + - `"completed"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"incomplete"` - - `model: string` + - `agent_message: object { author, content, recipient, 3 more }` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + A message routed between agents. - - `object: "thread.run"` + - `author: string` - The object type, which is always `thread.run`. + The sending agent identity. - - `parallel_tool_calls: boolean` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + Plaintext, image, or encrypted content sent between agents. - - `required_action: object { submit_tool_outputs, type }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - Details on the action required to continue the run. Will be `null` if no action is required. + A text input to the model. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `text: string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The text input to the model. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "input_text"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The type of the input item. Always `input_text`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `prompt_cache_breakpoint: optional object { mode }` - - `started_at: number` + 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. - The Unix timestamp (in seconds) for when the run was started. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `status: unknown` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `thread_id: string` + - `type: "input_image"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The type of the input item. Always `input_image`. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `detail: optional "low" or "high" or "auto" or "original"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `tools: array of unknown` + - `file_id: optional string` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The ID of the file to be sent to the model. - - `truncation_strategy: object { type, last_messages }` + - `image_url: optional string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `prompt_cache_breakpoint: optional object { mode }` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + 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. - - `temperature: optional number` + - `encrypted_content: object { encrypted_content, type }` - The sampling temperature used for this run. If not set, defaults to 1. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `top_p: optional number` + - `encrypted_content: string` - The nucleus sampling value used for this run. If not set, defaults to 1. + Opaque encrypted content. - - `event: "thread.run.expired"` + - `type: "encrypted_content"` -### Thread Stream Event + The type of the input item. Always `encrypted_content`. -- `thread_stream_event: object { data, event, enabled }` + - `recipient: string` - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. + The destination agent identity. - - `data: object { id, created_at, metadata, 2 more }` + - `type: "agent_message"` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + The item type. Always `agent_message`. - - `id: string` + - `id: optional string` - The identifier, which can be referenced in API endpoints. + The unique ID of this agent message item. - - `created_at: number` + - `agent: optional object { agent_name }` - The Unix timestamp (in seconds) for when the thread was created. + The agent that produced this item. - - `metadata: map[string]` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - `object: "thread"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The object type, which is always `thread`. + The multi-agent action that was executed. - - `tool_resources: object { code_interpreter, file_search }` + - `"spawn_agent"` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `"interrupt_agent"` - - `code_interpreter: optional object { file_ids }` + - `"list_agents"` - - `file_ids: optional array of string` + - `"send_message"` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `"followup_task"` - - `file_search: optional object { vector_store_ids }` + - `"wait_agent"` - - `vector_store_ids: optional array of string` + - `arguments: string` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + The action arguments as a JSON string. - - `event: "thread.created"` + - `call_id: string` - - `enabled: optional boolean` + The unique ID linking this call to its output. - Whether to enable input audio transcription. + - `type: "multi_agent_call"` -# Threads + The item type. Always `multi_agent_call`. -## Create thread + - `id: optional string` -`$ openai beta:threads create` + The unique ID of this multi-agent call. -**post** `/threads` + - `agent: optional object { agent_name }` -Create thread + The agent that produced this item. -### Parameters + - `agent_name: string` -- `--message: optional array of object { content, role, attachments, metadata }` + The canonical name of the agent that produced this item. - A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. + - `multi_agent_call_output: object { action, call_id, output, 3 more }` -- `--metadata: optional map[string]` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - 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. + The multi-agent action that produced this result. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"spawn_agent"` -- `--tool-resources: optional object { code_interpreter, file_search }` + - `"interrupt_agent"` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `"list_agents"` -### Returns + - `"send_message"` -- `thread: object { id, created_at, metadata, 2 more }` + - `"followup_task"` - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `"wait_agent"` - - `id: string` + - `call_id: string` - The identifier, which can be referenced in API endpoints. + The unique ID of the multi-agent call. - - `created_at: number` + - `output: array of object { text, type, annotations }` - The Unix timestamp (in seconds) for when the thread was created. + Text output returned by the multi-agent action. - - `metadata: map[string]` + - `text: string` - 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. + The text content. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "output_text"` - - `object: "thread"` + The content type. Always `output_text`. - The object type, which is always `thread`. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `tool_resources: object { code_interpreter, file_search }` + Citations associated with the text content. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `union_member_0: array of object { file_id, filename, index, type }` - - `code_interpreter: optional object { file_ids }` + - `file_id: string` - - `file_ids: optional array of string` + The ID of the file. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `filename: string` - - `file_search: optional object { vector_store_ids }` + The filename of the file cited. - - `vector_store_ids: optional array of string` + - `index: number` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + The index of the file in the list of files. -### Example + - `type: "file_citation"` -```cli -openai beta:threads create \ - --api-key 'My API Key' -``` + The citation type. Always `file_citation`. -#### Response + - `union_member_1: array of object { end_index, start_index, title, 2 more }` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `end_index: number` -## Create thread and run + The index of the last character of the citation in the message. -`$ openai beta:threads create-and-run` + - `start_index: number` -**post** `/threads/runs` + The index of the first character of the citation in the message. -Create thread and run + - `title: string` -### Parameters + The title of the cited resource. -- `--assistant-id: string` + - `type: "url_citation"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + The citation type. Always `url_citation`. -- `--instructions: optional string` + - `url: string` - Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. + The URL of the cited resource. -- `--max-completion-tokens: optional number` + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `container_id: string` -- `--max-prompt-tokens: optional number` + The ID of the container. - The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `end_index: number` -- `--metadata: optional map[string]` + The index of the last character of the citation in the message. - 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. + - `file_id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The ID of the container file. -- `--model: optional string or ChatModel` + - `filename: string` - The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + The filename of the container file cited. -- `--parallel-tool-calls: optional boolean` + - `start_index: number` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The index of the first character of the citation in the message. -- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `type: "container_file_citation"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The citation type. Always `container_file_citation`. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "multi_agent_call_output"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The item type. Always `multi_agent_call_output`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `id: optional string` -- `--temperature: optional number` + The unique ID of this multi-agent call output. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `agent: optional object { agent_name }` -- `--thread: optional object { messages, metadata, tool_resources }` + The agent that produced this item. - Options to create a new thread. If no thread is provided when running a - request, an empty thread will be created. + - `agent_name: string` -- `--tool-choice: optional "none" or "auto" or "required" or AssistantToolChoice` + The canonical name of the agent that produced this item. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `tool_search_call: object { arguments, type, id, 4 more }` -- `--tool-resources: optional object { code_interpreter, file_search }` + - `arguments: unknown` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The arguments supplied to the tool search call. -- `--tool: optional array of unknown` + - `type: "tool_search_call"` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + The item type. Always `tool_search_call`. -- `--top-p: optional number` + - `id: optional string` - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + The unique ID of this tool search call. - We generally recommend altering this or temperature but not both. + - `agent: optional object { agent_name }` -- `--truncation-strategy: optional object { type, last_messages }` + The agent that produced this item. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `agent_name: string` -### Returns + The canonical name of the agent that produced this item. -- `run: object { id, assistant_id, cancelled_at, 24 more }` + - `call_id: optional string` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + The unique ID of the tool search call generated by the model. - - `id: string` + - `execution: optional "server" or "client"` - The identifier, which can be referenced in API endpoints. + Whether tool search was executed by the server or by the client. - - `assistant_id: string` + - `"server"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"client"` - - `cancelled_at: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The Unix timestamp (in seconds) for when the run was cancelled. + The status of the tool search call. - - `completed_at: number` + - `"in_progress"` - The Unix timestamp (in seconds) for when the run was completed. + - `"completed"` - - `created_at: number` + - `"incomplete"` - The Unix timestamp (in seconds) for when the run was created. + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `expires_at: number` + - `tools: array of BetaTool` - The Unix timestamp (in seconds) for when the run will expire. + The loaded tool definitions returned by the tool search output. - - `failed_at: number` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The Unix timestamp (in seconds) for when the run failed. + 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). - - `incomplete_details: object { reason }` + - `name: string` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The name of the function to call. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `parameters: map[unknown]` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + A JSON schema object describing the parameters of the function. - - `"max_completion_tokens"` + - `strict: boolean` - - `"max_prompt_tokens"` + Whether strict parameter validation is enforced for this function tool. - - `instructions: string` + - `type: "function"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the function tool. Always `function`. - - `last_error: object { code, message }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The last error associated with this run. Will be `null` if there are no errors. + The tool invocation context(s). - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"direct"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"programmatic"` - - `"server_error"` + - `defer_loading: optional boolean` - - `"rate_limit_exceeded"` + Whether this function is deferred and loaded via tool search. - - `"invalid_prompt"` + - `description: optional string` - - `message: string` + A description of the function. Used by the model to determine whether or not to call the function. - A human-readable description of the error. + - `output_schema: optional map[unknown]` - - `max_completion_tokens: number` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The maximum number of completion tokens specified to have been used over the course of the run. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `max_prompt_tokens: number` + 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). - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: "file_search"` - - `metadata: map[string]` + The type of the file search tool. Always `file_search`. - 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. + - `vector_store_ids: array of string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The IDs of the vector stores to search. - - `model: string` + - `filters: optional object { key, type, value } or object { filters, type }` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + A filter to apply. - - `object: "thread.run"` + - `Comparison Filter: object { key, type, value }` - The object type, which is always `thread.run`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `parallel_tool_calls: boolean` + - `key: string` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The key to compare against the value. - - `required_action: object { submit_tool_outputs, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - Details on the action required to continue the run. Will be `null` if no action is required. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `submit_tool_outputs: object { tool_calls }` + - `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 - Details on the tool outputs needed for this run to continue. + - `"eq"` - - `tool_calls: array of RequiredActionFunctionToolCall` + - `"ne"` - A list of the relevant tool calls. + - `"gt"` - - `id: string` + - `"gte"` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `"lt"` - - `function: object { arguments, name }` + - `"lte"` - The function definition. + - `"in"` - - `arguments: string` + - `"nin"` - The arguments that the model expects you to pass to the function. + - `value: string or number or boolean or array of string or number` - - `name: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The name of the function. + - `union_member_0: string` - - `type: "function"` + - `union_member_1: number` - The type of tool call the output is required for. For now, this is always `function`. + - `union_member_2: boolean` - - `type: "submit_tool_outputs"` + - `union_member_3: array of string or number` - For now, this is always `submit_tool_outputs`. + - `union_member_0: string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `union_member_1: number` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `Compound Filter: object { filters, type }` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + Combine multiple filters using `and` or `or`. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `filters: array of object { key, type, value } or unknown` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `union_member_0: "auto"` + - `Comparison Filter: object { key, type, value }` - `auto` is the default value + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `response_format_text: object { type }` + - `key: string` - Default response format. Used to generate text responses. + The key to compare against the value. - - `type: "text"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of response format being defined. Always `text`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `response_format_json_object: object { type }` + - `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 - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `"eq"` - - `type: "json_object"` + - `"ne"` - The type of response format being defined. Always `json_object`. + - `"gt"` - - `response_format_json_schema: object { json_schema, type }` + - `"gte"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"lt"` - - `json_schema: object { name, description, schema, strict }` + - `"lte"` - Structured Outputs configuration options, including a JSON Schema. + - `"in"` - - `name: string` + - `"nin"` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `value: string or number or boolean or array of string or number` - - `description: optional string` + The value to compare against the attribute key; supports string, number, or boolean types. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `union_member_0: string` - - `schema: optional map[unknown]` + - `union_member_1: number` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `union_member_2: boolean` - - `strict: optional boolean` + - `union_member_3: array of string or number` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `union_member_0: string` - - `type: "json_schema"` + - `union_member_1: number` - The type of response format being defined. Always `json_schema`. + - `union_member_1: unknown` - - `started_at: number` + - `type: "and" or "or"` - The Unix timestamp (in seconds) for when the run was started. + Type of operation: `and` or `or`. - - `status: unknown` + - `"and"` - - `thread_id: string` + - `"or"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `max_num_results: optional number` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `Auto: "none" or "auto" or "required"` + Ranking options for search. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"none"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"auto"` + - `embedding_weight: number` - - `"required"` + The weight of the embedding in the reciprocal ranking fusion. - - `assistant_tool_choice: object { type, function }` + - `text_weight: number` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The weight of the text in the reciprocal ranking fusion. - - `type: "function" or "code_interpreter" or "file_search"` + - `ranker: optional "auto" or "default-2024-11-15"` - The type of the tool. If type is `function`, the function name must be set + The ranker to use for the file search. - - `"function"` + - `"auto"` - - `"code_interpreter"` + - `"default-2024-11-15"` - - `"file_search"` + - `score_threshold: optional number` - - `function: optional object { name }` + 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. - - `name: string` + - `beta_computer_tool: object { type }` - The name of the function to call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `tools: array of unknown` + - `type: "computer"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the computer tool. Always `computer`. - - `truncation_strategy: object { type, last_messages }` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "auto" or "last_messages"` + - `display_height: number` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + The height of the computer display. - - `"auto"` + - `display_width: number` - - `"last_messages"` + The width of the computer display. - - `last_messages: optional number` + - `environment: "windows" or "mac" or "linux" or 2 more` - The number of most recent messages from the thread when constructing the context for the run. + The type of computer environment to control. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"windows"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"mac"` - - `completion_tokens: number` + - `"linux"` - Number of completion tokens used over the course of the run. + - `"ubuntu"` - - `prompt_tokens: number` + - `"browser"` - Number of prompt tokens used over the course of the run. + - `type: "computer_use_preview"` - - `total_tokens: number` + The type of the computer use tool. Always `computer_use_preview`. - Total number of tokens used (prompt + completion). + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `temperature: optional number` + 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). - The sampling temperature used for this run. If not set, defaults to 1. + - `type: "web_search" or "web_search_2025_08_26"` - - `top_p: optional number` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"web_search"` -### Example + - `"web_search_2025_08_26"` -```cli -openai beta:threads create-and-run \ - --api-key 'My API Key' \ - --assistant-id assistant_id -``` + - `filters: optional object { allowed_domains }` -#### Response + Filters for the search. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `allowed_domains: optional array of string` -## Retrieve thread + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. -`$ openai beta:threads retrieve` + Example: `["pubmed.ncbi.nlm.nih.gov"]` -**get** `/threads/{thread_id}` + - `search_context_size: optional "low" or "medium" or "high"` -Retrieve thread + 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. -### Parameters + - `"low"` -- `--thread-id: string` + - `"medium"` - The ID of the thread to retrieve. + - `"high"` -### Returns + - `user_location: optional object { city, country, region, 2 more }` -- `thread: object { id, created_at, metadata, 2 more }` + The approximate location of the user. - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `city: optional string` - - `id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The identifier, which can be referenced in API endpoints. + - `country: optional string` - - `created_at: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The Unix timestamp (in seconds) for when the thread was created. + - `region: optional string` - - `metadata: map[string]` + Free text input for the region of the user, e.g. `California`. - 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. + - `timezone: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `object: "thread"` + - `type: optional "approximate"` - The object type, which is always `thread`. + The type of location approximation. Always `approximate`. - - `tool_resources: object { code_interpreter, file_search }` + - `"approximate"` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `code_interpreter: optional object { file_ids }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `file_ids: optional array of string` + - `server_label: string` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + A label for this MCP server, used to identify it in tool calls. - - `file_search: optional object { vector_store_ids }` + - `type: "mcp"` - - `vector_store_ids: optional array of string` + The type of the MCP tool. Always `mcp`. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `allowed_callers: optional array of "direct" or "programmatic"` -### Example + The tool invocation context(s). -```cli -openai beta:threads retrieve \ - --api-key 'My API Key' \ - --thread-id thread_id -``` + - `"direct"` -#### Response + - `"programmatic"` -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `allowed_tools: optional array of string or object { read_only, tool_names }` -## Modify thread + List of allowed tool names or a filter object. -`$ openai beta:threads update` + - `MCP allowed tools: array of string` -**post** `/threads/{thread_id}` + A string array of allowed tool names -Modify thread + - `MCP tool filter: object { read_only, tool_names }` -### Parameters + A filter object to specify which tools are allowed. -- `--thread-id: string` + - `read_only: optional boolean` - The ID of the thread to modify. Only the `metadata` can be modified. + 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. -- `--metadata: optional map[string]` + - `tool_names: optional array of string` - 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. + List of allowed tool names. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `authorization: optional string` -- `--tool-resources: optional object { code_interpreter, file_search }` + 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. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` -### Returns + 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). -- `thread: object { id, created_at, metadata, 2 more }` + Currently supported `connector_id` values are: - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - 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` - - `id: string` + - `"connector_dropbox"` - The identifier, which can be referenced in API endpoints. + - `"connector_gmail"` - - `created_at: number` + - `"connector_googlecalendar"` - The Unix timestamp (in seconds) for when the thread was created. + - `"connector_googledrive"` - - `metadata: map[string]` + - `"connector_microsoftteams"` - 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. + - `"connector_outlookcalendar"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"connector_outlookemail"` - - `object: "thread"` + - `"connector_sharepoint"` - The object type, which is always `thread`. + - `defer_loading: optional boolean` - - `tool_resources: object { code_interpreter, file_search }` + Whether this MCP tool is deferred and discovered via tool search. - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `headers: optional map[string]` - - `code_interpreter: optional object { file_ids }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `file_ids: optional array of string` + - `require_approval: optional object { always, never } or "always" or "never"` - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + Specify which of the MCP server's tools require approval. - - `file_search: optional object { vector_store_ids }` + - `MCP tool approval filter: object { always, never }` - - `vector_store_ids: optional array of string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + - `always: optional object { read_only, tool_names }` -### Example + A filter object to specify which tools are allowed. -```cli -openai beta:threads update \ - --api-key 'My API Key' \ - --thread-id thread_id -``` + - `read_only: optional boolean` -#### Response + 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. -```json -{ - "id": "id", - "created_at": 0, - "metadata": { - "foo": "string" - }, - "object": "thread", - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - } -} -``` + - `tool_names: optional array of string` -## Delete thread + List of allowed tool names. -`$ openai beta:threads delete` + - `never: optional object { read_only, tool_names }` -**delete** `/threads/{thread_id}` + A filter object to specify which tools are allowed. -Delete thread + - `read_only: optional boolean` -### Parameters + 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. -- `--thread-id: string` + - `tool_names: optional array of string` - The ID of the thread to delete. + List of allowed tool names. -### Returns + - `MCP tool approval setting: "always" or "never"` -- `thread_deleted: object { id, deleted, object }` + 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. - - `id: string` + - `"always"` - - `deleted: boolean` + - `"never"` - - `object: "thread.deleted"` + - `server_description: optional string` -### Example + Optional description of the MCP server, used to provide more context. -```cli -openai beta:threads delete \ - --api-key 'My API Key' \ - --thread-id thread_id -``` + - `server_url: optional string` -#### Response + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. -```json -{ - "id": "id", - "deleted": true, - "object": "thread.deleted" -} -``` + - `tunnel_id: optional string` -## Domain Types + 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. -### Assistant Response Format Option + - `code_interpreter: object { container, type, allowed_callers }` -- `assistant_response_format_option: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + A tool that runs Python code to help generate a response to a prompt. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + 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. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `union_member_0: string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The container ID. - - `union_member_0: "auto"` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - `auto` is the default value + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `response_format_text: object { type }` + - `type: "auto"` - Default response format. Used to generate text responses. + Always `auto`. - - `type: "text"` + - `file_ids: optional array of string` - The type of response format being defined. Always `text`. + An optional list of uploaded files to make available to your code. - - `response_format_json_object: object { type }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The memory limit for the code interpreter container. - - `type: "json_object"` + - `"1g"` - The type of response format being defined. Always `json_object`. + - `"4g"` - - `response_format_json_schema: object { json_schema, type }` + - `"16g"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"64g"` - - `json_schema: object { name, description, schema, strict }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Structured Outputs configuration options, including a JSON Schema. + Network access policy for the container. - - `name: string` + - `beta_container_network_policy_disabled: object { type }` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `type: "disabled"` - - `description: optional string` + Disable outbound network access. Always `disabled`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `schema: optional map[unknown]` + - `allowed_domains: array of string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A list of allowed domains when type is `allowlist`. - - `strict: optional boolean` + - `type: "allowlist"` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "json_schema"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The type of response format being defined. Always `json_schema`. + Optional domain-scoped secrets for allowlisted domains. -### Assistant Tool Choice + - `domain: string` -- `assistant_tool_choice: object { type, function }` + The domain associated with the secret. - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `name: string` - - `type: "function" or "code_interpreter" or "file_search"` + The name of the secret to inject for the domain. - The type of the tool. If type is `function`, the function name must be set + - `value: string` - - `"function"` + The secret value to inject for the domain. - - `"code_interpreter"` + - `type: "code_interpreter"` - - `"file_search"` + The type of the code interpreter tool. Always `code_interpreter`. - - `function: optional object { name }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: string` + The tool invocation context(s). - The name of the function to call. + - `"direct"` -### Assistant Tool Choice Function + - `"programmatic"` -- `assistant_tool_choice_function: object { name }` + - `programmatic_tool_calling: object { type }` - - `name: string` + - `image_generation: object { type, action, background, 9 more }` - The name of the function to call. + A tool that generates images using the GPT image models. -### Assistant Tool Choice Option + - `type: "image_generation"` -- `assistant_tool_choice_option: "none" or "auto" or "required" or AssistantToolChoice` + The type of the image generation tool. Always `image_generation`. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `action: optional "generate" or "edit" or "auto"` - - `Auto: "none" or "auto" or "required"` + Whether to generate a new image or edit an existing image. Default: `auto`. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `"generate"` - - `"none"` + - `"edit"` - `"auto"` - - `"required"` + - `background: optional "transparent" or "opaque" or "auto"` - - `assistant_tool_choice: object { type, function }` + 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. - Specifies a tool the model should use. Use to force the model to call a specific tool. + `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. - - `type: "function" or "code_interpreter" or "file_search"` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - The type of the tool. If type is `function`, the function name must be set + - `"transparent"` - - `"function"` + - `"opaque"` - - `"code_interpreter"` + - `"auto"` - - `"file_search"` + - `input_fidelity: optional "high" or "low"` - - `function: optional object { name }` + 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`. - - `name: string` + - `"high"` - The name of the function to call. + - `"low"` -### Thread + - `input_image_mask: optional object { file_id, image_url }` -- `thread: object { id, created_at, metadata, 2 more }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). + - `file_id: optional string` - - `id: string` + File ID for the mask image. - The identifier, which can be referenced in API endpoints. + - `image_url: optional string` - - `created_at: number` + Base64-encoded mask image. - The Unix timestamp (in seconds) for when the thread was created. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `metadata: map[string]` + The image generation model to use. Default: `gpt-image-1`. - 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. + - `"gpt-image-1"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"gpt-image-1-mini"` - - `object: "thread"` + - `"gpt-image-2"` - The object type, which is always `thread`. + - `"gpt-image-2-2026-04-21"` - - `tool_resources: object { code_interpreter, file_search }` + - `"gpt-image-1.5"` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `"chatgpt-image-latest"` - - `code_interpreter: optional object { file_ids }` + - `moderation: optional "auto" or "low"` - - `file_ids: optional array of string` + Moderation level for the generated image. Default: `auto`. - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `"auto"` - - `file_search: optional object { vector_store_ids }` + - `"low"` - - `vector_store_ids: optional array of string` + - `output_compression: optional number` - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + Compression level for the output image. Default: 100. -### Thread Deleted + - `output_format: optional "png" or "webp" or "jpeg"` -- `thread_deleted: object { id, deleted, object }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `id: string` + - `"png"` - - `deleted: boolean` + - `"webp"` - - `object: "thread.deleted"` + - `"jpeg"` -# Runs + - `partial_images: optional number` -## List runs + Number of partial images to generate in streaming mode, from 0 (default value) to 3. -`$ openai beta:threads:runs list` + - `quality: optional "low" or "medium" or "high" or "auto"` -**get** `/threads/{thread_id}/runs` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. -List runs + - `"low"` -### Parameters + - `"medium"` -- `--thread-id: string` + - `"high"` - The ID of the thread the run belongs to. + - `"auto"` -- `--after: optional string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + 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`. -- `--before: optional string` + - `"1024x1024"` - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `"1024x1536"` -- `--limit: optional number` + - `"1536x1024"` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `"auto"` -- `--order: optional "asc" or "desc"` + - `local_shell: object { type }` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + A tool that allows the model to execute shell commands in a local environment. -### Returns + - `beta_function_shell_tool: object { type, allowed_callers, environment }` -- `ListRunsResponse: object { data, first_id, has_more, 2 more }` + A tool that allows the model to execute shell commands. - - `data: array of Run` + - `type: "shell"` - - `id: string` + The type of the shell tool. Always `shell`. - The identifier, which can be referenced in API endpoints. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `assistant_id: string` + The tool invocation context(s). - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"direct"` - - `cancelled_at: number` + - `"programmatic"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `completed_at: number` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - The Unix timestamp (in seconds) for when the run was completed. + - `type: "container_auto"` - - `created_at: number` + Automatically creates a container for this request - The Unix timestamp (in seconds) for when the run was created. + - `file_ids: optional array of string` - - `expires_at: number` + An optional list of uploaded files to make available to your code. - The Unix timestamp (in seconds) for when the run will expire. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `failed_at: number` + The memory limit for the container. - The Unix timestamp (in seconds) for when the run failed. + - `"1g"` - - `incomplete_details: object { reason }` + - `"4g"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"16g"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"64g"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"max_completion_tokens"` + Network access policy for the container. - - `"max_prompt_tokens"` + - `beta_container_network_policy_disabled: object { type }` - - `instructions: string` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `last_error: object { code, message }` + An optional list of skills referenced by id or inline data. - The last error associated with this run. Will be `null` if there are no errors. + - `beta_skill_reference: object { skill_id, type, version }` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `skill_id: string` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The ID of the referenced skill. - - `"server_error"` + - `type: "skill_reference"` - - `"rate_limit_exceeded"` + References a skill created with the /v1/skills endpoint. - - `"invalid_prompt"` + - `version: optional string` - - `message: string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A human-readable description of the error. + - `beta_inline_skill: object { description, name, source, type }` - - `max_completion_tokens: number` + - `description: string` - The maximum number of completion tokens specified to have been used over the course of the run. + The description of the skill. - - `max_prompt_tokens: number` + - `name: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The name of the skill. - - `metadata: map[string]` + - `source: object { data, media_type, type }` - 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. + Inline skill payload - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `data: string` - - `model: string` + Base64-encoded skill zip bundle. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `media_type: "application/zip"` - - `object: "thread.run"` + The media type of the inline skill payload. Must be `application/zip`. - The object type, which is always `thread.run`. + - `type: "base64"` - - `parallel_tool_calls: boolean` + The type of the inline skill source. Must be `base64`. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `type: "inline"` - - `required_action: object { submit_tool_outputs, type }` + Defines an inline skill for this request. - Details on the action required to continue the run. Will be `null` if no action is required. + - `beta_local_environment: object { type, skills }` - - `submit_tool_outputs: object { tool_calls }` + - `type: "local"` - Details on the tool outputs needed for this run to continue. + Use a local computer environment. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `skills: optional array of BetaLocalSkill` - A list of the relevant tool calls. + An optional list of skills. - - `id: string` + - `description: string` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The description of the skill. - - `function: object { arguments, name }` + - `name: string` - The function definition. + The name of the skill. - - `arguments: string` + - `path: string` - The arguments that the model expects you to pass to the function. + The path to the directory containing the skill. - - `name: string` + - `beta_container_reference: object { container_id, type }` - The name of the function. + - `container_id: string` - - `type: "function"` + The ID of the referenced container. - The type of tool call the output is required for. For now, this is always `function`. + - `type: "container_reference"` - - `type: "submit_tool_outputs"` + References a container created with the /v1/containers endpoint - For now, this is always `submit_tool_outputs`. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + 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) - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `name: string` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The name of the custom tool, used to identify it in tool calls. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `type: "custom"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The type of the custom tool. Always `custom`. - - `union_member_0: "auto"` + - `allowed_callers: optional array of "direct" or "programmatic"` - `auto` is the default value + The tool invocation context(s). - - `response_format_text: object { type }` + - `"direct"` - Default response format. Used to generate text responses. + - `"programmatic"` - - `type: "text"` + - `defer_loading: optional boolean` - The type of response format being defined. Always `text`. + Whether this tool should be deferred and discovered via tool search. - - `response_format_json_object: object { type }` + - `description: optional string` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Optional description of the custom tool, used to provide more context. - - `type: "json_object"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of response format being defined. Always `json_object`. + The input format for the custom tool. Default is unconstrained text. - - `response_format_json_schema: object { json_schema, type }` + - `text: object { type }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + Unconstrained free-form text. - - `json_schema: object { name, description, schema, strict }` + - `grammar: object { definition, syntax, type }` - Structured Outputs configuration options, including a JSON Schema. + A grammar defined by the user. - - `name: string` + - `definition: string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The grammar definition. - - `description: optional string` + - `syntax: "lark" or "regex"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The syntax of the grammar definition. One of `lark` or `regex`. - - `schema: optional map[unknown]` + - `"lark"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"regex"` - - `strict: optional boolean` + - `type: "grammar"` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + Grammar format. Always `grammar`. - - `type: "json_schema"` + - `beta_namespace_tool: object { description, name, tools, type }` - The type of response format being defined. Always `json_schema`. + Groups function/custom tools under a shared namespace. - - `started_at: number` + - `description: string` - The Unix timestamp (in seconds) for when the run was started. + A description of the namespace shown to the model. - - `status: unknown` + - `name: string` - - `thread_id: string` + The namespace name used in tool calls (for example, `crm`). - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The function/custom tools available inside this namespace. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `function: object { name, type, allowed_callers, 5 more }` - - `Auto: "none" or "auto" or "required"` + - `name: string` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `type: "function"` - - `"none"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"auto"` + The tool invocation context(s). - - `"required"` + - `"direct"` - - `assistant_tool_choice: object { type, function }` + - `"programmatic"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `defer_loading: optional boolean` - - `type: "function" or "code_interpreter" or "file_search"` + Whether this function should be deferred and discovered via tool search. - The type of the tool. If type is `function`, the function name must be set + - `description: optional string` - - `"function"` + - `output_schema: optional map[unknown]` - - `"code_interpreter"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"file_search"` + - `parameters: optional unknown` - - `function: optional object { name }` + - `strict: optional boolean` - - `name: string` + 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. - The name of the function to call. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `tools: array of unknown` + 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) - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `name: string` - - `truncation_strategy: object { type, last_messages }` + The name of the custom tool, used to identify it in tool calls. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: "custom"` - - `type: "auto" or "last_messages"` + The type of the custom tool. Always `custom`. - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"auto"` + The tool invocation context(s). - - `"last_messages"` + - `defer_loading: optional boolean` - - `last_messages: optional number` + Whether this tool should be deferred and discovered via tool search. - The number of most recent messages from the thread when constructing the context for the run. + - `description: optional string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + Optional description of the custom tool, used to provide more context. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `format: optional object { type } or object { definition, syntax, type }` - - `completion_tokens: number` + The input format for the custom tool. Default is unconstrained text. - Number of completion tokens used over the course of the run. + - `type: "namespace"` - - `prompt_tokens: number` + The type of the tool. Always `namespace`. - Number of prompt tokens used over the course of the run. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `total_tokens: number` + Hosted or BYOT tool search configuration for deferred tools. - Total number of tokens used (prompt + completion). + - `type: "tool_search"` - - `temperature: optional number` + The type of the tool. Always `tool_search`. - The sampling temperature used for this run. If not set, defaults to 1. + - `description: optional string` - - `top_p: optional number` + Description shown to the model for a client-executed tool search tool. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `execution: optional "server" or "client"` - - `first_id: string` + Whether tool search is executed by the server or by the client. - - `has_more: boolean` + - `"server"` - - `last_id: string` + - `"client"` - - `object: string` + - `parameters: optional unknown` -### Example + Parameter schema for a client-executed tool search tool. -```cli -openai beta:threads:runs list \ - --api-key 'My API Key' \ - --thread-id thread_id -``` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` -#### Response + 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). -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 - } - ], - "first_id": "run_abc123", - "has_more": false, - "last_id": "run_abc456", - "object": "list" -} -``` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` -## Create run + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. -`$ openai beta:threads:runs create` + - `"web_search_preview"` -**post** `/threads/{thread_id}/runs` + - `"web_search_preview_2025_03_11"` -Create run + - `search_content_types: optional array of "text" or "image"` -### Parameters + - `"text"` -- `--thread-id: string` + - `"image"` - Path param: The ID of the thread to run. + - `search_context_size: optional "low" or "medium" or "high"` -- `--assistant-id: string` + 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. - Body param: The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. + - `"low"` -- `--include: optional array of RunStepInclude` + - `"medium"` - Query param: A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + - `"high"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `user_location: optional object { type, city, country, 2 more }` -- `--additional-instructions: optional string` + The user's location. - Body param: Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. + - `type: "approximate"` -- `--additional-message: optional array of object { content, role, attachments, metadata }` + The type of location approximation. Always `approximate`. - Body param: Adds additional messages to the thread before creating the run. + - `city: optional string` -- `--instructions: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - Body param: Overrides the [instructions](https://platform.openai.com/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. + - `country: optional string` -- `--max-completion-tokens: optional number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Body param: The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `region: optional string` -- `--max-prompt-tokens: optional number` + Free text input for the region of the user, e.g. `California`. - Body param: The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `timezone: optional string` -- `--metadata: optional map[string]` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Body param: 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. + - `beta_apply_patch_tool: object { type, allowed_callers }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Allows the assistant to create, delete, or update files using unified diffs. -- `--model: optional string or ChatModel` + - `type: "apply_patch"` - Body param: The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + The type of the tool. Always `apply_patch`. -- `--parallel-tool-calls: optional boolean` + - `allowed_callers: optional array of "direct" or "programmatic"` - Body param: Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The tool invocation context(s). -- `--reasoning-effort: optional "none" or "minimal" or "low" or 4 more` + - `"direct"` - Body param: Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"programmatic"` -- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `type: "tool_search_output"` - Body param: Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The item type. Always `tool_search_output`. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `id: optional string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The unique ID of this tool search output. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `agent: optional object { agent_name }` -- `--temperature: optional number` + The agent that produced this item. - Body param: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + - `agent_name: string` -- `--tool-choice: optional "none" or "auto" or "required" or AssistantToolChoice` + The canonical name of the agent that produced this item. - Body param: Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `call_id: optional string` -- `--tool: optional array of unknown` + The unique ID of the tool search call generated by the model. - Body param: Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + - `execution: optional "server" or "client"` -- `--top-p: optional number` + Whether tool search was executed by the server or by the client. - Body param: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. + - `"server"` - We generally recommend altering this or temperature but not both. + - `"client"` -- `--truncation-strategy: optional object { type, last_messages }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Body param: Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The status of the tool search output. -### Returns + - `"in_progress"` -- `run: object { id, assistant_id, cancelled_at, 24 more }` + - `"completed"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"incomplete"` - - `id: string` + - `additional_tools: object { role, tools, type, 2 more }` - The identifier, which can be referenced in API endpoints. + - `role: "developer"` - - `assistant_id: string` + The role that provided the additional tools. Only `developer` is supported. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `tools: array of BetaTool` - - `cancelled_at: number` + A list of additional tools made available at this item. - The Unix timestamp (in seconds) for when the run was cancelled. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `completed_at: number` + 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). - The Unix timestamp (in seconds) for when the run was completed. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `created_at: number` + 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). - The Unix timestamp (in seconds) for when the run was created. + - `beta_computer_tool: object { type }` - - `expires_at: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The Unix timestamp (in seconds) for when the run will expire. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `failed_at: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The Unix timestamp (in seconds) for when the run failed. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `incomplete_details: object { reason }` + 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). - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `code_interpreter: object { container, type, allowed_callers }` - - `"max_completion_tokens"` + A tool that runs Python code to help generate a response to a prompt. - - `"max_prompt_tokens"` + - `programmatic_tool_calling: object { type }` - - `instructions: string` + - `image_generation: object { type, action, background, 9 more }` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + A tool that generates images using the GPT image models. - - `last_error: object { code, message }` + - `local_shell: object { type }` - The last error associated with this run. Will be `null` if there are no errors. + A tool that allows the model to execute shell commands in a local environment. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + A tool that allows the model to execute shell commands. - - `"server_error"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"rate_limit_exceeded"` + 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) - - `"invalid_prompt"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `message: string` + Groups function/custom tools under a shared namespace. - A human-readable description of the error. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `max_completion_tokens: number` + Hosted or BYOT tool search configuration for deferred tools. - The maximum number of completion tokens specified to have been used over the course of the run. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `max_prompt_tokens: number` + 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). - The maximum number of prompt tokens specified to have been used over the course of the run. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `metadata: map[string]` + Allows the assistant to create, delete, or update files using unified diffs. - 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. + - `type: "additional_tools"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The item type. Always `additional_tools`. - - `model: string` + - `id: optional string` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID of this additional tools item. - - `object: "thread.run"` + - `agent: optional object { agent_name }` - The object type, which is always `thread.run`. + The agent that produced this item. - - `parallel_tool_calls: boolean` + - `agent_name: string` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The canonical name of the agent that produced this item. - - `required_action: object { submit_tool_outputs, type }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - Details on the action required to continue the run. Will be `null` if no action is required. + 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). - - `submit_tool_outputs: object { tool_calls }` + - `id: string` - Details on the tool outputs needed for this run to continue. + The unique identifier of the reasoning content. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `summary: array of object { text, type }` - A list of the relevant tool calls. + Reasoning summary content. - - `id: string` + - `text: string` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + A summary of the reasoning output from the model so far. - - `function: object { arguments, name }` + - `type: "summary_text"` - The function definition. + The type of the object. Always `summary_text`. - - `arguments: string` + - `type: "reasoning"` - The arguments that the model expects you to pass to the function. + The type of the object. Always `reasoning`. - - `name: string` + - `agent: optional object { agent_name }` - The name of the function. + The agent that produced this item. - - `type: "function"` + - `agent_name: string` - The type of tool call the output is required for. For now, this is always `function`. + The canonical name of the agent that produced this item. - - `type: "submit_tool_outputs"` + - `content: optional array of object { text, type }` - For now, this is always `submit_tool_outputs`. + Reasoning text content. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `text: string` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The reasoning text from the model. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "reasoning_text"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The type of the reasoning text. Always `reasoning_text`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `encrypted_content: optional string` - - `union_member_0: "auto"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - `auto` is the default value + - `status: optional "in_progress" or "completed" or "incomplete"` - - `response_format_text: object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Default response format. Used to generate text responses. + - `"in_progress"` - - `type: "text"` + - `"completed"` - The type of response format being defined. Always `text`. + - `"incomplete"` - - `response_format_json_object: object { type }` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `type: "json_object"` + - `encrypted_content: string` - The type of response format being defined. Always `json_object`. + The encrypted content of the compaction summary. - - `response_format_json_schema: object { json_schema, type }` + - `type: "compaction"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The type of the item. Always `compaction`. - - `json_schema: object { name, description, schema, strict }` + - `id: optional string` - Structured Outputs configuration options, including a JSON Schema. + The ID of the compaction item. - - `name: string` + - `agent: optional object { agent_name }` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The agent that produced this item. - - `description: optional string` + - `agent_name: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The canonical name of the agent that produced this item. - - `schema: optional map[unknown]` + - `image_generation_call: object { id, result, status, 2 more }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + An image generation request made by the model. - - `strict: optional boolean` + - `id: string` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The unique ID of the image generation call. - - `type: "json_schema"` + - `result: string` - The type of response format being defined. Always `json_schema`. + The generated image encoded in base64. - - `started_at: number` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The Unix timestamp (in seconds) for when the run was started. + The status of the image generation call. - - `status: unknown` + - `"in_progress"` - - `thread_id: string` + - `"completed"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"generating"` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `"failed"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `type: "image_generation_call"` - - `Auto: "none" or "auto" or "required"` + The type of the image generation call. Always `image_generation_call`. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `agent: optional object { agent_name }` - - `"none"` + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"required"` + The canonical name of the agent that produced this item. - - `assistant_tool_choice: object { type, function }` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + A tool call to run code. - - `type: "function" or "code_interpreter" or "file_search"` + - `id: string` - The type of the tool. If type is `function`, the function name must be set + The unique ID of the code interpreter tool call. - - `"function"` + - `code: string` - - `"code_interpreter"` + The code to run, or null if not available. - - `"file_search"` + - `container_id: string` - - `function: optional object { name }` + The ID of the container used to run the code. - - `name: string` + - `outputs: array of object { logs, type } or object { type, url }` - The name of the function to call. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `tools: array of unknown` + - `logs: object { logs, type }` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The logs output from the code interpreter. - - `truncation_strategy: object { type, last_messages }` + - `logs: string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The logs output from the code interpreter. - - `type: "auto" or "last_messages"` + - `type: "logs"` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + The type of the output. Always `logs`. - - `"auto"` + - `image: object { type, url }` - - `"last_messages"` + The image output from the code interpreter. - - `last_messages: optional number` + - `type: "image"` - The number of most recent messages from the thread when constructing the context for the run. + The type of the output. Always `image`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `url: string` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The URL of the image output from the code interpreter. - - `completion_tokens: number` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Number of completion tokens used over the course of the run. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `prompt_tokens: number` + - `"in_progress"` - Number of prompt tokens used over the course of the run. + - `"completed"` - - `total_tokens: number` + - `"incomplete"` - Total number of tokens used (prompt + completion). + - `"interpreting"` - - `temperature: optional number` + - `"failed"` - The sampling temperature used for this run. If not set, defaults to 1. + - `type: "code_interpreter_call"` - - `top_p: optional number` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `agent: optional object { agent_name }` -### Example + The agent that produced this item. -```cli -openai beta:threads:runs create \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --assistant-id assistant_id -``` + - `agent_name: string` -#### Response + The canonical name of the agent that produced this item. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `local_shell_call: object { id, action, call_id, 3 more }` -## Retrieve run + A tool call to run a command on the local shell. -`$ openai beta:threads:runs retrieve` + - `id: string` -**get** `/threads/{thread_id}/runs/{run_id}` + The unique ID of the local shell call. -Retrieve run + - `action: object { command, env, type, 3 more }` -### Parameters + Execute a shell command on the server. -- `--thread-id: string` + - `command: array of string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + The command to run. -- `--run-id: string` + - `env: map[string]` - The ID of the run to retrieve. + Environment variables to set for the command. -### Returns + - `type: "exec"` -- `run: object { id, assistant_id, cancelled_at, 24 more }` + The type of the local shell action. Always `exec`. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `timeout_ms: optional number` - - `id: string` + Optional timeout in milliseconds for the command. - The identifier, which can be referenced in API endpoints. + - `user: optional string` - - `assistant_id: string` + Optional user to run the command as. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `working_directory: optional string` - - `cancelled_at: number` + Optional working directory to run the command in. - The Unix timestamp (in seconds) for when the run was cancelled. + - `call_id: string` - - `completed_at: number` + The unique ID of the local shell tool call generated by the model. - The Unix timestamp (in seconds) for when the run was completed. + - `status: "in_progress" or "completed" or "incomplete"` - - `created_at: number` + The status of the local shell call. - The Unix timestamp (in seconds) for when the run was created. + - `"in_progress"` - - `expires_at: number` + - `"completed"` - The Unix timestamp (in seconds) for when the run will expire. + - `"incomplete"` - - `failed_at: number` + - `type: "local_shell_call"` - The Unix timestamp (in seconds) for when the run failed. + The type of the local shell call. Always `local_shell_call`. - - `incomplete_details: object { reason }` + - `agent: optional object { agent_name }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The agent that produced this item. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `agent_name: string` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The canonical name of the agent that produced this item. - - `"max_completion_tokens"` + - `local_shell_call_output: object { id, output, type, 2 more }` - - `"max_prompt_tokens"` + The output of a local shell tool call. - - `instructions: string` + - `id: string` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The unique ID of the local shell tool call generated by the model. - - `last_error: object { code, message }` + - `output: string` - The last error associated with this run. Will be `null` if there are no errors. + A JSON string of the output of the local shell tool call. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `type: "local_shell_call_output"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"server_error"` + - `agent: optional object { agent_name }` - - `"rate_limit_exceeded"` + The agent that produced this item. - - `"invalid_prompt"` + - `agent_name: string` - - `message: string` + The canonical name of the agent that produced this item. - A human-readable description of the error. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `max_completion_tokens: number` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The maximum number of completion tokens specified to have been used over the course of the run. + - `"in_progress"` - - `max_prompt_tokens: number` + - `"completed"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"incomplete"` - - `metadata: map[string]` + - `shell_call: object { action, call_id, type, 5 more }` - 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. + A tool representing a request to execute one or more shell commands. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `action: object { commands, max_output_length, timeout_ms }` - - `model: string` + The shell commands and limits that describe how to run the tool call. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `commands: array of string` - - `object: "thread.run"` + Ordered shell commands for the execution environment to run. - The object type, which is always `thread.run`. + - `max_output_length: optional number` - - `parallel_tool_calls: boolean` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `timeout_ms: optional number` - - `required_action: object { submit_tool_outputs, type }` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - Details on the action required to continue the run. Will be `null` if no action is required. + - `call_id: string` - - `submit_tool_outputs: object { tool_calls }` + The unique ID of the shell tool call generated by the model. - Details on the tool outputs needed for this run to continue. + - `type: "shell_call"` - - `tool_calls: array of RequiredActionFunctionToolCall` + The type of the item. Always `shell_call`. - A list of the relevant tool calls. + - `id: optional string` - - `id: string` + The unique ID of the shell tool call. Populated when this item is returned via API. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `agent: optional object { agent_name }` - - `function: object { arguments, name }` + The agent that produced this item. - The function definition. + - `agent_name: string` - - `arguments: string` + The canonical name of the agent that produced this item. - The arguments that the model expects you to pass to the function. + - `caller: optional object { type } or object { caller_id, type }` - - `name: string` + The execution context that produced this tool call. - The name of the function. + - `direct: object { type }` - - `type: "function"` + - `program: object { caller_id, type }` - The type of tool call the output is required for. For now, this is always `function`. + - `caller_id: string` - - `type: "submit_tool_outputs"` + The call ID of the program item that produced this tool call. - For now, this is always `submit_tool_outputs`. + - `type: "program"` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The caller type. Always `program`. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The environment to execute the shell commands in. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `beta_local_environment: object { type, skills }` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `beta_container_reference: object { container_id, type }` - - `union_member_0: "auto"` + - `status: optional "in_progress" or "completed" or "incomplete"` - `auto` is the default value + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `response_format_text: object { type }` + - `"in_progress"` - Default response format. Used to generate text responses. + - `"completed"` - - `type: "text"` + - `"incomplete"` - The type of response format being defined. Always `text`. + - `shell_call_output: object { call_id, output, type, 5 more }` - - `response_format_json_object: object { type }` + The streamed output items emitted by a shell tool call. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `call_id: string` - - `type: "json_object"` + The unique ID of the shell tool call generated by the model. - The type of response format being defined. Always `json_object`. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `response_format_json_schema: object { json_schema, type }` + Captured chunks of stdout and stderr output, along with their associated outcomes. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `outcome: object { type } or object { exit_code, type }` - - `json_schema: object { name, description, schema, strict }` + The exit or timeout outcome associated with this shell call. - Structured Outputs configuration options, including a JSON Schema. + - `timeout: object { type }` - - `name: string` + Indicates that the shell call exceeded its configured time limit. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `exit: object { exit_code, type }` - - `description: optional string` + Indicates that the shell commands finished and returned an exit code. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `exit_code: number` - - `schema: optional map[unknown]` + The exit code returned by the shell process. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: "exit"` - - `strict: optional boolean` + The outcome type. Always `exit`. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `stderr: string` - - `type: "json_schema"` + Captured stderr output for the shell call. - The type of response format being defined. Always `json_schema`. + - `stdout: string` - - `started_at: number` + Captured stdout output for the shell call. - The Unix timestamp (in seconds) for when the run was started. + - `type: "shell_call_output"` - - `status: unknown` + The type of the item. Always `shell_call_output`. - - `thread_id: string` + - `id: optional string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `agent: optional object { agent_name }` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The agent that produced this item. - - `Auto: "none" or "auto" or "required"` + - `agent_name: string` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + The canonical name of the agent that produced this item. - - `"none"` + - `caller: optional object { type } or object { caller_id, type }` - - `"auto"` + The execution context that produced this tool call. - - `"required"` + - `direct: object { type }` - - `assistant_tool_choice: object { type, function }` + - `program: object { caller_id, type }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `caller_id: string` - - `type: "function" or "code_interpreter" or "file_search"` + The call ID of the program item that produced this tool call. - The type of the tool. If type is `function`, the function name must be set + - `type: "program"` - - `"function"` + The caller type. Always `program`. - - `"code_interpreter"` + - `max_output_length: optional number` - - `"file_search"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `function: optional object { name }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the shell call output. - The name of the function to call. + - `"in_progress"` - - `tools: array of unknown` + - `"completed"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"incomplete"` - - `truncation_strategy: object { type, last_messages }` + - `apply_patch_call: object { call_id, operation, status, 4 more }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + A tool call representing a request to create, delete, or update files using diff patches. - - `type: "auto" or "last_messages"` + - `call_id: string` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + The unique ID of the apply patch tool call generated by the model. - - `"auto"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"last_messages"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `last_messages: optional number` + - `create_file: object { diff, path, type }` - The number of most recent messages from the thread when constructing the context for the run. + Instruction for creating a new file via the apply_patch tool. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `diff: string` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + Unified diff content to apply when creating the file. - - `completion_tokens: number` + - `path: string` - Number of completion tokens used over the course of the run. + Path of the file to create relative to the workspace root. - - `prompt_tokens: number` + - `type: "create_file"` - Number of prompt tokens used over the course of the run. + The operation type. Always `create_file`. - - `total_tokens: number` + - `delete_file: object { path, type }` - Total number of tokens used (prompt + completion). + Instruction for deleting an existing file via the apply_patch tool. - - `temperature: optional number` + - `path: string` - The sampling temperature used for this run. If not set, defaults to 1. + Path of the file to delete relative to the workspace root. - - `top_p: optional number` + - `type: "delete_file"` - The nucleus sampling value used for this run. If not set, defaults to 1. + The operation type. Always `delete_file`. -### Example + - `update_file: object { diff, path, type }` -```cli -openai beta:threads:runs retrieve \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id -``` + Instruction for updating an existing file via the apply_patch tool. -#### Response + - `diff: string` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + Unified diff content to apply to the existing file. -## Modify run + - `path: string` -`$ openai beta:threads:runs update` + Path of the file to update relative to the workspace root. -**post** `/threads/{thread_id}/runs/{run_id}` + - `type: "update_file"` -Modify run + The operation type. Always `update_file`. -### Parameters + - `status: "in_progress" or "completed"` -- `--thread-id: string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"in_progress"` -- `--run-id: string` + - `"completed"` - The ID of the run to modify. + - `type: "apply_patch_call"` -- `--metadata: optional map[string]` + The type of the item. Always `apply_patch_call`. - 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. + - `id: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The unique ID of the apply patch tool call. Populated when this item is returned via API. -### Returns + - `agent: optional object { agent_name }` -- `run: object { id, assistant_id, cancelled_at, 24 more }` + The agent that produced this item. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The identifier, which can be referenced in API endpoints. + - `caller: optional object { type } or object { caller_id, type }` - - `assistant_id: string` + The execution context that produced this tool call. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `direct: object { type }` - - `cancelled_at: number` + - `program: object { caller_id, type }` - The Unix timestamp (in seconds) for when the run was cancelled. + - `caller_id: string` - - `completed_at: number` + The call ID of the program item that produced this tool call. - The Unix timestamp (in seconds) for when the run was completed. + - `type: "program"` - - `created_at: number` + The caller type. Always `program`. - The Unix timestamp (in seconds) for when the run was created. + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - - `expires_at: number` + The streamed output emitted by an apply patch tool call. - The Unix timestamp (in seconds) for when the run will expire. + - `call_id: string` - - `failed_at: number` + The unique ID of the apply patch tool call generated by the model. - The Unix timestamp (in seconds) for when the run failed. + - `status: "completed" or "failed"` - - `incomplete_details: object { reason }` + The status of the apply patch tool call output. One of `completed` or `failed`. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"completed"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"failed"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `type: "apply_patch_call_output"` - - `"max_completion_tokens"` + The type of the item. Always `apply_patch_call_output`. - - `"max_prompt_tokens"` + - `id: optional string` - - `instructions: string` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `agent: optional object { agent_name }` - - `last_error: object { code, message }` + The agent that produced this item. - The last error associated with this run. Will be `null` if there are no errors. + - `agent_name: string` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + The canonical name of the agent that produced this item. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `caller: optional object { type } or object { caller_id, type }` - - `"server_error"` + The execution context that produced this tool call. - - `"rate_limit_exceeded"` + - `direct: object { type }` - - `"invalid_prompt"` + - `program: object { caller_id, type }` - - `message: string` + - `caller_id: string` - A human-readable description of the error. + The call ID of the program item that produced this tool call. - - `max_completion_tokens: number` + - `type: "program"` - The maximum number of completion tokens specified to have been used over the course of the run. + The caller type. Always `program`. - - `max_prompt_tokens: number` + - `output: optional string` - The maximum number of prompt tokens specified to have been used over the course of the run. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `metadata: map[string]` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - 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. + A list of tools available on an MCP server. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: string` - - `model: string` + The unique ID of the list. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `server_label: string` - - `object: "thread.run"` + The label of the MCP server. - The object type, which is always `thread.run`. + - `tools: array of object { input_schema, name, annotations, description }` - - `parallel_tool_calls: boolean` + The tools available on the server. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `input_schema: unknown` - - `required_action: object { submit_tool_outputs, type }` + The JSON schema describing the tool's input. - Details on the action required to continue the run. Will be `null` if no action is required. + - `name: string` - - `submit_tool_outputs: object { tool_calls }` + The name of the tool. - Details on the tool outputs needed for this run to continue. + - `annotations: optional unknown` - - `tool_calls: array of RequiredActionFunctionToolCall` + Additional annotations about the tool. - A list of the relevant tool calls. + - `description: optional string` - - `id: string` + The description of the tool. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `type: "mcp_list_tools"` - - `function: object { arguments, name }` + The type of the item. Always `mcp_list_tools`. - The function definition. + - `agent: optional object { agent_name }` - - `arguments: string` + The agent that produced this item. - The arguments that the model expects you to pass to the function. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the function. + - `error: optional string` - - `type: "function"` + Error message if the server could not list tools. - The type of tool call the output is required for. For now, this is always `function`. + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `type: "submit_tool_outputs"` + A request for human approval of a tool invocation. - For now, this is always `submit_tool_outputs`. + - `id: string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The unique ID of the approval request. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `arguments: string` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + A JSON string of arguments for the tool. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `name: string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The name of the tool to run. - - `union_member_0: "auto"` + - `server_label: string` - `auto` is the default value + The label of the MCP server making the request. - - `response_format_text: object { type }` + - `type: "mcp_approval_request"` - Default response format. Used to generate text responses. + The type of the item. Always `mcp_approval_request`. - - `type: "text"` + - `agent: optional object { agent_name }` - The type of response format being defined. Always `text`. + The agent that produced this item. - - `response_format_json_object: object { type }` + - `agent_name: string` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The canonical name of the agent that produced this item. - - `type: "json_object"` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - The type of response format being defined. Always `json_object`. + A response to an MCP approval request. - - `response_format_json_schema: object { json_schema, type }` + - `approval_request_id: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The ID of the approval request being answered. - - `json_schema: object { name, description, schema, strict }` + - `approve: boolean` - Structured Outputs configuration options, including a JSON Schema. + Whether the request was approved. - - `name: string` + - `type: "mcp_approval_response"` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The type of the item. Always `mcp_approval_response`. - - `description: optional string` + - `id: optional string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The unique ID of the approval response - - `schema: optional map[unknown]` + - `agent: optional object { agent_name }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The agent that produced this item. - - `strict: optional boolean` + - `agent_name: string` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - - `type: "json_schema"` + - `reason: optional string` - The type of response format being defined. Always `json_schema`. + Optional reason for the decision. - - `started_at: number` + - `mcp_call: object { id, arguments, name, 7 more }` - The Unix timestamp (in seconds) for when the run was started. + An invocation of a tool on an MCP server. - - `status: unknown` + - `id: string` - - `thread_id: string` + The unique ID of the tool call. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `arguments: string` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + A JSON string of the arguments passed to the tool. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `name: string` - - `Auto: "none" or "auto" or "required"` + The name of the tool that was run. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `server_label: string` - - `"none"` + The label of the MCP server running the tool. - - `"auto"` + - `type: "mcp_call"` - - `"required"` + The type of the item. Always `mcp_call`. - - `assistant_tool_choice: object { type, function }` + - `agent: optional object { agent_name }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The agent that produced this item. - - `type: "function" or "code_interpreter" or "file_search"` + - `agent_name: string` - The type of the tool. If type is `function`, the function name must be set + The canonical name of the agent that produced this item. - - `"function"` + - `approval_request_id: optional string` - - `"code_interpreter"` + 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. - - `"file_search"` + - `error: optional string` - - `function: optional object { name }` + The error from the tool call, if any. - - `name: string` + - `output: optional string` - The name of the function to call. + The output from the tool call. - - `tools: array of unknown` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `truncation_strategy: object { type, last_messages }` + - `"in_progress"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"completed"` - - `type: "auto" or "last_messages"` + - `"incomplete"` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `"calling"` - - `"auto"` + - `"failed"` - - `"last_messages"` + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `last_messages: optional number` + The output of a custom tool call from your code, being sent back to the model. - The number of most recent messages from the thread when constructing the context for the run. + - `call_id: string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The call ID, used to map this custom tool call output to a custom tool call. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `completion_tokens: number` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Number of completion tokens used over the course of the run. + - `string output: string` - - `prompt_tokens: number` + A string of the output of the custom tool call. - Number of prompt tokens used over the course of the run. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `total_tokens: number` + Text, image, or file output of the custom tool call. - Total number of tokens used (prompt + completion). + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `temperature: optional number` + A text input to the model. - The sampling temperature used for this run. If not set, defaults to 1. + - `text: string` - - `top_p: optional number` + The text input to the model. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `type: "input_text"` -### Example + The type of the input item. Always `input_text`. -```cli -openai beta:threads:runs update \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id -``` + - `prompt_cache_breakpoint: optional object { mode }` -#### Response + 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. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` -## Submit tool outputs to run + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). -`$ openai beta:threads:runs submit-tool-outputs` + - `detail: "low" or "high" or "auto" or "original"` -**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. -Submit tool outputs to run + - `type: "input_image"` -### Parameters + The type of the input item. Always `input_image`. -- `--thread-id: string` + - `file_id: optional string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to which this run belongs. + The ID of the file to be sent to the model. -- `--run-id: string` + - `image_url: optional string` - The ID of the run that requires the tool output submission. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. -- `--tool-output: array of object { output, tool_call_id }` + - `prompt_cache_breakpoint: optional object { mode }` - A list of tools for which the outputs are being submitted. + 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. -### Returns + - `beta_response_input_file: object { type, detail, file_data, 4 more }` -- `run: object { id, assistant_id, cancelled_at, 24 more }` + A file input to the model. - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: "input_file"` - - `id: string` + The type of the input item. Always `input_file`. - The identifier, which can be referenced in API endpoints. + - `detail: optional "auto" or "low" or "high"` - - `assistant_id: string` + 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`. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `file_data: optional string` - - `cancelled_at: number` + The content of the file to be sent to the model. - The Unix timestamp (in seconds) for when the run was cancelled. + - `file_id: optional string` - - `completed_at: number` + The ID of the file to be sent to the model. - The Unix timestamp (in seconds) for when the run was completed. + - `file_url: optional string` - - `created_at: number` + The URL of the file to be sent to the model. - The Unix timestamp (in seconds) for when the run was created. + - `filename: optional string` - - `expires_at: number` + The name of the file to be sent to the model. - The Unix timestamp (in seconds) for when the run will expire. + - `prompt_cache_breakpoint: optional object { mode }` - - `failed_at: number` + 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. - The Unix timestamp (in seconds) for when the run failed. + - `type: "custom_tool_call_output"` - - `incomplete_details: object { reason }` + The type of the custom tool call output. Always `custom_tool_call_output`. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `id: optional string` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + The unique ID of the custom tool call output in the OpenAI platform. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `agent: optional object { agent_name }` - - `"max_completion_tokens"` + The agent that produced this item. - - `"max_prompt_tokens"` + - `agent_name: string` - - `instructions: string` + The canonical name of the agent that produced this item. - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `caller: optional object { type } or object { caller_id, type }` - - `last_error: object { code, message }` + The execution context that produced this tool call. - The last error associated with this run. Will be `null` if there are no errors. + - `direct: object { type }` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `program: object { caller_id, type }` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `caller_id: string` - - `"server_error"` + The call ID of the program item that produced this tool call. - - `"rate_limit_exceeded"` + - `type: "program"` - - `"invalid_prompt"` + The caller type. Always `program`. - - `message: string` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - A human-readable description of the error. + A call to a custom tool created by the model. - - `max_completion_tokens: number` + - `call_id: string` - The maximum number of completion tokens specified to have been used over the course of the run. + An identifier used to map this custom tool call to a tool call output. - - `max_prompt_tokens: number` + - `input: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + The input for the custom tool call generated by the model. - - `metadata: map[string]` + - `name: string` - 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. + The name of the custom tool being called. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "custom_tool_call"` - - `model: string` + The type of the custom tool call. Always `custom_tool_call`. - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `id: optional string` - - `object: "thread.run"` + The unique ID of the custom tool call in the OpenAI platform. - The object type, which is always `thread.run`. + - `agent: optional object { agent_name }` - - `parallel_tool_calls: boolean` + The agent that produced this item. - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `agent_name: string` - - `required_action: object { submit_tool_outputs, type }` + The canonical name of the agent that produced this item. - Details on the action required to continue the run. Will be `null` if no action is required. + - `caller: optional object { type } or object { caller_id, type }` - - `submit_tool_outputs: object { tool_calls }` + The execution context that produced this tool call. - Details on the tool outputs needed for this run to continue. + - `direct: object { type }` - - `tool_calls: array of RequiredActionFunctionToolCall` + - `program: object { caller_id, type }` - A list of the relevant tool calls. + - `caller_id: string` - - `id: string` + The call ID of the program item that produced this tool call. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `type: "program"` - - `function: object { arguments, name }` + - `namespace: optional string` - The function definition. + The namespace of the custom tool being called. - - `arguments: string` + - `compaction_trigger: object { type, agent }` - The arguments that the model expects you to pass to the function. + Compacts the current context. Must be the final input item. - - `name: string` + - `type: "compaction_trigger"` - The name of the function. + The type of the item. Always `compaction_trigger`. - - `type: "function"` + - `agent: optional object { agent_name }` - The type of tool call the output is required for. For now, this is always `function`. + The agent that produced this item. - - `type: "submit_tool_outputs"` + - `agent_name: string` - For now, this is always `submit_tool_outputs`. + The canonical name of the agent that produced this item. - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `item_reference: object { id, agent, type }` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + An internal identifier for an item to reference. - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `id: string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The ID of the item to reference. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `agent: optional object { agent_name }` - - `union_member_0: "auto"` + The agent that produced this item. - `auto` is the default value + - `agent_name: string` - - `response_format_text: object { type }` + The canonical name of the agent that produced this item. - Default response format. Used to generate text responses. + - `type: optional "item_reference"` - - `type: "text"` + The type of item to reference. Always `item_reference`. - The type of response format being defined. Always `text`. + - `"item_reference"` - - `response_format_json_object: object { type }` + - `program: object { id, call_id, code, 3 more }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `id: string` - - `type: "json_object"` + The unique ID of this program item. - The type of response format being defined. Always `json_object`. + - `call_id: string` - - `response_format_json_schema: object { json_schema, type }` + The stable call ID of the program item. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `code: string` - - `json_schema: object { name, description, schema, strict }` + The JavaScript source executed by programmatic tool calling. - Structured Outputs configuration options, including a JSON Schema. + - `fingerprint: string` - - `name: string` + Opaque program replay fingerprint that must be round-tripped. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `type: "program"` - - `description: optional string` + The item type. Always `program`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent: optional object { agent_name }` - - `schema: optional map[unknown]` + The agent that produced this item. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `agent_name: string` - - `strict: optional boolean` + The canonical name of the agent that produced this item. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `program_output: object { id, call_id, result, 3 more }` - - `type: "json_schema"` + - `id: string` - The type of response format being defined. Always `json_schema`. + The unique ID of this program output item. - - `started_at: number` + - `call_id: string` - The Unix timestamp (in seconds) for when the run was started. + The call ID of the program item. - - `status: unknown` + - `result: string` - - `thread_id: string` + The result produced by the program item. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `status: "completed" or "incomplete"` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The terminal status of the program output. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `"completed"` - - `Auto: "none" or "auto" or "required"` + - `"incomplete"` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `type: "program_output"` - - `"none"` + The item type. Always `program_output`. - - `"auto"` + - `agent: optional object { agent_name }` - - `"required"` + The agent that produced this item. - - `assistant_tool_choice: object { type, function }` + - `agent_name: string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The canonical name of the agent that produced this item. - - `type: "function" or "code_interpreter" or "file_search"` + - `metadata: map[string]` - The type of the tool. If type is `function`, the function name must be set + 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. - - `"function"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"code_interpreter"` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `"file_search"` + Model ID used to generate the response, like `gpt-4o` 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. - - `function: optional object { name }` + - `"gpt-5.6-sol"` - - `name: string` + - `"gpt-5.6-terra"` - The name of the function to call. + - `"gpt-5.6-luna"` - - `tools: array of unknown` + - `"gpt-5.4"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-5.4-mini"` - - `truncation_strategy: object { type, last_messages }` + - `"gpt-5.4-nano"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"gpt-5.4-mini-2026-03-17"` - - `type: "auto" or "last_messages"` + - `"gpt-5.4-nano-2026-03-17"` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `"gpt-5.3-chat-latest"` - - `"auto"` + - `"gpt-5.2"` - - `"last_messages"` + - `"gpt-5.2-2025-12-11"` - - `last_messages: optional number` + - `"gpt-5.2-chat-latest"` - The number of most recent messages from the thread when constructing the context for the run. + - `"gpt-5.2-pro"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"gpt-5.2-pro-2025-12-11"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"gpt-5.1"` - - `completion_tokens: number` + - `"gpt-5.1-2025-11-13"` - Number of completion tokens used over the course of the run. + - `"gpt-5.1-codex"` - - `prompt_tokens: number` + - `"gpt-5.1-mini"` - Number of prompt tokens used over the course of the run. + - `"gpt-5.1-chat-latest"` - - `total_tokens: number` + - `"gpt-5"` - Total number of tokens used (prompt + completion). + - `"gpt-5-mini"` - - `temperature: optional number` + - `"gpt-5-nano"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"gpt-5-2025-08-07"` - - `top_p: optional number` + - `"gpt-5-mini-2025-08-07"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"gpt-5-nano-2025-08-07"` -### Example + - `"gpt-5-chat-latest"` -```cli -openai beta:threads:runs submit-tool-outputs \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id \ - --tool-output '{}' -``` + - `"gpt-4.1"` -#### Response + - `"gpt-4.1-mini"` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `"gpt-4.1-nano"` -## Cancel a run + - `"gpt-4.1-2025-04-14"` -`$ openai beta:threads:runs cancel` + - `"gpt-4.1-mini-2025-04-14"` -**post** `/threads/{thread_id}/runs/{run_id}/cancel` + - `"gpt-4.1-nano-2025-04-14"` -Cancel a run + - `"o4-mini"` -### Parameters + - `"o4-mini-2025-04-16"` -- `--thread-id: string` + - `"o3"` - The ID of the thread to which this run belongs. + - `"o3-2025-04-16"` -- `--run-id: string` + - `"o3-mini"` - The ID of the run to cancel. + - `"o3-mini-2025-01-31"` -### Returns + - `"o1"` -- `run: object { id, assistant_id, cancelled_at, 24 more }` + - `"o1-2024-12-17"` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"o1-preview"` - - `id: string` + - `"o1-preview-2024-09-12"` - The identifier, which can be referenced in API endpoints. + - `"o1-mini"` - - `assistant_id: string` + - `"o1-mini-2024-09-12"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + - `"gpt-4o"` - - `cancelled_at: number` + - `"gpt-4o-2024-11-20"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `"gpt-4o-2024-08-06"` - - `completed_at: number` + - `"gpt-4o-2024-05-13"` - The Unix timestamp (in seconds) for when the run was completed. + - `"gpt-4o-audio-preview"` - - `created_at: number` + - `"gpt-4o-audio-preview-2024-10-01"` - The Unix timestamp (in seconds) for when the run was created. + - `"gpt-4o-audio-preview-2024-12-17"` - - `expires_at: number` + - `"gpt-4o-audio-preview-2025-06-03"` - The Unix timestamp (in seconds) for when the run will expire. + - `"gpt-4o-mini-audio-preview"` - - `failed_at: number` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The Unix timestamp (in seconds) for when the run failed. + - `"gpt-4o-search-preview"` - - `incomplete_details: object { reason }` + - `"gpt-4o-mini-search-preview"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"gpt-4o-search-preview-2025-03-11"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"chatgpt-4o-latest"` - - `"max_completion_tokens"` + - `"codex-mini-latest"` - - `"max_prompt_tokens"` + - `"gpt-4o-mini"` - - `instructions: string` + - `"gpt-4o-mini-2024-07-18"` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-4-turbo"` - - `last_error: object { code, message }` + - `"gpt-4-turbo-2024-04-09"` - The last error associated with this run. Will be `null` if there are no errors. + - `"gpt-4-0125-preview"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"gpt-4-turbo-preview"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"gpt-4-1106-preview"` - - `"server_error"` + - `"gpt-4-vision-preview"` - - `"rate_limit_exceeded"` + - `"gpt-4"` - - `"invalid_prompt"` + - `"gpt-4-0314"` - - `message: string` + - `"gpt-4-0613"` - A human-readable description of the error. + - `"gpt-4-32k"` - - `max_completion_tokens: number` + - `"gpt-4-32k-0314"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"gpt-4-32k-0613"` - - `max_prompt_tokens: number` + - `"gpt-3.5-turbo"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"gpt-3.5-turbo-16k"` - - `metadata: map[string]` + - `"gpt-3.5-turbo-0301"` - 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. + - `"gpt-3.5-turbo-0613"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"gpt-3.5-turbo-1106"` - - `model: string` + - `"gpt-3.5-turbo-0125"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `"gpt-3.5-turbo-16k-0613"` - - `object: "thread.run"` + - `"o1-pro"` - The object type, which is always `thread.run`. + - `"o1-pro-2025-03-19"` - - `parallel_tool_calls: boolean` + - `"o3-pro"` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"o3-pro-2025-06-10"` - - `required_action: object { submit_tool_outputs, type }` + - `"o3-deep-research"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"o3-deep-research-2025-06-26"` - - `submit_tool_outputs: object { tool_calls }` + - `"o4-mini-deep-research"` - Details on the tool outputs needed for this run to continue. + - `"o4-mini-deep-research-2025-06-26"` - - `tool_calls: array of RequiredActionFunctionToolCall` + - `"computer-use-preview"` - A list of the relevant tool calls. + - `"computer-use-preview-2025-03-11"` - - `id: string` + - `"gpt-5-codex"` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + - `"gpt-5-pro"` - - `function: object { arguments, name }` + - `"gpt-5-pro-2025-10-06"` - The function definition. + - `"gpt-5.1-codex-max"` - - `arguments: string` + - `object: "response"` - The arguments that the model expects you to pass to the function. + The object type of this resource - always set to `response`. - - `name: string` + - `output: array of BetaResponseOutputItem` - The name of the function. + An array of content items generated by the model. - - `type: "function"` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - The type of tool call the output is required for. For now, this is always `function`. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `type: "submit_tool_outputs"` + An output message from the model. - For now, this is always `submit_tool_outputs`. + - `id: string` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + The unique ID of the output message. - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The content of the output message. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `role: "assistant"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The role of the output message. Always `assistant`. - - `union_member_0: "auto"` + - `status: "in_progress" or "completed" or "incomplete"` - `auto` is the default value + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `response_format_text: object { type }` + - `type: "message"` - Default response format. Used to generate text responses. + The type of the output message. Always `message`. - - `type: "text"` + - `agent: optional object { agent_name }` - The type of response format being defined. Always `text`. + The agent that produced this item. - - `response_format_json_object: object { type }` + - `phase: optional "commentary" or "final_answer"` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `type: "json_object"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The type of response format being defined. Always `json_object`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `response_format_json_schema: object { json_schema, type }` + - `id: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The unique ID of the file search tool call. - - `json_schema: object { name, description, schema, strict }` + - `queries: array of string` - Structured Outputs configuration options, including a JSON Schema. + The queries used to search for files. - - `name: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `description: optional string` + - `type: "file_search_call"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The type of the file search tool call. Always `file_search_call`. - - `schema: optional map[unknown]` + - `agent: optional object { agent_name }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The agent that produced this item. - - `strict: optional boolean` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The results of the file search tool call. - - `type: "json_schema"` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The type of response format being defined. Always `json_schema`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `started_at: number` + - `arguments: string` - The Unix timestamp (in seconds) for when the run was started. + A JSON string of the arguments to pass to the function. - - `status: unknown` + - `call_id: string` - - `thread_id: string` + The unique ID of the function tool call generated by the model. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `name: string` - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + The name of the function to run. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `type: "function_call"` - - `Auto: "none" or "auto" or "required"` + The type of the function tool call. Always `function_call`. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `id: optional string` - - `"none"` + The unique ID of the function tool call. - - `"auto"` + - `agent: optional object { agent_name }` - - `"required"` + The agent that produced this item. - - `assistant_tool_choice: object { type, function }` + - `caller: optional object { type } or object { caller_id, type }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The execution context that produced this tool call. - - `type: "function" or "code_interpreter" or "file_search"` + - `namespace: optional string` - The type of the tool. If type is `function`, the function name must be set + The namespace of the function to run. - - `"function"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"code_interpreter"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"file_search"` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `function: optional object { name }` + - `id: string` - - `name: string` + The unique ID of the function call tool output. - The name of the function to call. + - `call_id: string` - - `tools: array of unknown` + The unique ID of the function tool call generated by the model. - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `truncation_strategy: object { type, last_messages }` + The output from the function call generated by your code. + Can be a string or an list of output content. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `string output: string` - - `type: "auto" or "last_messages"` + A string of the output of the function call. - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"auto"` + Text, image, or file output of the function call. - - `"last_messages"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `last_messages: optional number` + A text input to the model. - The number of most recent messages from the thread when constructing the context for the run. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `completion_tokens: number` + A file input to the model. - Number of completion tokens used over the course of the run. + - `status: "in_progress" or "completed" or "incomplete"` - - `prompt_tokens: number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Number of prompt tokens used over the course of the run. + - `"in_progress"` - - `total_tokens: number` + - `"completed"` - Total number of tokens used (prompt + completion). + - `"incomplete"` - - `temperature: optional number` + - `type: "function_call_output"` - The sampling temperature used for this run. If not set, defaults to 1. + The type of the function tool call output. Always `function_call_output`. - - `top_p: optional number` + - `agent: optional object { agent_name }` - The nucleus sampling value used for this run. If not set, defaults to 1. + The agent that produced this item. -### Example + - `agent_name: string` -```cli -openai beta:threads:runs cancel \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id -``` + The canonical name of the agent that produced this item. -#### Response + - `caller: optional object { type } or object { caller_id, type }` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": {}, - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - {} - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The execution context that produced this tool call. -## Domain Types + - `direct: object { type }` -### Required Action Function Tool Call + - `program: object { caller_id, type }` -- `required_action_function_tool_call: object { id, function, type }` + - `caller_id: string` - Tool call objects + The call ID of the program item that produced this tool call. - - `id: string` + - `type: "program"` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The caller type. Always `program`. - - `function: object { arguments, name }` + - `created_by: optional string` - The function definition. + The identifier of the actor that created the item. - - `arguments: string` + - `agent_message: object { id, author, content, 3 more }` - The arguments that the model expects you to pass to the function. + - `id: string` - - `name: string` + The unique ID of the agent message. - The name of the function. + - `author: string` - - `type: "function"` + The sending agent identity. - The type of tool call the output is required for. For now, this is always `function`. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` -### Run + Encrypted content sent between agents. -- `run: object { id, assistant_id, cancelled_at, 24 more }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). + A text input to the model. - - `id: string` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - The identifier, which can be referenced in API endpoints. + A text output from the model. - - `assistant_id: string` + - `text: object { text, type }` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. + A text content. - - `cancelled_at: number` + - `text: string` - The Unix timestamp (in seconds) for when the run was cancelled. + - `type: "text"` - - `completed_at: number` + - `summary_text: object { text, type }` - The Unix timestamp (in seconds) for when the run was completed. + A summary text from the model. - - `created_at: number` + - `text: string` - The Unix timestamp (in seconds) for when the run was created. + A summary of the reasoning output from the model so far. - - `expires_at: number` + - `type: "summary_text"` - The Unix timestamp (in seconds) for when the run will expire. + The type of the object. Always `summary_text`. - - `failed_at: number` + - `reasoning_text: object { text, type }` - The Unix timestamp (in seconds) for when the run failed. + Reasoning text from the model. - - `incomplete_details: object { reason }` + - `text: string` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The reasoning text from the model. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `type: "reasoning_text"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The type of the reasoning text. Always `reasoning_text`. - - `"max_completion_tokens"` + - `beta_response_output_refusal: object { refusal, type }` - - `"max_prompt_tokens"` + A refusal from the model. - - `instructions: string` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `last_error: object { code, message }` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - The last error associated with this run. Will be `null` if there are no errors. + A screenshot of a computer. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `detail: "low" or "high" or "auto" or "original"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"server_error"` + - `"low"` - - `"rate_limit_exceeded"` + - `"high"` - - `"invalid_prompt"` + - `"auto"` - - `message: string` + - `"original"` - A human-readable description of the error. + - `file_id: string` - - `max_completion_tokens: number` + The identifier of an uploaded file that contains the screenshot. - The maximum number of completion tokens specified to have been used over the course of the run. + - `image_url: string` - - `max_prompt_tokens: number` + The URL of the screenshot image. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: "computer_screenshot"` - - `metadata: map[string]` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - 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. + - `prompt_cache_breakpoint: optional object { mode }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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. - - `model: string` + - `mode: "explicit"` - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The breakpoint mode. Always `explicit`. - - `object: "thread.run"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The object type, which is always `thread.run`. + A file input to the model. - - `parallel_tool_calls: boolean` + - `encrypted_content: object { encrypted_content, type }` - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `required_action: object { submit_tool_outputs, type }` + - `encrypted_content: string` - Details on the action required to continue the run. Will be `null` if no action is required. + Opaque encrypted content. - - `submit_tool_outputs: object { tool_calls }` + - `type: "encrypted_content"` - Details on the tool outputs needed for this run to continue. + The type of the input item. Always `encrypted_content`. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `recipient: string` - A list of the relevant tool calls. + The destination agent identity. - - `id: string` + - `type: "agent_message"` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. + The type of the item. Always `agent_message`. - - `function: object { arguments, name }` + - `agent: optional object { agent_name }` - The function definition. + The agent that produced this item. - - `arguments: string` + - `agent_name: string` - The arguments that the model expects you to pass to the function. + The canonical name of the agent that produced this item. - - `name: string` + - `multi_agent_call: object { id, action, arguments, 3 more }` - The name of the function. + - `id: string` - - `type: "function"` + The unique ID of the multi-agent call item. - The type of tool call the output is required for. For now, this is always `function`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "submit_tool_outputs"` + The multi-agent action to execute. - For now, this is always `submit_tool_outputs`. + - `"spawn_agent"` - - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` + - `"interrupt_agent"` - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"list_agents"` - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"send_message"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"followup_task"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"wait_agent"` - - `union_member_0: "auto"` + - `arguments: string` - `auto` is the default value + The JSON string of arguments generated for the action. - - `response_format_text: object { type }` + - `call_id: string` - Default response format. Used to generate text responses. + The unique ID linking this call to its output. - - `type: "text"` + - `type: "multi_agent_call"` - The type of response format being defined. Always `text`. + The type of the multi-agent call. Always `multi_agent_call`. - - `response_format_json_object: object { type }` + - `agent: optional object { agent_name }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The agent that produced this item. - - `type: "json_object"` + - `agent_name: string` - The type of response format being defined. Always `json_object`. + The canonical name of the agent that produced this item. - - `response_format_json_schema: object { json_schema, type }` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `id: string` - - `json_schema: object { name, description, schema, strict }` + The unique ID of the multi-agent call output item. - Structured Outputs configuration options, including a JSON Schema. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `name: string` + The multi-agent action that produced this result. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `"spawn_agent"` - - `description: optional string` + - `"interrupt_agent"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"list_agents"` - - `schema: optional map[unknown]` + - `"send_message"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"followup_task"` - - `strict: optional boolean` + - `"wait_agent"` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `call_id: string` - - `type: "json_schema"` + The unique ID of the multi-agent call. - The type of response format being defined. Always `json_schema`. + - `output: array of BetaResponseOutputText` - - `started_at: number` + Text output returned by the multi-agent action. - The Unix timestamp (in seconds) for when the run was started. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `status: unknown` + The annotations of the text output. - - `thread_id: string` + - `text: string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + The text output from the model. - - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` + - `type: "output_text"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The type of the output text. Always `output_text`. - - `Auto: "none" or "auto" or "required"` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `type: "multi_agent_call_output"` - - `"none"` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"auto"` + - `agent: optional object { agent_name }` - - `"required"` + The agent that produced this item. - - `assistant_tool_choice: object { type, function }` + - `agent_name: string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The canonical name of the agent that produced this item. - - `type: "function" or "code_interpreter" or "file_search"` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - The type of the tool. If type is `function`, the function name must be set + 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. - - `"function"` + - `id: string` - - `"code_interpreter"` + The unique ID of the web search tool call. - - `"file_search"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `function: optional object { name }` + 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). - - `name: string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The name of the function to call. + The status of the web search tool call. - - `tools: array of unknown` + - `type: "web_search_call"` - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + The type of the web search tool call. Always `web_search_call`. - - `truncation_strategy: object { type, last_messages }` + - `agent: optional object { agent_name }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The agent that produced this item. - - `type: "auto" or "last_messages"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + 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. - - `"auto"` + - `id: string` - - `"last_messages"` + The unique ID of the computer call. - - `last_messages: optional number` + - `call_id: string` - The number of most recent messages from the thread when constructing the context for the run. + An identifier used when responding to the tool call with output. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `pending_safety_checks: array of object { id, code, message }` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The pending safety checks for the computer call. - - `completion_tokens: number` + - `status: "in_progress" or "completed" or "incomplete"` - Number of completion tokens used over the course of the run. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `prompt_tokens: number` + - `type: "computer_call"` - Number of prompt tokens used over the course of the run. + The type of the computer call. Always `computer_call`. - - `total_tokens: number` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - Total number of tokens used (prompt + completion). + A click action. - - `temperature: optional number` + - `actions: optional array of BetaComputerAction` - The sampling temperature used for this run. If not set, defaults to 1. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `top_p: optional number` + - `agent: optional object { agent_name }` - The nucleus sampling value used for this run. If not set, defaults to 1. + The agent that produced this item. -### Run Status + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` -- `run_status: unknown` + - `id: string` -# Steps + The unique ID of the computer call tool output. -## List run steps + - `call_id: string` -`$ openai beta:threads:runs:steps list` + The ID of the computer tool call that produced the output. -**get** `/threads/{thread_id}/runs/{run_id}/steps` + - `output: object { type, file_id, image_url }` -List run steps + A computer screenshot image used with the computer use tool. -### Parameters + - `type: "computer_screenshot"` -- `--thread-id: string` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The ID of the thread the run and run steps belong to. + - `file_id: optional string` -- `--run-id: string` + The identifier of an uploaded file that contains the screenshot. - The ID of the run the run steps belong to. + - `image_url: optional string` -- `--after: optional string` + The URL of the screenshot image. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` -- `--before: optional string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `"completed"` -- `--include: optional array of RunStepInclude` + - `"incomplete"` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + - `"failed"` - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"in_progress"` -- `--limit: optional number` + - `type: "computer_call_output"` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The type of the computer tool call output. Always `computer_call_output`. -- `--order: optional "asc" or "desc"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + The safety checks reported by the API that have been acknowledged by the + developer. -### Returns + - `id: string` -- `ListRunStepsResponse: object { data, first_id, has_more, 2 more }` + The ID of the pending safety check. - - `data: array of RunStep` + - `code: optional string` - - `id: string` + The type of the pending safety check. - The identifier of the run step, which can be referenced in API endpoints. + - `message: optional string` - - `assistant_id: string` + Details about the pending safety check. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `agent: optional object { agent_name }` - - `cancelled_at: number` + The agent that produced this item. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `agent_name: string` - - `completed_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the run step completed. + - `created_by: optional string` - - `created_at: number` + The identifier of the actor that created the item. - The Unix timestamp (in seconds) for when the run step was created. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `expired_at: number` + 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). - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `id: string` - - `failed_at: number` + The unique identifier of the reasoning content. - The Unix timestamp (in seconds) for when the run step failed. + - `summary: array of object { text, type }` - - `last_error: object { code, message }` + Reasoning summary content. - The last error associated with this run step. Will be `null` if there are no errors. + - `type: "reasoning"` - - `code: "server_error" or "rate_limit_exceeded"` + The type of the object. Always `reasoning`. - One of `server_error` or `rate_limit_exceeded`. + - `agent: optional object { agent_name }` - - `"server_error"` + The agent that produced this item. - - `"rate_limit_exceeded"` + - `content: optional array of object { text, type }` - - `message: string` + Reasoning text content. - A human-readable description of the error. + - `encrypted_content: optional string` - - `metadata: map[string]` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - 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. + - `status: optional "in_progress" or "completed" or "incomplete"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `object: "thread.run.step"` + - `program: object { id, call_id, code, 3 more }` - The object type, which is always `thread.run.step`. + - `id: string` - - `run_id: string` + The unique ID of the program item. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `call_id: string` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + The stable call ID of the program item. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `code: string` - - `"in_progress"` + The JavaScript source executed by programmatic tool calling. - - `"cancelled"` + - `fingerprint: string` - - `"failed"` + Opaque program replay fingerprint that must be round-tripped. - - `"completed"` + - `type: "program"` - - `"expired"` + The type of the item. Always `program`. - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `agent: optional object { agent_name }` - The details of the run step. + The agent that produced this item. - - `message_creation_step_details: object { message_creation, type }` + - `agent_name: string` - Details of the message creation by the run step. + The canonical name of the agent that produced this item. - - `message_creation: object { message_id }` + - `program_output: object { id, call_id, result, 3 more }` - - `message_id: string` + - `id: string` - The ID of the message that was created by this run step. + The unique ID of the program output item. - - `type: "message_creation"` + - `call_id: string` - Always `message_creation`. + The call ID of the program item. - - `tool_calls_step_details: object { tool_calls, type }` + - `result: string` - Details of the tool call. + The result produced by the program item. - - `tool_calls: array of unknown` + - `status: "completed" or "incomplete"` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The terminal status of the program output item. - - `type: "tool_calls"` + - `"completed"` - Always `tool_calls`. + - `"incomplete"` - - `thread_id: string` + - `type: "program_output"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + The type of the item. Always `program_output`. - - `type: "message_creation" or "tool_calls"` + - `agent: optional object { agent_name }` - The type of run step, which can be either `message_creation` or `tool_calls`. + The agent that produced this item. - - `"message_creation"` + - `agent_name: string` - - `"tool_calls"` + The canonical name of the agent that produced this item. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `id: string` - - `completion_tokens: number` + The unique ID of the tool search call item. - Number of completion tokens used over the course of the run step. + - `arguments: unknown` - - `prompt_tokens: number` + Arguments used for the tool search call. - Number of prompt tokens used over the course of the run step. + - `call_id: string` - - `total_tokens: number` + The unique ID of the tool search call generated by the model. - Total number of tokens used (prompt + completion). + - `execution: "server" or "client"` - - `first_id: string` + Whether tool search was executed by the server or by the client. - - `has_more: boolean` + - `"server"` - - `last_id: string` + - `"client"` - - `object: string` + - `status: "in_progress" or "completed" or "incomplete"` -### Example + The status of the tool search call item that was recorded. -```cli -openai beta:threads:runs:steps list \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id -``` + - `"in_progress"` -#### Response + - `"completed"` -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } - } - ], - "first_id": "step_abc123", - "has_more": false, - "last_id": "step_abc456", - "object": "list" -} -``` + - `"incomplete"` -## Retrieve run step + - `type: "tool_search_call"` -`$ openai beta:threads:runs:steps retrieve` + The type of the item. Always `tool_search_call`. -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` + - `agent: optional object { agent_name }` -Retrieve run step + The agent that produced this item. -### Parameters + - `agent_name: string` -- `--thread-id: string` + The canonical name of the agent that produced this item. - The ID of the thread to which the run and run step belongs. + - `created_by: optional string` -- `--run-id: string` + The identifier of the actor that created the item. - The ID of the run to which the run step belongs. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` -- `--step-id: string` + - `id: string` - The ID of the run step to retrieve. + The unique ID of the tool search output item. -- `--include: optional array of RunStepInclude` + - `call_id: string` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + The unique ID of the tool search call generated by the model. - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `execution: "server" or "client"` -### Returns + Whether tool search was executed by the server or by the client. -- `run_step: object { id, assistant_id, cancelled_at, 13 more }` + - `"server"` - Represents a step in execution of a run. + - `"client"` - - `id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The identifier of the run step, which can be referenced in API endpoints. + The status of the tool search output item that was recorded. - - `assistant_id: string` + - `"in_progress"` - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `"completed"` - - `cancelled_at: number` + - `"incomplete"` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `tools: array of BetaTool` - - `completed_at: number` + The loaded tool definitions returned by tool search. - The Unix timestamp (in seconds) for when the run step completed. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `created_at: number` + 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). - The Unix timestamp (in seconds) for when the run step was created. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `expired_at: number` + 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). - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `beta_computer_tool: object { type }` - - `failed_at: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The Unix timestamp (in seconds) for when the run step failed. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `last_error: object { code, message }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The last error associated with this run step. Will be `null` if there are no errors. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `code: "server_error" or "rate_limit_exceeded"` + 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). - One of `server_error` or `rate_limit_exceeded`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `"server_error"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"rate_limit_exceeded"` + - `code_interpreter: object { container, type, allowed_callers }` - - `message: string` + A tool that runs Python code to help generate a response to a prompt. - A human-readable description of the error. + - `programmatic_tool_calling: object { type }` - - `metadata: map[string]` + - `image_generation: object { type, action, background, 9 more }` - 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. + A tool that generates images using the GPT image models. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `local_shell: object { type }` - - `object: "thread.run.step"` + A tool that allows the model to execute shell commands in a local environment. - The object type, which is always `thread.run.step`. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `run_id: string` + A tool that allows the model to execute shell commands. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + 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) - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `beta_namespace_tool: object { description, name, tools, type }` - - `"in_progress"` + Groups function/custom tools under a shared namespace. - - `"cancelled"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `"failed"` + Hosted or BYOT tool search configuration for deferred tools. - - `"completed"` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"expired"` + 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). - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The details of the run step. + Allows the assistant to create, delete, or update files using unified diffs. - - `message_creation_step_details: object { message_creation, type }` + - `type: "tool_search_output"` - Details of the message creation by the run step. + The type of the item. Always `tool_search_output`. - - `message_creation: object { message_id }` + - `agent: optional object { agent_name }` - - `message_id: string` + The agent that produced this item. - The ID of the message that was created by this run step. + - `agent_name: string` - - `type: "message_creation"` + The canonical name of the agent that produced this item. - Always `message_creation`. + - `created_by: optional string` - - `tool_calls_step_details: object { tool_calls, type }` + The identifier of the actor that created the item. - Details of the tool call. + - `additional_tools: object { id, role, tools, 2 more }` - - `tool_calls: array of unknown` + - `id: string` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The unique ID of the additional tools item. - - `type: "tool_calls"` + - `role: "unknown" or "user" or "assistant" or 5 more` - Always `tool_calls`. + The role that provided the additional tools. - - `thread_id: string` + - `"unknown"` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `"user"` - - `type: "message_creation" or "tool_calls"` + - `"assistant"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"system"` - - `"message_creation"` + - `"critic"` - - `"tool_calls"` + - `"discriminator"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"developer"` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `"tool"` - - `completion_tokens: number` + - `tools: array of BetaTool` - Number of completion tokens used over the course of the run step. + The additional tool definitions made available at this item. - - `prompt_tokens: number` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - Number of prompt tokens used over the course of the run step. + 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). - - `total_tokens: number` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - Total number of tokens used (prompt + completion). + 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). -### Example + - `beta_computer_tool: object { type }` -```cli -openai beta:threads:runs:steps retrieve \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id \ - --step-id step_id -``` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -#### Response + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } -} -``` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -## Domain Types + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` -### Code Interpreter Logs + 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). -- `code_interpreter_logs: object { index, type, logs }` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - Text output from the Code Interpreter tool call as part of a run step. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `index: number` + - `code_interpreter: object { container, type, allowed_callers }` - The index of the output in the outputs array. + A tool that runs Python code to help generate a response to a prompt. - - `type: "logs"` + - `programmatic_tool_calling: object { type }` - Always `logs`. + - `image_generation: object { type, action, background, 9 more }` - - `logs: optional string` + A tool that generates images using the GPT image models. - The text output from the Code Interpreter tool call. + - `local_shell: object { type }` -### Code Interpreter Output Image + A tool that allows the model to execute shell commands in a local environment. -- `code_interpreter_output_image: object { index, type, image }` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `index: number` + A tool that allows the model to execute shell commands. - The index of the output in the outputs array. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `type: "image"` + 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) - Always `image`. + - `beta_namespace_tool: object { description, name, tools, type }` - - `image: optional object { file_id }` + Groups function/custom tools under a shared namespace. - - `file_id: optional string` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + Hosted or BYOT tool search configuration for deferred tools. -### Code Interpreter Tool Call + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` -- `code_interpreter_tool_call: object { id, code_interpreter, type }` + 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). - Details of the Code Interpreter tool call the run step was involved in. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `id: string` + Allows the assistant to create, delete, or update files using unified diffs. - The ID of the tool call. + - `type: "additional_tools"` - - `code_interpreter: object { input, outputs }` + The type of the item. Always `additional_tools`. - The Code Interpreter tool call definition. + - `agent: optional object { agent_name }` - - `input: string` + The agent that produced this item. - The input to the Code Interpreter tool call. + - `agent_name: string` - - `outputs: array of object { logs, type } or object { image, type }` + The canonical name of the agent that produced this item. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - `logs: object { logs, type }` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - Text output from the Code Interpreter tool call as part of a run step. + - `id: string` - - `logs: string` + The unique ID of the compaction item. - The text output from the Code Interpreter tool call. + - `encrypted_content: string` - - `type: "logs"` + The encrypted content that was produced by compaction. - Always `logs`. + - `type: "compaction"` - - `image: object { image, type }` + The type of the item. Always `compaction`. - - `image: object { file_id }` + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `agent_name: string` - - `type: "image"` + The canonical name of the agent that produced this item. - Always `image`. + - `created_by: optional string` - - `type: "code_interpreter"` + The identifier of the actor that created the item. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `image_generation_call: object { id, result, status, 2 more }` -### Code Interpreter Tool Call Delta + An image generation request made by the model. -- `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` + - `id: string` - Details of the Code Interpreter tool call the run step was involved in. + The unique ID of the image generation call. - - `index: number` + - `result: string` - The index of the tool call in the tool calls array. + The generated image encoded in base64. - - `type: "code_interpreter"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The status of the image generation call. - - `id: optional string` + - `"in_progress"` - The ID of the tool call. + - `"completed"` - - `code_interpreter: optional object { input, outputs }` + - `"generating"` - The Code Interpreter tool call definition. + - `"failed"` - - `input: optional string` + - `type: "image_generation_call"` - The input to the Code Interpreter tool call. + The type of the image generation call. Always `image_generation_call`. - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `agent: optional object { agent_name }` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + The agent that produced this item. - - `code_interpreter_logs: object { index, type, logs }` + - `agent_name: string` - Text output from the Code Interpreter tool call as part of a run step. + The canonical name of the agent that produced this item. - - `index: number` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - The index of the output in the outputs array. + A tool call to run code. - - `type: "logs"` + - `id: string` - Always `logs`. + The unique ID of the code interpreter tool call. - - `logs: optional string` + - `code: string` - The text output from the Code Interpreter tool call. + The code to run, or null if not available. - - `code_interpreter_output_image: object { index, type, image }` + - `container_id: string` - - `index: number` + The ID of the container used to run the code. - The index of the output in the outputs array. + - `outputs: array of object { logs, type } or object { type, url }` - - `type: "image"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - Always `image`. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `image: optional object { file_id }` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `file_id: optional string` + - `type: "code_interpreter_call"` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + The type of the code interpreter tool call. Always `code_interpreter_call`. -### File Search Tool Call + - `agent: optional object { agent_name }` -- `file_search_tool_call: object { id, file_search, type }` + The agent that produced this item. - - `id: string` + - `local_shell_call: object { id, action, call_id, 3 more }` - The ID of the tool call object. + A tool call to run a command on the local shell. - - `file_search: object { ranking_options, results }` + - `id: string` - For now, this is always going to be an empty object. + The unique ID of the local shell call. - - `ranking_options: optional object { ranker, score_threshold }` + - `action: object { command, env, type, 3 more }` - The ranking options for the file search. + Execute a shell command on the server. - - `ranker: "auto" or "default_2024_08_21"` + - `command: array of string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The command to run. - - `"auto"` + - `env: map[string]` - - `"default_2024_08_21"` + Environment variables to set for the command. - - `score_threshold: number` + - `type: "exec"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The type of the local shell action. Always `exec`. - - `results: optional array of object { file_id, file_name, score, content }` + - `timeout_ms: optional number` - The results of the file search. + Optional timeout in milliseconds for the command. - - `file_id: string` + - `user: optional string` - The ID of the file that result was found in. + Optional user to run the command as. - - `file_name: string` + - `working_directory: optional string` - The name of the file that result was found in. + Optional working directory to run the command in. - - `score: number` + - `call_id: string` - The score of the result. All values must be a floating point number between 0 and 1. + The unique ID of the local shell tool call generated by the model. - - `content: optional array of object { text, type }` + - `status: "in_progress" or "completed" or "incomplete"` - The content of the result that was found. The content is only included if requested via the include query parameter. + The status of the local shell call. - - `text: optional string` + - `"in_progress"` - The text content of the file. + - `"completed"` - - `type: optional "text"` + - `"incomplete"` - The type of the content. + - `type: "local_shell_call"` - - `"text"` + The type of the local shell call. Always `local_shell_call`. - - `type: "file_search"` + - `agent: optional object { agent_name }` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The agent that produced this item. -### File Search Tool Call Delta + - `agent_name: string` -- `file_search_tool_call_delta: object { file_search, index, type, id }` + The canonical name of the agent that produced this item. - - `file_search: unknown` + - `local_shell_call_output: object { id, output, type, 2 more }` - For now, this is always going to be an empty object. + The output of a local shell tool call. - - `index: number` + - `id: string` - The index of the tool call in the tool calls array. + The unique ID of the local shell tool call generated by the model. - - `type: "file_search"` + - `output: string` - The type of tool call. This is always going to be `file_search` for this type of tool call. + A JSON string of the output of the local shell tool call. - - `id: optional string` + - `type: "local_shell_call_output"` - The ID of the tool call object. + The type of the local shell tool call output. Always `local_shell_call_output`. -### Function Tool Call + - `agent: optional object { agent_name }` -- `function_tool_call: object { id, function, type }` + The agent that produced this item. - - `id: string` + - `agent_name: string` - The ID of the tool call object. + The canonical name of the agent that produced this item. - - `function: object { arguments, name, output }` + - `status: optional "in_progress" or "completed" or "incomplete"` - The definition of the function that was called. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `arguments: string` + - `"in_progress"` - The arguments passed to the function. + - `"completed"` - - `name: string` + - `"incomplete"` - The name of the function. + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - `output: string` + A tool call that executes one or more shell commands in a managed environment. - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + - `id: string` - - `type: "function"` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of tool call. This is always going to be `function` for this type of tool call. + - `action: object { commands, max_output_length, timeout_ms }` -### Function Tool Call Delta + The shell commands and limits that describe how to run the tool call. -- `function_tool_call_delta: object { index, type, id, function }` + - `commands: array of string` - - `index: number` + - `max_output_length: number` - The index of the tool call in the tool calls array. + Optional maximum number of characters to return from each command. - - `type: "function"` + - `timeout_ms: number` - The type of tool call. This is always going to be `function` for this type of tool call. + Optional timeout in milliseconds for the commands. - - `id: optional string` + - `call_id: string` - The ID of the tool call object. + The unique ID of the shell tool call generated by the model. - - `function: optional object { arguments, name, output }` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The definition of the function that was called. + Represents the use of a local environment to perform shell actions. - - `arguments: optional string` + - `beta_response_local_environment: object { type }` - The arguments passed to the function. + Represents the use of a local environment to perform shell actions. - - `name: optional string` + - `type: "local"` - The name of the function. + The environment type. Always `local`. - - `output: optional string` + - `beta_response_container_reference: object { container_id, type }` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + Represents a container created with /v1/containers. -### Message Creation Step Details + - `container_id: string` -- `message_creation_step_details: object { message_creation, type }` + - `type: "container_reference"` - Details of the message creation by the run step. + The environment type. Always `container_reference`. - - `message_creation: object { message_id }` + - `status: "in_progress" or "completed" or "incomplete"` - - `message_id: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The ID of the message that was created by this run step. + - `"in_progress"` - - `type: "message_creation"` + - `"completed"` - Always `message_creation`. + - `"incomplete"` -### Run Step + - `type: "shell_call"` -- `run_step: object { id, assistant_id, cancelled_at, 13 more }` + The type of the item. Always `shell_call`. - Represents a step in execution of a run. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - The identifier of the run step, which can be referenced in API endpoints. + - `agent_name: string` - - `assistant_id: string` + The canonical name of the agent that produced this item. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. + - `caller: optional object { type } or object { caller_id, type }` - - `cancelled_at: number` + The execution context that produced this tool call. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `direct: object { type }` - - `completed_at: number` + - `program: object { caller_id, type }` - The Unix timestamp (in seconds) for when the run step completed. + - `caller_id: string` - - `created_at: number` + The call ID of the program item that produced this tool call. - The Unix timestamp (in seconds) for when the run step was created. + - `type: "program"` - - `expired_at: number` + - `created_by: optional string` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The ID of the entity that created this tool call. - - `failed_at: number` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - The Unix timestamp (in seconds) for when the run step failed. + The output of a shell tool call that was emitted. - - `last_error: object { code, message }` + - `id: string` - The last error associated with this run step. Will be `null` if there are no errors. + The unique ID of the shell call output. Populated when this item is returned via API. - - `code: "server_error" or "rate_limit_exceeded"` + - `call_id: string` - One of `server_error` or `rate_limit_exceeded`. + The unique ID of the shell tool call generated by the model. - - `"server_error"` + - `max_output_length: number` - - `"rate_limit_exceeded"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `message: string` + - `output: array of object { outcome, stderr, stdout, created_by }` - A human-readable description of the error. + An array of shell call output contents - - `metadata: map[string]` + - `outcome: object { type } or object { exit_code, type }` - 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. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `timeout: object { type }` - - `object: "thread.run.step"` + Indicates that the shell call exceeded its configured time limit. - The object type, which is always `thread.run.step`. + - `exit: object { exit_code, type }` - - `run_id: string` + Indicates that the shell commands finished and returned an exit code. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + - `exit_code: number` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + Exit code from the shell process. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `type: "exit"` - - `"in_progress"` + The outcome type. Always `exit`. - - `"cancelled"` + - `stderr: string` - - `"failed"` + The standard error output that was captured. - - `"completed"` + - `stdout: string` - - `"expired"` + The standard output that was captured. - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `created_by: optional string` - The details of the run step. + The identifier of the actor that created the item. - - `message_creation_step_details: object { message_creation, type }` + - `status: "in_progress" or "completed" or "incomplete"` - Details of the message creation by the run step. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `message_creation: object { message_id }` + - `"in_progress"` - - `message_id: string` + - `"completed"` - The ID of the message that was created by this run step. + - `"incomplete"` - - `type: "message_creation"` + - `type: "shell_call_output"` - Always `message_creation`. + The type of the shell call output. Always `shell_call_output`. - - `tool_calls_step_details: object { tool_calls, type }` + - `agent: optional object { agent_name }` - Details of the tool call. + The agent that produced this item. - - `tool_calls: array of unknown` + - `agent_name: string` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The canonical name of the agent that produced this item. - - `type: "tool_calls"` + - `caller: optional object { type } or object { caller_id, type }` - Always `tool_calls`. + The execution context that produced this tool call. - - `thread_id: string` + - `direct: object { type }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `program: object { caller_id, type }` - - `type: "message_creation" or "tool_calls"` + - `caller_id: string` - The type of run step, which can be either `message_creation` or `tool_calls`. + The call ID of the program item that produced this tool call. - - `"message_creation"` + - `type: "program"` - - `"tool_calls"` + - `created_by: optional string` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The identifier of the actor that created the item. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `completion_tokens: number` + A tool call that applies file diffs by creating, deleting, or updating files. - Number of completion tokens used over the course of the run step. + - `id: string` - - `prompt_tokens: number` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Number of prompt tokens used over the course of the run step. + - `call_id: string` - - `total_tokens: number` + The unique ID of the apply patch tool call generated by the model. - Total number of tokens used (prompt + completion). + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` -### Run Step Delta + One of the create_file, delete_file, or update_file operations applied via apply_patch. -- `run_step_delta: unknown` + - `create_file: object { diff, path, type }` -### Run Step Delta Event + Instruction describing how to create a file via the apply_patch tool. -- `run_step_delta_event: object { id, delta, object }` + - `diff: string` - Represents a run step delta i.e. any changed fields on a run step during streaming. + Diff to apply. - - `id: string` + - `path: string` - The identifier of the run step, which can be referenced in API endpoints. + Path of the file to create. - - `delta: unknown` + - `type: "create_file"` - - `object: "thread.run.step.delta"` + Create a new file with the provided diff. - The object type, which is always `thread.run.step.delta`. + - `delete_file: object { path, type }` -### Run Step Delta Message Delta + Instruction describing how to delete a file via the apply_patch tool. -- `run_step_delta_message_delta: object { type, message_creation }` + - `path: string` - Details of the message creation by the run step. + Path of the file to delete. - - `type: "message_creation"` + - `type: "delete_file"` - Always `message_creation`. + Delete the specified file. - - `message_creation: optional object { message_id }` + - `update_file: object { diff, path, type }` - - `message_id: optional string` + Instruction describing how to update a file via the apply_patch tool. - The ID of the message that was created by this run step. + - `diff: string` -### Run Step Include + Diff to apply. -- `run_step_include: "step_details.tool_calls[*].file_search.results[*].content"` + - `path: string` - - `"step_details.tool_calls[*].file_search.results[*].content"` + Path of the file to update. -### Tool Call + - `type: "update_file"` -- `tool_call: unknown` + Update an existing file with the provided diff. -### Tool Call Delta + - `status: "in_progress" or "completed"` -- `tool_call_delta: unknown` + The status of the apply patch tool call. One of `in_progress` or `completed`. -### Tool Call Delta Object + - `"in_progress"` -- `tool_call_delta_object: object { type, tool_calls }` + - `"completed"` - Details of the tool call. + - `type: "apply_patch_call"` - - `type: "tool_calls"` + The type of the item. Always `apply_patch_call`. - Always `tool_calls`. + - `agent: optional object { agent_name }` - - `tool_calls: optional array of unknown` + The agent that produced this item. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `agent_name: string` -### Tool Calls Step Details + The canonical name of the agent that produced this item. -- `tool_calls_step_details: object { tool_calls, type }` + - `caller: optional object { type } or object { caller_id, type }` - Details of the tool call. + The execution context that produced this tool call. - - `tool_calls: array of unknown` + - `direct: object { type }` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `program: object { caller_id, type }` - - `type: "tool_calls"` + - `caller_id: string` - Always `tool_calls`. + The call ID of the program item that produced this tool call. -# Messages + - `type: "program"` -## List messages + - `created_by: optional string` -`$ openai beta:threads:messages list` + The ID of the entity that created this tool call. -**get** `/threads/{thread_id}/messages` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` -List messages + The output emitted by an apply patch tool call. -### Parameters + - `id: string` -- `--thread-id: string` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) the messages belong to. + - `call_id: string` -- `--after: optional string` + The unique ID of the apply patch tool call generated by the model. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `status: "completed" or "failed"` -- `--before: optional string` + The status of the apply patch tool call output. One of `completed` or `failed`. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `"completed"` -- `--limit: optional number` + - `"failed"` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `type: "apply_patch_call_output"` -- `--order: optional "asc" or "desc"` + The type of the item. Always `apply_patch_call_output`. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `agent: optional object { agent_name }` -- `--run-id: optional string` + The agent that produced this item. - Filter messages by the run ID that generated them. + - `agent_name: string` -### Returns + The canonical name of the agent that produced this item. -- `ListMessagesResponse: object { data, first_id, has_more, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` - - `data: array of Message` + The execution context that produced this tool call. - - `id: string` + - `direct: object { type }` - The identifier, which can be referenced in API endpoints. + - `program: object { caller_id, type }` - - `assistant_id: string` + - `caller_id: string` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The call ID of the program item that produced this tool call. - - `attachments: array of object { file_id, tools }` + - `type: "program"` - A list of files attached to the message, and the tools they were added to. + - `created_by: optional string` - - `file_id: optional string` + The ID of the entity that created this tool call output. - The ID of the file to attach to the message. + - `output: optional string` - - `tools: optional array of CodeInterpreterTool or object { type }` + Optional textual output returned by the apply patch tool. - The tools to add this file to. + - `mcp_call: object { id, arguments, name, 7 more }` - - `code_interpreter_tool: object { type }` + An invocation of a tool on an MCP server. - - `type: "code_interpreter"` + - `id: string` - The type of tool being defined: `code_interpreter` + The unique ID of the tool call. - - `AssistantToolsFileSearchTypeOnly: object { type }` + - `arguments: string` - - `completed_at: number` + A JSON string of the arguments passed to the tool. - The Unix timestamp (in seconds) for when the message was completed. + - `name: string` - - `content: array of unknown` + The name of the tool that was run. - The content of the message in array of text and/or images. + - `server_label: string` - - `created_at: number` + The label of the MCP server running the tool. - The Unix timestamp (in seconds) for when the message was created. + - `type: "mcp_call"` - - `incomplete_at: number` + The type of the item. Always `mcp_call`. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `agent: optional object { agent_name }` - - `incomplete_details: object { reason }` + The agent that produced this item. - On an incomplete message, details about why the message is incomplete. + - `agent_name: string` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + The canonical name of the agent that produced this item. - The reason the message is incomplete. + - `approval_request_id: optional string` - - `"content_filter"` + 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. - - `"max_tokens"` + - `error: optional string` - - `"run_cancelled"` + The error from the tool call, if any. - - `"run_expired"` + - `output: optional string` - - `"run_failed"` + The output from the tool call. - - `metadata: map[string]` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - 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. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"in_progress"` - - `object: "thread.message"` + - `"completed"` - The object type, which is always `thread.message`. + - `"incomplete"` - - `role: "user" or "assistant"` + - `"calling"` - The entity that produced the message. One of `user` or `assistant`. + - `"failed"` - - `"user"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `"assistant"` + A list of tools available on an MCP server. - - `run_id: string` + - `id: string` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The unique ID of the list. - - `status: "in_progress" or "incomplete" or "completed"` + - `server_label: string` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The label of the MCP server. - - `"in_progress"` + - `tools: array of object { input_schema, name, annotations, description }` - - `"incomplete"` + The tools available on the server. - - `"completed"` + - `input_schema: unknown` - - `thread_id: string` + The JSON schema describing the tool's input. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `name: string` - - `first_id: string` + The name of the tool. - - `has_more: boolean` + - `annotations: optional unknown` - - `last_id: string` + Additional annotations about the tool. - - `object: string` + - `description: optional string` -### Example + The description of the tool. -```cli -openai beta:threads:messages list \ - --api-key 'My API Key' \ - --thread-id thread_id -``` + - `type: "mcp_list_tools"` -#### Response + The type of the item. Always `mcp_list_tools`. -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" - } - ], - "first_id": "msg_abc123", - "has_more": false, - "last_id": "msg_abc123", - "object": "list" -} -``` + - `agent: optional object { agent_name }` -## Create message + The agent that produced this item. -`$ openai beta:threads:messages create` + - `agent_name: string` -**post** `/threads/{thread_id}/messages` + The canonical name of the agent that produced this item. -Create message + - `error: optional string` -### Parameters + Error message if the server could not list tools. -- `--thread-id: string` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to create a message for. + A request for human approval of a tool invocation. -- `--content: string or array of MessageContentPartParam` + - `id: string` - The text contents of the message. + The unique ID of the approval request. -- `--role: "user" or "assistant"` + - `arguments: string` - The role of the entity that is creating the message. Allowed values include: + A JSON string of arguments for the tool. - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `name: string` -- `--attachment: optional array of object { file_id, tools }` + The name of the tool to run. - A list of files attached to the message, and the tools they should be added to. + - `server_label: string` -- `--metadata: optional map[string]` + The label of the MCP server making the request. - 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. + - `type: "mcp_approval_request"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The type of the item. Always `mcp_approval_request`. -### Returns + - `agent: optional object { agent_name }` -- `message: object { id, assistant_id, attachments, 11 more }` + The agent that produced this item. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The identifier, which can be referenced in API endpoints. + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - - `assistant_id: string` + A response to an MCP approval request. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `id: string` - - `attachments: array of object { file_id, tools }` + The unique ID of the approval response - A list of files attached to the message, and the tools they were added to. + - `approval_request_id: string` - - `file_id: optional string` + The ID of the approval request being answered. - The ID of the file to attach to the message. + - `approve: boolean` - - `tools: optional array of CodeInterpreterTool or object { type }` + Whether the request was approved. - The tools to add this file to. + - `type: "mcp_approval_response"` - - `code_interpreter_tool: object { type }` + The type of the item. Always `mcp_approval_response`. - - `type: "code_interpreter"` + - `agent: optional object { agent_name }` - The type of tool being defined: `code_interpreter` + The agent that produced this item. - - `AssistantToolsFileSearchTypeOnly: object { type }` + - `agent_name: string` - - `completed_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the message was completed. + - `reason: optional string` - - `content: array of unknown` + Optional reason for the decision. - The content of the message in array of text and/or images. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `created_at: number` + A call to a custom tool created by the model. - The Unix timestamp (in seconds) for when the message was created. + - `call_id: string` - - `incomplete_at: number` + An identifier used to map this custom tool call to a tool call output. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `input: string` - - `incomplete_details: object { reason }` + The input for the custom tool call generated by the model. - On an incomplete message, details about why the message is incomplete. + - `name: string` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + The name of the custom tool being called. - The reason the message is incomplete. + - `type: "custom_tool_call"` - - `"content_filter"` + The type of the custom tool call. Always `custom_tool_call`. - - `"max_tokens"` + - `id: optional string` - - `"run_cancelled"` + The unique ID of the custom tool call in the OpenAI platform. - - `"run_expired"` + - `agent: optional object { agent_name }` - - `"run_failed"` + The agent that produced this item. - - `metadata: map[string]` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `namespace: optional string` - - `object: "thread.message"` + The namespace of the custom tool being called. - The object type, which is always `thread.message`. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `role: "user" or "assistant"` + The output of a custom tool call from your code, being sent back to the model. - The entity that produced the message. One of `user` or `assistant`. + - `id: string` - - `"user"` + The unique ID of the custom tool call output item. - - `"assistant"` + - `status: "in_progress" or "completed" or "incomplete"` - - `run_id: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `"in_progress"` - - `status: "in_progress" or "incomplete" or "completed"` + - `"completed"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"incomplete"` - - `"in_progress"` + - `created_by: optional string` - - `"incomplete"` + The identifier of the actor that created the item. - - `"completed"` + - `parallel_tool_calls: boolean` - - `thread_id: string` + Whether to allow the model to run tool calls in parallel. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `temperature: number` -### Example + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. -```cli -openai beta:threads:messages create \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --content string \ - --role user -``` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` -#### Response + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `beta_tool_choice_options: "none" or "auto" or "required"` -## Modify message + Controls which (if any) tool is called by the model. -`$ openai beta:threads:messages update` + `none` means the model will not call any tool and instead generates a message. -**post** `/threads/{thread_id}/messages/{message_id}` + `auto` means the model can pick between generating a message or calling one or + more tools. -Modify message + `required` means the model must call one or more tools. -### Parameters + - `"none"` -- `--thread-id: string` + - `"auto"` - The ID of the thread to which this message belongs. + - `"required"` -- `--message-id: string` + - `beta_tool_choice_allowed: object { mode, tools, type }` - The ID of the message to modify. + Constrains the tools available to the model to a pre-defined set. -- `--metadata: optional map[string]` + - `mode: "auto" or "required"` - 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. + Constrains the tools available to the model to a pre-defined set. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + `auto` allows the model to pick from among the allowed tools and generate a + message. -### Returns + `required` requires the model to call one or more of the allowed tools. -- `message: object { id, assistant_id, attachments, 11 more }` + - `"auto"` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `"required"` - - `id: string` + - `tools: array of map[unknown]` - The identifier, which can be referenced in API endpoints. + A list of tool definitions that the model should be allowed to call. - - `assistant_id: string` + For the Responses API, the list of tool definitions might look like: - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `attachments: array of object { file_id, tools }` + - `type: "allowed_tools"` - A list of files attached to the message, and the tools they were added to. + Allowed tool configuration type. Always `allowed_tools`. - - `file_id: optional string` + - `beta_tool_choice_types: object { type }` - The ID of the file to attach to the message. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `tools: optional array of CodeInterpreterTool or object { type }` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - The tools to add this file to. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `code_interpreter_tool: object { type }` + Allowed values are: - - `type: "code_interpreter"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The type of tool being defined: `code_interpreter` + - `"file_search"` - - `AssistantToolsFileSearchTypeOnly: object { type }` + - `"web_search_preview"` - - `completed_at: number` + - `"computer"` - The Unix timestamp (in seconds) for when the message was completed. + - `"computer_use_preview"` - - `content: array of unknown` + - `"computer_use"` - The content of the message in array of text and/or images. + - `"web_search_preview_2025_03_11"` - - `created_at: number` + - `"image_generation"` - The Unix timestamp (in seconds) for when the message was created. + - `"code_interpreter"` - - `incomplete_at: number` + - `beta_tool_choice_function: object { name, type }` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Use this option to force the model to call a specific function. - - `incomplete_details: object { reason }` + - `name: string` - On an incomplete message, details about why the message is incomplete. + The name of the function to call. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `type: "function"` - The reason the message is incomplete. + For function calling, the type is always `function`. - - `"content_filter"` + - `beta_tool_choice_mcp: object { server_label, type, name }` - - `"max_tokens"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `"run_cancelled"` + - `server_label: string` - - `"run_expired"` + The label of the MCP server to use. - - `"run_failed"` + - `type: "mcp"` - - `metadata: map[string]` + For MCP tools, the type is always `mcp`. - 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. + - `name: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the tool to call on the server. - - `object: "thread.message"` + - `beta_tool_choice_custom: object { name, type }` - The object type, which is always `thread.message`. + Use this option to force the model to call a specific custom tool. - - `role: "user" or "assistant"` + - `name: string` - The entity that produced the message. One of `user` or `assistant`. + The name of the custom tool to call. - - `"user"` + - `type: "custom"` - - `"assistant"` + For custom tool calling, the type is always `custom`. - - `run_id: string` + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `beta_tool_choice_apply_patch: object { type }` - - `status: "in_progress" or "incomplete" or "completed"` + Forces the model to call the apply_patch tool when executing a tool call. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `type: "apply_patch"` - - `"in_progress"` + The tool to call. Always `apply_patch`. - - `"incomplete"` + - `beta_tool_choice_shell: object { type }` - - `"completed"` + Forces the model to call the shell tool when a tool call is required. - - `thread_id: string` + - `type: "shell"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The tool to call. Always `shell`. -### Example + - `tools: array of BetaTool` -```cli -openai beta:threads:messages update \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --message-id message_id -``` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. -#### Response + We support the following categories of tools: -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. -## Retrieve message + - `beta_function_tool: object { name, parameters, strict, 5 more }` -`$ openai beta:threads:messages retrieve` + 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). -**get** `/threads/{thread_id}/messages/{message_id}` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` -Retrieve message + 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). -### Parameters + - `beta_computer_tool: object { type }` -- `--thread-id: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to which this message belongs. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` -- `--message-id: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The ID of the message to retrieve. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` -### Returns + 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). -- `message: object { id, assistant_id, attachments, 11 more }` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `id: string` + - `code_interpreter: object { container, type, allowed_callers }` - The identifier, which can be referenced in API endpoints. + A tool that runs Python code to help generate a response to a prompt. - - `assistant_id: string` + - `programmatic_tool_calling: object { type }` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `image_generation: object { type, action, background, 9 more }` - - `attachments: array of object { file_id, tools }` + A tool that generates images using the GPT image models. - A list of files attached to the message, and the tools they were added to. + - `local_shell: object { type }` - - `file_id: optional string` + A tool that allows the model to execute shell commands in a local environment. - The ID of the file to attach to the message. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `tools: optional array of CodeInterpreterTool or object { type }` + A tool that allows the model to execute shell commands. - The tools to add this file to. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `code_interpreter_tool: object { type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: "code_interpreter"` + - `beta_namespace_tool: object { description, name, tools, type }` - The type of tool being defined: `code_interpreter` + Groups function/custom tools under a shared namespace. - - `AssistantToolsFileSearchTypeOnly: object { type }` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `completed_at: number` + Hosted or BYOT tool search configuration for deferred tools. - The Unix timestamp (in seconds) for when the message was completed. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `content: array of unknown` + 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). - The content of the message in array of text and/or images. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `created_at: number` + Allows the assistant to create, delete, or update files using unified diffs. - The Unix timestamp (in seconds) for when the message was created. + - `top_p: number` - - `incomplete_at: number` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + We generally recommend altering this or `temperature` but not both. - - `incomplete_details: object { reason }` + - `background: optional boolean` - On an incomplete message, details about why the message is incomplete. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `completed_at: optional number` - The reason the message is incomplete. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"content_filter"` + - `conversation: optional object { id }` - - `"max_tokens"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `"run_cancelled"` + - `id: string` - - `"run_expired"` + The unique ID of the conversation that this response was associated with. - - `"run_failed"` + - `max_output_tokens: optional number` - - `metadata: map[string]` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - 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. + - `max_tool_calls: optional number` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `object: "thread.message"` + - `moderation: optional object { input, output }` - The object type, which is always `thread.message`. + Moderation results for the response input and output, if moderated completions were requested. - - `role: "user" or "assistant"` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The entity that produced the message. One of `user` or `assistant`. + Moderation for the response input. - - `"user"` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `"assistant"` + A moderation result produced for the response input or output. - - `run_id: string` + - `categories: map[boolean]` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `status: "in_progress" or "incomplete" or "completed"` + - `category_applied_input_types: map[array of "text" or "image"]` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + Which modalities of input are reflected by the score for each category. - - `"in_progress"` + - `"text"` - - `"incomplete"` + - `"image"` - - `"completed"` + - `category_scores: map[number]` - - `thread_id: string` + A dictionary of moderation categories to scores. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `flagged: boolean` -### Example + A boolean indicating whether the content was flagged by any category. -```cli -openai beta:threads:messages retrieve \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --message-id message_id -``` + - `model: string` -#### Response + The moderation model that produced this result. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `type: "moderation_result"` -## Delete message + The object type, which was always `moderation_result` for successful moderation results. -`$ openai beta:threads:messages delete` + - `error: object { code, message, type }` -**delete** `/threads/{thread_id}/messages/{message_id}` + An error produced while attempting moderation for the response input or output. -Delete message + - `code: string` -### Parameters + The error code. -- `--thread-id: string` + - `message: string` - The ID of the thread to which this message belongs. + The error message. -- `--message-id: string` + - `type: "error"` - The ID of the message to delete. + The object type, which was always `error` for moderation failures. -### Returns + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` -- `message_deleted: object { id, deleted, object }` + Moderation for the response output. - - `id: string` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `deleted: boolean` + A moderation result produced for the response input or output. - - `object: "thread.message.deleted"` + - `categories: map[boolean]` -### Example + A dictionary of moderation categories to booleans, True if the input is flagged under this category. -```cli -openai beta:threads:messages delete \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --message-id message_id -``` + - `category_applied_input_types: map[array of "text" or "image"]` -#### Response + Which modalities of input are reflected by the score for each category. -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` - -## Domain Types - -### Annotation + - `"text"` -- `annotation: unknown` + - `"image"` -### Annotation Delta + - `category_scores: map[number]` -- `annotation_delta: unknown` + A dictionary of moderation categories to scores. -### File Citation Annotation + - `flagged: boolean` -- `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + A boolean indicating whether the content was flagged by any category. - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `model: string` - - `end_index: number` + The moderation model that produced this result. - - `file_citation: object { file_id }` + - `type: "moderation_result"` - - `file_id: string` + The object type, which was always `moderation_result` for successful moderation results. - The ID of the specific File the citation is from. + - `error: object { code, message, type }` - - `start_index: number` + An error produced while attempting moderation for the response input or output. - - `text: string` + - `code: string` - The text in the message content that needs to be replaced. + The error code. - - `type: "file_citation"` + - `message: string` - Always `file_citation`. + The error message. -### File Citation Delta Annotation + - `type: "error"` -- `file_citation_delta_annotation: object { index, type, end_index, 3 more }` + The object type, which was always `error` for moderation failures. - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `previous_response_id: optional string` - - `index: number` + 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`. - The index of the annotation in the text content part. + - `prompt: optional object { id, variables, version }` - - `type: "file_citation"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - Always `file_citation`. + - `id: string` - - `end_index: optional number` + The unique identifier of the prompt template to use. - - `file_citation: optional object { file_id, quote }` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `file_id: optional string` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The ID of the specific File the citation is from. + - `union_member_0: string` - - `quote: optional string` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The specific quote in the file. + A text input to the model. - - `start_index: optional number` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `text: optional string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The text in the message content that needs to be replaced. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` -### File Path Annotation + A file input to the model. -- `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + - `version: optional string` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + Optional version of the prompt template. - - `end_index: number` + - `prompt_cache_key: optional string` - - `file_path: object { file_id }` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `file_id: string` + - `prompt_cache_options: optional object { mode, ttl }` - The ID of the file that was generated. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `start_index: number` + - `mode: "implicit" or "explicit"` - - `text: string` + Whether implicit prompt-cache breakpoints were enabled. - The text in the message content that needs to be replaced. + - `"implicit"` - - `type: "file_path"` + - `"explicit"` - Always `file_path`. + - `ttl: "30m"` -### File Path Delta Annotation + The minimum lifetime applied to each cache breakpoint. -- `file_path_delta_annotation: object { index, type, end_index, 3 more }` + - `"30m"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `index: number` + Deprecated. Use `prompt_cache_options.ttl` instead. - The index of the annotation in the text content part. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `type: "file_path"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - Always `file_path`. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `end_index: optional number` + - `"in_memory"` - - `file_path: optional object { file_id }` + - `"24h"` - - `file_id: optional string` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The ID of the file that was generated. + **gpt-5 and o-series models only** - - `start_index: optional number` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `text: optional string` + - `context: optional "auto" or "current_turn" or "all_turns"` - The text in the message content that needs to be replaced. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. -### Image File + - `"auto"` -- `image_file: object { file_id, detail }` + - `"current_turn"` - - `file_id: string` + - `"all_turns"` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `detail: optional "auto" or "low" or "high"` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `"none"` - - `"auto"` + - `"minimal"` - `"low"` - - `"high"` + - `"medium"` -### Image File Content Block + - `"high"` -- `image_file_content_block: object { image_file, type }` + - `"xhigh"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"max"` - - `image_file: object { file_id, detail }` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `file_id: string` + **Deprecated:** use `summary` instead. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `detail: optional "auto" or "low" or "high"` + - `"auto"` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `"concise"` - - `"auto"` + - `"detailed"` - - `"low"` + - `mode: optional string or "standard" or "pro"` - - `"high"` + Controls the reasoning execution mode for the request. - - `type: "image_file"` + When returned on a response, this is the effective execution mode. - Always `image_file`. + - `"standard"` -### Image File Delta + - `"pro"` -- `image_file_delta: object { detail, file_id }` + - `summary: optional "auto" or "concise" or "detailed"` - - `detail: optional "auto" or "low" or "high"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - `"auto"` - - `"low"` + - `"concise"` - - `"high"` + - `"detailed"` - - `file_id: optional string` + - `safety_identifier: optional string` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). -### Image File Delta Block + - `service_tier: optional "auto" or "default" or "flex" or 2 more` -- `image_file_delta_block: object { index, type, image_file }` + Specifies the processing type used for serving the request. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `index: number` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The index of the content part in the message. + - `"auto"` - - `type: "image_file"` + - `"default"` - Always `image_file`. + - `"flex"` - - `image_file: optional object { detail, file_id }` + - `"scale"` - - `detail: optional "auto" or "low" or "high"` + - `"priority"` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `"auto"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"low"` + - `"completed"` - - `"high"` + - `"failed"` - - `file_id: optional string` + - `"in_progress"` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `"cancelled"` -### Image URL + - `"queued"` -- `image_url: object { url, detail }` + - `"incomplete"` - - `url: string` + - `text: optional object { format, verbosity }` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `detail: optional "auto" or "low" or "high"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - `"auto"` + An object specifying the format that the model must output. - - `"low"` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"high"` + The default format is `{ "type": "text" }` with no additional options. -### Image URL Content Block + **Not recommended for gpt-4o and newer models:** -- `image_url_content_block: object { image_url, type }` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - References an image URL in the content of a message. + - `text: object { type }` - - `image_url: object { url, detail }` + Default response format. Used to generate text responses. - - `url: string` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `detail: optional "auto" or "low" or "high"` + - `name: string` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `"auto"` + - `schema: map[unknown]` - - `"low"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"high"` + - `type: "json_schema"` - - `type: "image_url"` + The type of response format being defined. Always `json_schema`. - The type of the content part. + - `description: optional string` -### Image URL Delta + A description of what the response format is for, used by the model to + determine how to respond in the format. -- `image_url_delta: object { detail, url }` + - `strict: optional boolean` - - `detail: optional "auto" or "low" or "high"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `json_object: object { type }` - - `"auto"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - `"low"` + - `"medium"` + - `"high"` - - `url: optional string` + - `top_logprobs: optional number` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. -### Image URL Delta Block + - `truncation: optional "auto" or "disabled"` -- `image_url_delta_block: object { index, type, image_url }` + The truncation strategy to use for the model response. - References an image URL in the content of a message. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `index: number` + - `"auto"` - The index of the content part in the message. + - `"disabled"` - - `type: "image_url"` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - Always `image_url`. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `image_url: optional object { detail, url }` + - `input_tokens: number` - - `detail: optional "auto" or "low" or "high"` + The number of input tokens. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `"auto"` + A detailed breakdown of the input tokens. - - `"low"` + - `cache_write_tokens: number` - - `"high"` + The number of input tokens that were written to the cache. - - `url: optional string` + - `cached_tokens: number` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). -### Message + - `output_tokens: number` -- `message: object { id, assistant_id, attachments, 11 more }` + The number of output tokens. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `output_tokens_details: object { reasoning_tokens }` - - `id: string` + A detailed breakdown of the output tokens. - The identifier, which can be referenced in API endpoints. + - `reasoning_tokens: number` - - `assistant_id: string` + The number of reasoning tokens. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `total_tokens: number` - - `attachments: array of object { file_id, tools }` + The total number of tokens used. - A list of files attached to the message, and the tools they were added to. + - `user: optional string` - - `file_id: optional string` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The ID of the file to attach to the message. +### Example - - `tools: optional array of CodeInterpreterTool or object { type }` +```cli +openai beta:responses retrieve \ + --api-key 'My API Key' \ + --response-id resp_677efb5139a88190b512bc3fef8e535d +``` - The tools to add this file to. +#### Response - - `code_interpreter_tool: object { type }` +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "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" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "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 + }, + "user": "user-1234" +} +``` - - `type: "code_interpreter"` +## Delete a model response - The type of tool being defined: `code_interpreter` +`$ openai beta:responses delete` - - `AssistantToolsFileSearchTypeOnly: object { type }` +**delete** `/responses/{response_id}?beta=true` - - `completed_at: number` +Deletes a model response with the given ID. - The Unix timestamp (in seconds) for when the message was completed. +### Parameters - - `content: array of unknown` +- `--response-id: string` - The content of the message in array of text and/or images. + The ID of the response to delete. - - `created_at: number` +- `--beta: optional array of "responses_multi_agent=v1"` - The Unix timestamp (in seconds) for when the message was created. + Optional beta features to enable for this request. - - `incomplete_at: number` +### Example - The Unix timestamp (in seconds) for when the message was marked as incomplete. +```cli +openai beta:responses delete \ + --api-key 'My API Key' \ + --response-id resp_677efb5139a88190b512bc3fef8e535d +``` - - `incomplete_details: object { reason }` +## Cancel a response - On an incomplete message, details about why the message is incomplete. +`$ openai beta:responses cancel` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` +**post** `/responses/{response_id}/cancel?beta=true` - The reason the message is incomplete. +Cancels a model response with the given ID. Only responses created with +the `background` parameter set to `true` can be cancelled. +[Learn more](https://platform.openai.com/docs/guides/background). - - `"content_filter"` +### Parameters - - `"max_tokens"` +- `--response-id: string` - - `"run_cancelled"` + The ID of the response to cancel. - - `"run_expired"` +- `--beta: optional array of "responses_multi_agent=v1"` - - `"run_failed"` + Optional beta features to enable for this request. - - `metadata: map[string]` +### Returns - 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. +- `beta_response: object { id, created_at, error, 31 more }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: string` - - `object: "thread.message"` + Unique identifier for this Response. - The object type, which is always `thread.message`. + - `created_at: number` - - `role: "user" or "assistant"` + Unix timestamp (in seconds) of when this Response was created. - The entity that produced the message. One of `user` or `assistant`. + - `error: object { code, message }` - - `"user"` + An error object returned when the model fails to generate a Response. - - `"assistant"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `run_id: string` + The error code for the response. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `"server_error"` - - `status: "in_progress" or "incomplete" or "completed"` + - `"rate_limit_exceeded"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"invalid_prompt"` - - `"in_progress"` + - `"bio_policy"` - - `"incomplete"` + - `"vector_store_timeout"` - - `"completed"` + - `"invalid_image"` - - `thread_id: string` + - `"invalid_image_format"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `"invalid_base64_image"` -### Message Content + - `"invalid_image_url"` -- `message_content: unknown` + - `"image_too_large"` -### Message Content Delta + - `"image_too_small"` -- `message_content_delta: unknown` + - `"image_parse_error"` -### Message Content Part Param + - `"image_content_policy_violation"` -- `message_content_part_param: ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + - `"invalid_image_mode"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"image_file_too_large"` - - `image_file_content_block: object { image_file, type }` + - `"unsupported_image_media_type"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"empty_image_file"` - - `image_file: object { file_id, detail }` + - `"failed_to_download_image"` - - `file_id: string` + - `"image_file_not_found"` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `message: string` - - `detail: optional "auto" or "low" or "high"` + A human-readable description of the error. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `incomplete_details: object { reason }` - - `"auto"` + Details about why the response is incomplete. - - `"low"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `"high"` + The reason why the response is incomplete. - - `type: "image_file"` + - `"max_output_tokens"` - Always `image_file`. + - `"content_filter"` - - `image_url_content_block: object { image_url, type }` + - `instructions: string or array of BetaResponseInputItem` - References an image URL in the content of a message. + A system (or developer) message inserted into the model's context. - - `image_url: object { url, detail }` + When using 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. - - `url: string` + - `union_member_0: string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + A text input to the model, equivalent to a text input with the + `developer` role. - - `detail: optional "auto" or "low" or "high"` + - `Input item list: array of BetaResponseInputItem` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + A list of one or many input items to the model, containing + different content types. - - `"auto"` + - `beta_easy_input_message: object { content, role, phase, type }` - - `"low"` + 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. - - `"high"` + - `content: string or BetaResponseInputMessageContentList` - - `type: "image_url"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The type of the content part. + - `Text input: string` - - `text_content_block_param: object { text, type }` + A text input to the model. - The text content that is part of a message. + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - `text: string` + A list of one or many input items to the model, containing different content + types. - Text content to be sent to the model + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `type: "text"` + A text input to the model. - Always `text`. + - `text: string` -### Message Deleted + The text input to the model. -- `message_deleted: object { id, deleted, object }` + - `type: "input_text"` - - `id: string` + The type of the input item. Always `input_text`. - - `deleted: boolean` + - `prompt_cache_breakpoint: optional object { mode }` - - `object: "thread.message.deleted"` + 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. -### Message Delta + - `mode: "explicit"` -- `message_delta: object { content, role }` + The breakpoint mode. Always `explicit`. - The delta containing the fields that have changed on the Message. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `content: optional array of unknown` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The content of the message in array of text and/or images. + - `detail: "low" or "high" or "auto" or "original"` - - `role: optional "user" or "assistant"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The entity that produced the message. One of `user` or `assistant`. + - `"low"` - - `"user"` + - `"high"` - - `"assistant"` + - `"auto"` -### Message Delta Event + - `"original"` -- `message_delta_event: object { id, delta, object }` + - `type: "input_image"` - Represents a message delta i.e. any changed fields on a message during streaming. + The type of the input item. Always `input_image`. - - `id: string` + - `file_id: optional string` - The identifier of the message, which can be referenced in API endpoints. + The ID of the file to be sent to the model. - - `delta: object { content, role }` + - `image_url: optional string` - The delta containing the fields that have changed on the Message. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `content: optional array of unknown` + - `prompt_cache_breakpoint: optional object { mode }` - The content of the message in array of text and/or images. + 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. - - `role: optional "user" or "assistant"` + - `mode: "explicit"` - The entity that produced the message. One of `user` or `assistant`. + The breakpoint mode. Always `explicit`. - - `"user"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"assistant"` + A file input to the model. - - `object: "thread.message.delta"` + - `type: "input_file"` - The object type, which is always `thread.message.delta`. + The type of the input item. Always `input_file`. -### Refusal Content Block + - `detail: optional "auto" or "low" or "high"` -- `refusal_content_block: object { refusal, type }` + 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`. - The refusal content generated by the assistant. + - `"auto"` - - `refusal: string` + - `"low"` - - `type: "refusal"` + - `"high"` - Always `refusal`. + - `file_data: optional string` -### Refusal Delta Block + The content of the file to be sent to the model. -- `refusal_delta_block: object { index, type, refusal }` + - `file_id: optional string` - The refusal content that is part of a message. + The ID of the file to be sent to the model. - - `index: number` + - `file_url: optional string` - The index of the refusal part in the message. + The URL of the file to be sent to the model. - - `type: "refusal"` + - `filename: optional string` - Always `refusal`. + The name of the file to be sent to the model. - - `refusal: optional string` + - `prompt_cache_breakpoint: optional object { mode }` -### Text + 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. -- `text: object { annotations, value }` + - `mode: "explicit"` - - `annotations: array of unknown` + The breakpoint mode. Always `explicit`. - - `value: string` + - `role: "user" or "assistant" or "system" or "developer"` - The data that makes up the text. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. -### Text Content Block + - `"user"` -- `text_content_block: object { text, type }` + - `"assistant"` - The text content that is part of a message. + - `"system"` - - `text: object { annotations, value }` + - `"developer"` - - `annotations: array of unknown` + - `phase: optional "commentary" or "final_answer"` - - `value: string` + 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. - The data that makes up the text. + - `"commentary"` - - `type: "text"` + - `"final_answer"` - Always `text`. + - `type: optional "message"` -### Text Content Block Param + The type of the message input. Always `message`. -- `text_content_block_param: object { text, type }` + - `"message"` - The text content that is part of a message. + - `message: object { content, role, agent, 2 more }` - - `text: string` + 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. - Text content to be sent to the model + - `content: array of BetaResponseInputContent` - - `type: "text"` + A list of one or many input items to the model, containing different content + types. - Always `text`. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` -### Text Delta + A text input to the model. -- `text_delta: object { annotations, value }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `annotations: optional array of unknown` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `value: optional string` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The data that makes up the text. + A file input to the model. -### Text Delta Block + - `role: "user" or "system" or "developer"` -- `text_delta_block: object { index, type, text }` + The role of the message input. One of `user`, `system`, or `developer`. - The text content that is part of a message. + - `"user"` - - `index: number` + - `"system"` - The index of the content part in the message. + - `"developer"` - - `type: "text"` + - `agent: optional object { agent_name }` - Always `text`. + The agent that produced this item. - - `text: optional object { annotations, value }` + - `agent_name: string` - - `annotations: optional array of unknown` + The canonical name of the agent that produced this item. - - `value: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The data that makes up the text. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -# Responses + - `"in_progress"` -## Create a model response + - `"completed"` -`$ openai beta:responses create` + - `"incomplete"` -**post** `/responses?beta=true` + - `type: optional "message"` -Create a model response + The type of the message input. Always set to `message`. -### Parameters + - `"message"` -- `--background: optional boolean` + - `beta_response_output_message: object { id, content, role, 4 more }` - Body param: Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + An output message from the model. -- `--context-management: optional array of object { type, compact_threshold }` + - `id: string` - Body param: Context management configuration for this request. + The unique ID of the output message. -- `--conversation: optional string or BetaResponseConversationParam` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Body param: The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + The content of the output message. -- `--include: optional array of BetaResponseIncludable` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - Body param: Specify additional output data to include in the model response. Currently supported values are: + A text output from the model. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` -- `--input: optional string or BetaResponseInput` + The annotations of the text output. - Body param: Text, image, or file inputs to the model, used to generate a response. + - `file_citation: object { file_id, filename, index, type }` - Learn more: + A citation to a file. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) + - `file_id: string` -- `--instructions: optional string` + The ID of the file. - Body param: A system (or developer) message inserted into the model's context. + - `filename: string` - When using 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. + The filename of the file cited. -- `--max-output-tokens: optional number` + - `index: number` - Body param: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The index of the file in the list of files. -- `--max-tool-calls: optional number` + - `type: "file_citation"` - Body param: The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The type of the file citation. Always `file_citation`. -- `--metadata: optional map[string]` + - `url_citation: object { end_index, start_index, title, 2 more }` - Body param: 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. + A citation for a web resource used to generate a model response. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `end_index: number` -- `--model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + The index of the last character of the URL citation in the message. - Body param: Model ID used to generate the response, like `gpt-4o` 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. + - `start_index: number` -- `--moderation: optional object { model, policy }` + The index of the first character of the URL citation in the message. - Body param: Configuration for running moderation on the input and output of this response. + - `title: string` -- `--multi-agent: optional object { enabled, max_concurrent_subagents }` + The title of the web resource. - Body param: Configuration for server-hosted multi-agent execution. + - `type: "url_citation"` -- `--parallel-tool-calls: optional boolean` + The type of the URL citation. Always `url_citation`. - Body param: Whether to allow the model to run tool calls in parallel. + - `url: string` -- `--previous-response-id: optional string` + The URL of the web resource. - Body param: 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`. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` -- `--prompt: optional object { id, variables, version }` + A citation for a container file used to generate a model response. - Body param: Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `container_id: string` -- `--prompt-cache-key: optional string` + The ID of the container file. - Body param: Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `end_index: number` -- `--prompt-cache-options: optional object { mode, ttl }` + The index of the last character of the container file citation in the message. - Body param: 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. + - `file_id: string` -- `--prompt-cache-retention: optional "in_memory" or "24h"` + The ID of the file. - Body param: Deprecated. Use `prompt_cache_options.ttl` instead. + - `filename: string` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The filename of the container file cited. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `start_index: number` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The index of the first character of the container file citation in the message. -- `--reasoning: optional object { context, effort, generate_summary, 2 more }` + - `type: "container_file_citation"` - Body param: **gpt-5 and o-series models only** + The type of the container file citation. Always `container_file_citation`. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `file_path: object { file_id, index, type }` -- `--safety-identifier: optional string` - - Body param: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - -- `--service-tier: optional "auto" or "default" or "flex" or 2 more` - - Body param: Specifies the processing type used for serving the request. - - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. - - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - -- `--store: optional boolean` - - Body param: Whether to store the generated model response for later retrieval via - API. - -- `--stream-options: optional object { include_obfuscation }` - - Body param: Options for streaming responses. Only set this when you set `stream: true`. - -- `--temperature: optional number` - - Body param: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. - -- `--text: optional object { format, verbosity }` - - Body param: Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: - - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - -- `--tool-choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - Body param: How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. - -- `--tool: optional array of BetaTool` - - Body param: An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. - - We support the following categories of tools: - - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. - -- `--top-logprobs: optional number` - - Body param: An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - -- `--top-p: optional number` - - Body param: An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. - - We generally recommend altering this or `temperature` but not both. - -- `--truncation: optional "auto" or "disabled"` - - Body param: The truncation strategy to use for the model response. - - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. - -- `--user: optional string` - - Body param: This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - -- `--beta: optional array of "responses_multi_agent=v1"` - - Header param: Optional beta features to enable for this request. - -### Returns - -- `beta_response: object { id, created_at, error, 31 more }` - - - `id: string` - - Unique identifier for this Response. - - - `created_at: number` - - Unix timestamp (in seconds) of when this Response was created. - - - `error: object { code, message }` - - An error object returned when the model fails to generate a Response. - - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - The error code for the response. - - - `"server_error"` - - - `"rate_limit_exceeded"` - - - `"invalid_prompt"` - - - `"bio_policy"` - - - `"vector_store_timeout"` - - - `"invalid_image"` - - - `"invalid_image_format"` - - - `"invalid_base64_image"` - - - `"invalid_image_url"` - - - `"image_too_large"` - - - `"image_too_small"` - - - `"image_parse_error"` - - - `"image_content_policy_violation"` - - - `"invalid_image_mode"` - - - `"image_file_too_large"` - - - `"unsupported_image_media_type"` - - - `"empty_image_file"` - - - `"failed_to_download_image"` - - - `"image_file_not_found"` - - - `message: string` - - A human-readable description of the error. - - - `incomplete_details: object { reason }` - - Details about why the response is incomplete. - - - `reason: optional "max_output_tokens" or "content_filter"` - - The reason why the response is incomplete. - - - `"max_output_tokens"` - - - `"content_filter"` - - - `instructions: string or array of BetaResponseInputItem` - - A system (or developer) message inserted into the model's context. - - When using 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. - - - `union_member_0: string` - - A text input to the model, equivalent to a text input with the - `developer` role. - - - `Input item list: array of BetaResponseInputItem` - - A list of one or many input items to the model, containing - different content types. - - - `beta_easy_input_message: object { content, role, phase, type }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: string or BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `Text input: string` - - A text input to the model. - - - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `role: "user" or "assistant" or "system" or "developer"` - - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"developer"` - - - `phase: optional "commentary"` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` - - - `type: optional "message"` - - The type of the message input. Always `message`. - - - `"message"` - - - `message: object { content, role, agent, 2 more }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. - - - `content: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `role: "user" or "system" or "developer"` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `"user"` - - - `"system"` - - - `"developer"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: optional "message"` - - The type of the message input. Always set to `message`. - - - `"message"` - - - `beta_response_output_message: object { id, content, role, 4 more }` - - An output message from the model. - - - `id: string` - - The unique ID of the output message. - - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - The content of the output message. - - - `beta_response_output_text: object { annotations, text, type, logprobs }` - - A text output from the model. - - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - The annotations of the text output. - - - `file_citation: object { file_id, filename, index, type }` - - A citation to a file. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the file cited. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_citation"` - - The type of the file citation. Always `file_citation`. - - - `url_citation: object { end_index, start_index, title, 2 more }` - - A citation for a web resource used to generate a model response. - - - `end_index: number` - - The index of the last character of the URL citation in the message. - - - `start_index: number` - - The index of the first character of the URL citation in the message. - - - `title: string` - - The title of the web resource. - - - `type: "url_citation"` - - The type of the URL citation. Always `url_citation`. - - - `url: string` - - The URL of the web resource. - - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - A citation for a container file used to generate a model response. - - - `container_id: string` - - The ID of the container file. - - - `end_index: number` - - The index of the last character of the container file citation in the message. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the container file cited. - - - `start_index: number` - - The index of the first character of the container file citation in the message. - - - `type: "container_file_citation"` - - The type of the container file citation. Always `container_file_citation`. - - - `file_path: object { file_id, index, type }` - - A path to a file. + A path to a file. - `file_id: string` @@ -15219,7 +13837,7 @@ Create a model response The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -15227,6 +13845,8 @@ Create a model response - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -16337,7 +14957,7 @@ Create a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -16347,7 +14967,11 @@ Create a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -16394,7 +15018,7 @@ Create a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -16404,7 +15028,11 @@ Create a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -18698,7 +17326,7 @@ Create a model response The agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -21081,8 +19709,9 @@ Create a model response ### Example ```cli -openai beta:responses create \ - --api-key 'My API Key' +openai beta:responses cancel \ + --api-key 'My API Key' \ + --response-id resp_677efb5139a88190b512bc3fef8e535d ``` #### Response @@ -21260,339 +19889,74 @@ openai beta:responses create \ } ``` -## Get a model response - -`$ openai beta:responses retrieve` - -**get** `/responses/{response_id}?beta=true` - -Get a model response - -### Parameters - -- `--response-id: string` - - Path param: The ID of the response to retrieve. - -- `--include: optional array of BetaResponseIncludable` - - Query param: Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. - -- `--include-obfuscation: optional boolean` - - Query param: When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events - to normalize payload sizes as a mitigation to certain side-channel - attacks. These obfuscation fields are included by default, but add a - small amount of overhead to the data stream. You can set - `include_obfuscation` to false to optimize for bandwidth if you trust - the network links between your application and the OpenAI API. - -- `--starting-after: optional number` - - Query param: The sequence number of the event after which to start streaming. - -- `--beta: optional array of "responses_multi_agent=v1"` - - Header param: Optional beta features to enable for this request. - -### Returns - -- `beta_response: object { id, created_at, error, 31 more }` - - - `id: string` - - Unique identifier for this Response. - - - `created_at: number` - - Unix timestamp (in seconds) of when this Response was created. - - - `error: object { code, message }` - - An error object returned when the model fails to generate a Response. - - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - The error code for the response. - - - `"server_error"` - - - `"rate_limit_exceeded"` - - - `"invalid_prompt"` - - - `"bio_policy"` - - - `"vector_store_timeout"` - - - `"invalid_image"` - - - `"invalid_image_format"` - - - `"invalid_base64_image"` - - - `"invalid_image_url"` - - - `"image_too_large"` - - - `"image_too_small"` - - - `"image_parse_error"` - - - `"image_content_policy_violation"` - - - `"invalid_image_mode"` - - - `"image_file_too_large"` - - - `"unsupported_image_media_type"` - - - `"empty_image_file"` - - - `"failed_to_download_image"` - - - `"image_file_not_found"` - - - `message: string` - - A human-readable description of the error. - - - `incomplete_details: object { reason }` - - Details about why the response is incomplete. - - - `reason: optional "max_output_tokens" or "content_filter"` - - The reason why the response is incomplete. - - - `"max_output_tokens"` - - - `"content_filter"` - - - `instructions: string or array of BetaResponseInputItem` - - A system (or developer) message inserted into the model's context. - - When using 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. - - - `union_member_0: string` - - A text input to the model, equivalent to a text input with the - `developer` role. - - - `Input item list: array of BetaResponseInputItem` - - A list of one or many input items to the model, containing - different content types. - - - `beta_easy_input_message: object { content, role, phase, type }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: string or BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `Text input: string` - - A text input to the model. - - - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `role: "user" or "assistant" or "system" or "developer"` - - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - - - `"user"` - - - `"assistant"` - - - `"system"` +## Compact a response - - `"developer"` +`$ openai beta:responses compact` - - `phase: optional "commentary"` +**post** `/responses/compact?beta=true` - 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. +Compact a conversation. Returns a compacted response object. - - `"commentary"` +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). - - `type: optional "message"` - - The type of the message input. Always `message`. +### Parameters - - `"message"` +- `--model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `message: object { content, role, agent, 2 more }` + Body param: 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. - 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. +- `--input: optional string or array of BetaResponseInputItem` - - `content: array of BetaResponseInputContent` + Body param: Text, image, or file inputs to the model, used to generate a response - A list of one or many input items to the model, containing different content - types. +- `--instructions: optional string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + Body param: 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. - A text input to the model. +- `--previous-response-id: optional string` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + Body param: 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`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). +- `--prompt-cache-key: optional string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Body param: A key to use when reading from or writing to the prompt cache. - A file input to the model. +- `--prompt-cache-options: optional object { mode, ttl }` - - `role: "user" or "system" or "developer"` + Body param: 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. - The role of the message input. One of `user`, `system`, or `developer`. +- `--prompt-cache-retention: optional "in_memory" or "24h"` - - `"user"` + Body param: How long to retain a prompt cache entry created by this request. - - `"system"` +- `--service-tier: optional "auto" or "default" or "flex" or "priority"` - - `"developer"` + Body param: The service tier to use for this request. - - `agent: optional object { agent_name }` +- `--beta: optional array of "responses_multi_agent=v1"` - The agent that produced this item. + Header param: Optional beta features to enable for this request. - - `agent_name: string` +### Returns - The canonical name of the agent that produced this item. +- `beta_compacted_response: object { id, created_at, object, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `id: string` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique identifier for the compacted response. - - `"in_progress"` + - `created_at: number` - - `"completed"` + Unix timestamp (in seconds) when the compacted conversation was created. - - `"incomplete"` + - `object: "response.compaction"` - - `type: optional "message"` + The object type. Always `response.compaction`. - The type of the message input. Always set to `message`. + - `output: array of BetaResponseOutputItem` - - `"message"` + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - `beta_response_output_message: object { id, content, role, 4 more }` @@ -21765,7 +20129,7 @@ Get a model response The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -21773,6 +20137,8 @@ Get a model response - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -21847,36 +20213,58 @@ Get a model response The text that was retrieved from the file. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - 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. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `call_id: string` - An identifier used when responding to the tool call with output. + The unique ID of the function tool call generated by the model. - - `pending_safety_checks: array of object { id, code, message }` + - `name: string` - The pending safety checks for the computer call. + The name of the function to run. - - `id: string` + - `type: "function_call"` - The ID of the pending safety check. + The type of the function tool call. Always `function_call`. - - `code: optional string` + - `id: optional string` - The type of the pending safety check. + The unique ID of the function tool call. - - `message: optional string` + - `agent: optional object { agent_name }` - Details about the pending safety check. + The agent that produced this item. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -21887,278 +20275,333 @@ Get a model response - `"incomplete"` - - `type: "computer_call"` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - The type of the computer call. Always `computer_call`. + - `id: string` - - `"computer_call"` + The unique ID of the function call tool output. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `call_id: string` - A click action. + The unique ID of the function tool call generated by the model. - - `click: object { button, type, x, 2 more }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A click action. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `button: "left" or "right" or "wheel" or 2 more` + - `string output: string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + A string of the output of the function call. - - `"left"` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"right"` + Text, image, or file output of the function call. - - `"wheel"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"back"` + A text input to the model. - - `"forward"` + - `text: string` - - `type: "click"` + The text input to the model. - Specifies the event type. For a click action, this property is always `click`. + - `type: "input_text"` - - `x: number` + The type of the input item. Always `input_text`. - The x-coordinate where the click occurred. + - `prompt_cache_breakpoint: optional object { mode }` - - `y: number` + 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. - The y-coordinate where the click occurred. + - `mode: "explicit"` - - `keys: optional array of string` + The breakpoint mode. Always `explicit`. - The keys being held while clicking. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `double_click: object { keys, type, x, y }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A double click action. + - `detail: "low" or "high" or "auto" or "original"` - - `keys: array of string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The keys being held while double-clicking. + - `"low"` - - `type: "double_click"` + - `"high"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"auto"` - - `x: number` + - `"original"` - The x-coordinate where the double click occurred. + - `type: "input_image"` - - `y: number` + The type of the input item. Always `input_image`. - The y-coordinate where the double click occurred. + - `file_id: optional string` - - `drag: object { path, type, keys }` + The ID of the file to be sent to the model. - A drag action. + - `image_url: optional string` - - `path: array of object { x, y }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `prompt_cache_breakpoint: optional object { mode }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + 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. - - `x: number` + - `mode: "explicit"` - The x-coordinate. + The breakpoint mode. Always `explicit`. - - `y: number` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The y-coordinate. + A file input to the model. - - `type: "drag"` + - `type: "input_file"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The type of the input item. Always `input_file`. - - `keys: optional array of string` + - `detail: optional "auto" or "low" or "high"` - The keys being held while dragging the mouse. + 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`. - - `keypress: object { keys, type }` + - `"auto"` - A collection of keypresses the model would like to perform. + - `"low"` - - `keys: array of string` + - `"high"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `file_data: optional string` - - `type: "keypress"` + The content of the file to be sent to the model. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `file_id: optional string` - - `move: object { type, x, y, keys }` + The ID of the file to be sent to the model. - A mouse move action. + - `file_url: optional string` - - `type: "move"` + The URL of the file to be sent to the model. - Specifies the event type. For a move action, this property is always set to `move`. + - `filename: optional string` - - `x: number` + The name of the file to be sent to the model. - The x-coordinate to move to. + - `prompt_cache_breakpoint: optional object { mode }` - - `y: number` + 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. - The y-coordinate to move to. + - `mode: "explicit"` - - `keys: optional array of string` + The breakpoint mode. Always `explicit`. - The keys being held while moving the mouse. + - `status: "in_progress" or "completed" or "incomplete"` - - `screenshot: object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A screenshot action. + - `"in_progress"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"completed"` - A scroll action. + - `"incomplete"` - - `scroll_x: number` + - `type: "function_call_output"` - The horizontal scroll distance. + The type of the function tool call output. Always `function_call_output`. - - `scroll_y: number` + - `agent: optional object { agent_name }` - The vertical scroll distance. + The agent that produced this item. - - `type: "scroll"` + - `agent_name: string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The canonical name of the agent that produced this item. - - `x: number` + - `caller: optional object { type } or object { caller_id, type }` - The x-coordinate where the scroll occurred. + The execution context that produced this tool call. - - `y: number` + - `direct: object { type }` - The y-coordinate where the scroll occurred. + - `program: object { caller_id, type }` - - `keys: optional array of string` + - `caller_id: string` - The keys being held while scrolling. + The call ID of the program item that produced this tool call. - - `type: object { text, type }` + - `type: "program"` - An action to type in text. + The caller type. Always `program`. - - `text: string` + - `created_by: optional string` - The text to type. + The identifier of the actor that created the item. - - `type: "type"` + - `agent_message: object { id, author, content, 3 more }` - Specifies the event type. For a type action, this property is always set to `type`. + - `id: string` - - `wait: object { type }` + The unique ID of the agent message. - A wait action. + - `author: string` - - `actions: optional array of BetaComputerAction` + The sending agent identity. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `click: object { button, type, x, 2 more }` + Encrypted content sent between agents. - A click action. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `double_click: object { keys, type, x, y }` + A text input to the model. - A double click action. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `drag: object { path, type, keys }` + A text output from the model. - A drag action. + - `text: object { text, type }` - - `keypress: object { keys, type }` + A text content. - A collection of keypresses the model would like to perform. + - `text: string` - - `move: object { type, x, y, keys }` + - `type: "text"` - A mouse move action. + - `summary_text: object { text, type }` - - `screenshot: object { type }` + A summary text from the model. - A screenshot action. + - `text: string` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + A summary of the reasoning output from the model so far. - A scroll action. + - `type: "summary_text"` - - `type: object { text, type }` + The type of the object. Always `summary_text`. - An action to type in text. + - `reasoning_text: object { text, type }` - - `wait: object { type }` + Reasoning text from the model. - A wait action. + - `text: string` - - `agent: optional object { agent_name }` + The reasoning text from the model. - The agent that produced this item. + - `type: "reasoning_text"` - - `agent_name: string` + The type of the reasoning text. Always `reasoning_text`. - The canonical name of the agent that produced this item. + - `beta_response_output_refusal: object { refusal, type }` - - `computer_call_output: object { call_id, output, type, 4 more }` + A refusal from the model. - The output of a computer tool call. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `call_id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The ID of the computer tool call that produced the output. + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - - `output: object { type, file_id, image_url }` + A screenshot of a computer. - A computer screenshot image used with the computer use tool. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "computer_screenshot"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"low"` - - `file_id: optional string` + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` The identifier of an uploaded file that contains the screenshot. - - `image_url: optional string` + - `image_url: string` The URL of the screenshot image. - - `type: "computer_call_output"` + - `type: "computer_screenshot"` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `id: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the computer tool call output. + 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. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `mode: "explicit"` - The safety checks reported by the API that have been acknowledged by the developer. + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { id, action, arguments, 3 more }` - `id: string` - The ID of the pending safety check. + The unique ID of the multi-agent call item. - - `code: optional string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The type of the pending safety check. + The multi-agent action to execute. - - `message: optional string` + - `"spawn_agent"` - Details about the pending safety check. + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` @@ -22168,15 +20611,61 @@ Get a model response The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `id: string` - - `"in_progress"` + The unique ID of the multi-agent call output item. - - `"completed"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"incomplete"` + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of BetaResponseOutputText` + + Text output returned by the multi-agent action. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `type: "multi_agent_call_output"` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `beta_response_function_web_search: object { id, action, status, 2 more }` @@ -22272,303 +20761,330 @@ Get a model response The canonical name of the agent that produced this item. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + 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. - - `arguments: string` + - `id: string` - A JSON string of the arguments to pass to the function. + The unique ID of the computer call. - `call_id: string` - The unique ID of the function tool call generated by the model. + An identifier used when responding to the tool call with output. - - `name: string` + - `pending_safety_checks: array of object { id, code, message }` - The name of the function to run. + The pending safety checks for the computer call. - - `type: "function_call"` + - `id: string` - The type of the function tool call. Always `function_call`. + The ID of the pending safety check. - - `id: optional string` + - `code: optional string` - The unique ID of the function tool call. + The type of the pending safety check. - - `agent: optional object { agent_name }` + - `message: optional string` - The agent that produced this item. + Details about the pending safety check. - - `agent_name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `caller: optional object { type } or object { caller_id, type }` + - `"in_progress"` - The execution context that produced this tool call. + - `"completed"` - - `direct: object { type }` + - `"incomplete"` - - `program: object { caller_id, type }` + - `type: "computer_call"` - - `caller_id: string` + The type of the computer call. Always `computer_call`. - The call ID of the program item that produced this tool call. + - `"computer_call"` - - `type: "program"` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `namespace: optional string` + A click action. - The namespace of the function to run. + - `click: object { button, type, x, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A click action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `button: "left" or "right" or "wheel" or 2 more` - - `"in_progress"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"completed"` + - `"left"` - - `"incomplete"` + - `"right"` - - `function_call_output: object { call_id, output, type, 4 more }` + - `"wheel"` - The output of a function tool call. + - `"back"` - - `call_id: string` + - `"forward"` - The unique ID of the function tool call generated by the model. + - `type: "click"` - - `output: string or BetaResponseFunctionCallOutputItemList` + Specifies the event type. For a click action, this property is always `click`. - Text, image, or file output of the function tool call. + - `x: number` - - `union_member_0: string` + The x-coordinate where the click occurred. - A JSON string of the output of the function tool call. + - `y: number` - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + The y-coordinate where the click occurred. - An array of content outputs (text, image, file) for the function tool call. + - `keys: optional array of string` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + The keys being held while clicking. - A text input to the model. + - `double_click: object { keys, type, x, y }` - - `text: string` + A double click action. - The text input to the model. + - `keys: array of string` - - `type: "input_text"` + The keys being held while double-clicking. - The type of the input item. Always `input_text`. + - `type: "double_click"` - - `prompt_cache_breakpoint: optional object { mode }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - 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. + - `x: number` - - `mode: "explicit"` + The x-coordinate where the double click occurred. - The breakpoint mode. Always `explicit`. + - `y: number` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + The y-coordinate where the double click occurred. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `drag: object { path, type, keys }` - - `type: "input_image"` + A drag action. - The type of the input item. Always `input_image`. + - `path: array of object { x, y }` - - `detail: optional "low" or "high" or "auto" or "original"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"low"` + - `x: number` - - `"high"` + The x-coordinate. - - `"auto"` + - `y: number` - - `"original"` + The y-coordinate. - - `file_id: optional string` + - `type: "drag"` - The ID of the file to be sent to the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `image_url: optional string` + - `keys: optional array of string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The keys being held while dragging the mouse. - - `prompt_cache_breakpoint: optional object { mode }` + - `keypress: object { keys, type }` - 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. + A collection of keypresses the model would like to perform. - - `mode: "explicit"` + - `keys: array of string` - The breakpoint mode. Always `explicit`. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `type: "keypress"` - A file input to the model. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: "input_file"` + - `move: object { type, x, y, keys }` - The type of the input item. Always `input_file`. + A mouse move action. - - `detail: optional "auto" or "low" or "high"` + - `type: "move"` - 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`. + Specifies the event type. For a move action, this property is always set to `move`. - - `"auto"` + - `x: number` - - `"low"` + The x-coordinate to move to. - - `"high"` + - `y: number` - - `file_data: optional string` + The y-coordinate to move to. - The base64-encoded data of the file to be sent to the model. + - `keys: optional array of string` - - `file_id: optional string` + The keys being held while moving the mouse. - The ID of the file to be sent to the model. + - `screenshot: object { type }` - - `file_url: optional string` + A screenshot action. - The URL of the file to be sent to the model. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `filename: optional string` + A scroll action. - The name of the file to be sent to the model. + - `scroll_x: number` - - `prompt_cache_breakpoint: optional object { mode }` + The horizontal scroll distance. - 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. + - `scroll_y: number` - - `mode: "explicit"` + The vertical scroll distance. - The breakpoint mode. Always `explicit`. + - `type: "scroll"` - - `type: "function_call_output"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The type of the function tool call output. Always `function_call_output`. + - `x: number` - - `id: optional string` + The x-coordinate where the scroll occurred. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `y: number` - - `agent: optional object { agent_name }` + The y-coordinate where the scroll occurred. - The agent that produced this item. + - `keys: optional array of string` - - `agent_name: string` + The keys being held while scrolling. - The canonical name of the agent that produced this item. + - `type: object { text, type }` - - `caller: optional object { type } or object { caller_id, type }` + An action to type in text. - The execution context that produced this tool call. + - `text: string` - - `direct: object { type }` + The text to type. - - `program: object { caller_id, type }` + - `type: "type"` - - `caller_id: string` + Specifies the event type. For a type action, this property is always set to `type`. - The call ID of the program item that produced this tool call. + - `wait: object { type }` - - `type: "program"` + A wait action. - The caller type. Always `program`. + - `actions: optional array of BetaComputerAction` - - `status: optional "in_progress" or "completed" or "incomplete"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `click: object { button, type, x, 2 more }` - - `"in_progress"` + A click action. - - `"completed"` + - `double_click: object { keys, type, x, y }` - - `"incomplete"` + A double click action. - - `agent_message: object { author, content, recipient, 3 more }` + - `drag: object { path, type, keys }` - A message routed between agents. + A drag action. - - `author: string` + - `keypress: object { keys, type }` - The sending agent identity. + A collection of keypresses the model would like to perform. - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `move: object { type, x, y, keys }` - Plaintext, image, or encrypted content sent between agents. + A mouse move action. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `screenshot: object { type }` - A text input to the model. + A screenshot action. - - `text: string` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The text input to the model. + A scroll action. - - `type: "input_text"` + - `type: object { text, type }` - The type of the input item. Always `input_text`. + An action to type in text. - - `prompt_cache_breakpoint: optional object { mode }` + - `wait: object { type }` - 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. + A wait action. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The agent that produced this item. - - `type: "input_image"` + - `agent_name: string` - The type of the input item. Always `input_image`. + The canonical name of the agent that produced this item. - - `detail: optional "low" or "high" or "auto" or "original"` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - `file_id: optional string` - The ID of the file to be sent to the model. + The identifier of an uploaded file that contains the screenshot. - `image_url: optional string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The URL of the screenshot image. - - `prompt_cache_breakpoint: optional object { mode }` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - 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. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `encrypted_content: object { encrypted_content, type }` + - `"completed"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"incomplete"` - - `encrypted_content: string` + - `"failed"` - Opaque encrypted content. + - `"in_progress"` - - `type: "encrypted_content"` + - `type: "computer_call_output"` - The type of the input item. Always `encrypted_content`. + The type of the computer tool call output. Always `computer_call_output`. - - `recipient: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The destination agent identity. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "agent_message"` + - `id: string` - The item type. Always `agent_message`. + The ID of the pending safety check. - - `id: optional string` + - `code: optional string` - The unique ID of this agent message item. + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -22578,39 +21094,36 @@ Get a model response The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. - - - `"spawn_agent"` + - `created_by: optional string` - - `"interrupt_agent"` + The identifier of the actor that created the item. - - `"list_agents"` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `"send_message"` + 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). - - `"followup_task"` + - `id: string` - - `"wait_agent"` + The unique identifier of the reasoning content. - - `arguments: string` + - `summary: array of object { text, type }` - The action arguments as a JSON string. + Reasoning summary content. - - `call_id: string` + - `text: string` - The unique ID linking this call to its output. + A summary of the reasoning output from the model so far. - - `type: "multi_agent_call"` + - `type: "summary_text"` - The item type. Always `multi_agent_call`. + The type of the object. Always `summary_text`. - - `id: optional string` + - `type: "reasoning"` - The unique ID of this multi-agent call. + The type of the object. Always `reasoning`. - `agent: optional object { agent_name }` @@ -22620,139 +21133,133 @@ Get a model response The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. + - `content: optional array of object { text, type }` - - `"spawn_agent"` + Reasoning text content. - - `"interrupt_agent"` + - `text: string` - - `"list_agents"` + The reasoning text from the model. - - `"send_message"` + - `type: "reasoning_text"` - - `"followup_task"` + The type of the reasoning text. Always `reasoning_text`. - - `"wait_agent"` + - `encrypted_content: optional string` - - `call_id: string` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The unique ID of the multi-agent call. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `output: array of object { text, type, annotations }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Text output returned by the multi-agent action. + - `"in_progress"` - - `text: string` + - `"completed"` - The text content. + - `"incomplete"` - - `type: "output_text"` + - `program: object { id, call_id, code, 3 more }` - The content type. Always `output_text`. + - `id: string` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + The unique ID of the program item. - Citations associated with the text content. + - `call_id: string` - - `union_member_0: array of object { file_id, filename, index, type }` + The stable call ID of the program item. - - `file_id: string` + - `code: string` - The ID of the file. + The JavaScript source executed by programmatic tool calling. - - `filename: string` + - `fingerprint: string` - The filename of the file cited. + Opaque program replay fingerprint that must be round-tripped. - - `index: number` + - `type: "program"` - The index of the file in the list of files. + The type of the item. Always `program`. - - `type: "file_citation"` + - `agent: optional object { agent_name }` - The citation type. Always `file_citation`. + The agent that produced this item. - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + - `agent_name: string` - - `end_index: number` + The canonical name of the agent that produced this item. - The index of the last character of the citation in the message. + - `program_output: object { id, call_id, result, 3 more }` - - `start_index: number` + - `id: string` - The index of the first character of the citation in the message. + The unique ID of the program output item. - - `title: string` + - `call_id: string` - The title of the cited resource. + The call ID of the program item. - - `type: "url_citation"` + - `result: string` - The citation type. Always `url_citation`. + The result produced by the program item. - - `url: string` + - `status: "completed" or "incomplete"` - The URL of the cited resource. + The terminal status of the program output item. - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + - `"completed"` - - `container_id: string` + - `"incomplete"` - The ID of the container. + - `type: "program_output"` - - `end_index: number` + The type of the item. Always `program_output`. - The index of the last character of the citation in the message. + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The ID of the container file. + - `agent_name: string` - - `filename: string` + The canonical name of the agent that produced this item. - The filename of the container file cited. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `start_index: number` + - `id: string` - The index of the first character of the citation in the message. + The unique ID of the tool search call item. - - `type: "container_file_citation"` + - `arguments: unknown` - The citation type. Always `container_file_citation`. + Arguments used for the tool search call. - - `type: "multi_agent_call_output"` + - `call_id: string` - The item type. Always `multi_agent_call_output`. + The unique ID of the tool search call generated by the model. - - `id: optional string` + - `execution: "server" or "client"` - The unique ID of this multi-agent call output. + Whether tool search was executed by the server or by the client. - - `agent: optional object { agent_name }` + - `"server"` - The agent that produced this item. + - `"client"` - - `agent_name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the tool search call item that was recorded. - - `tool_search_call: object { arguments, type, id, 4 more }` + - `"in_progress"` - - `arguments: unknown` + - `"completed"` - The arguments supplied to the tool search call. + - `"incomplete"` - `type: "tool_search_call"` - The item type. Always `tool_search_call`. - - - `id: optional string` - - The unique ID of this tool search call. + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -22762,11 +21269,21 @@ Get a model response The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` The unique ID of the tool search call generated by the model. - - `execution: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -22774,9 +21291,9 @@ Get a model response - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -22784,11 +21301,9 @@ Get a model response - `"incomplete"` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `tools: array of BetaTool` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -22883,7 +21398,7 @@ Get a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -22893,7 +21408,11 @@ Get a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -22940,7 +21459,7 @@ Get a model response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -22950,7 +21469,11 @@ Get a model response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -23822,11 +22345,7 @@ Get a model response - `type: "tool_search_output"` - The item type. Always `tool_search_output`. - - - `id: optional string` - - The unique ID of this tool search output. + The type of the item. Always `tool_search_output`. - `agent: optional object { agent_name }` @@ -23836,37 +22355,39 @@ Get a model response The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` - The unique ID of the tool search call generated by the model. + The identifier of the actor that created the item. - - `execution: optional "server" or "client"` + - `additional_tools: object { id, role, tools, 2 more }` - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the additional tools item. - - `"client"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + The role that provided the additional tools. - The status of the tool search output. + - `"unknown"` - - `"in_progress"` + - `"user"` - - `"completed"` + - `"assistant"` - - `"incomplete"` + - `"system"` - - `additional_tools: object { role, tools, type, 2 more }` + - `"critic"` - - `role: "developer"` + - `"discriminator"` - The role that provided the additional tools. Only `developer` is supported. + - `"developer"` + + - `"tool"` - `tools: array of BetaTool` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -23934,11 +22455,7 @@ Get a model response - `type: "additional_tools"` - The item type. Always `additional_tools`. - - - `id: optional string` - - The unique ID of this additional tools item. + The type of the item. Always `additional_tools`. - `agent: optional object { agent_name }` @@ -23948,85 +22465,22 @@ Get a model response The canonical name of the agent that produced this item. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: string` - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - Reasoning summary content. - - - `text: string` - - A summary of the reasoning output from the model so far. - - - `type: "summary_text"` - - The type of the object. Always `summary_text`. - - - `type: "reasoning"` - - The type of the object. Always `reasoning`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `content: optional array of object { text, type }` - - Reasoning text content. - - - `text: string` - - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - - `encrypted_content: optional string` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The unique ID of the compaction item. - `encrypted_content: string` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: "compaction"` The type of the item. Always `compaction`. - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -24035,6 +22489,10 @@ Get a model response The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -24238,9 +22696,13 @@ Get a model response - `"incomplete"` - - `shell_call: object { action, call_id, type, 5 more }` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - A tool representing a request to execute one or more shell commands. + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. - `action: object { commands, max_output_length, timeout_ms }` @@ -24248,27 +22710,53 @@ Get a model response - `commands: array of string` - Ordered shell commands for the execution environment to run. - - - `max_output_length: optional number` + - `max_output_length: number` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - - `timeout_ms: optional number` + - `timeout_ms: number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `type: "shell_call"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The type of the item. Always `shell_call`. + Represents the use of a local environment to perform shell actions. - - `id: optional string` + - `beta_response_local_environment: object { type }` - The unique ID of the shell tool call. Populated when this item is returned via API. + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. - `agent: optional object { agent_name }` @@ -24292,41 +22780,33 @@ Get a model response - `type: "program"` - The caller type. Always `program`. - - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `beta_local_environment: object { type, skills }` - - - `beta_container_reference: object { container_id, type }` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: optional string` - - `"in_progress"` + The ID of the entity that created this tool call. - - `"completed"` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `"incomplete"` + The output of a shell tool call that was emitted. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `id: string` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `max_output_length: number` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents - `outcome: object { type } or object { exit_code, type }` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `timeout: object { type }` @@ -24338,7 +22818,7 @@ Get a model response - `exit_code: number` - The exit code returned by the shell process. + Exit code from the shell process. - `type: "exit"` @@ -24346,19 +22826,29 @@ Get a model response - `stderr: string` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: string` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: "shell_call_output"` + - `created_by: optional string` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `id: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. - `agent: optional object { agent_name }` @@ -24382,25 +22872,17 @@ Get a model response - `type: "program"` - The caller type. Always `program`. - - - `max_output_length: optional number` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` @@ -24408,51 +22890,51 @@ Get a model response - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `create_file: object { diff, path, type }` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: string` - Unified diff content to apply when creating the file. + Diff to apply. - `path: string` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: "create_file"` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `delete_file: object { path, type }` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: string` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: "delete_file"` - The operation type. Always `delete_file`. + Delete the specified file. - `update_file: object { diff, path, type }` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: string` - Unified diff content to apply to the existing file. + Diff to apply. - `path: string` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: "update_file"` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `status: "in_progress" or "completed"` @@ -24466,10 +22948,6 @@ Get a model response The type of the item. Always `apply_patch_call`. - - `id: optional string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -24492,11 +22970,17 @@ Get a model response - `type: "program"` - The caller type. Always `program`. + - `created_by: optional string` - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + The ID of the entity that created this tool call. - The streamed output emitted by an apply patch tool call. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: string` @@ -24514,10 +22998,6 @@ Get a model response The type of the item. Always `apply_patch_call_output`. - - `id: optional string` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -24540,123 +23020,13 @@ Get a model response - `type: "program"` - The caller type. Always `program`. - - - `output: optional string` - - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - A list of tools available on an MCP server. - - - `id: string` - - The unique ID of the list. - - - `server_label: string` - - The label of the MCP server. - - - `tools: array of object { input_schema, name, annotations, description }` - - The tools available on the server. - - - `input_schema: unknown` - - The JSON schema describing the tool's input. - - - `name: string` - - The name of the tool. - - - `annotations: optional unknown` - - Additional annotations about the tool. - - - `description: optional string` - - The description of the tool. - - - `type: "mcp_list_tools"` - - The type of the item. Always `mcp_list_tools`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `error: optional string` - - Error message if the server could not list tools. - - - `mcp_approval_request: object { id, arguments, name, 3 more }` - - A request for human approval of a tool invocation. - - - `id: string` - - The unique ID of the approval request. - - - `arguments: string` - - A JSON string of arguments for the tool. - - - `name: string` - - The name of the tool to run. - - - `server_label: string` - - The label of the MCP server making the request. - - - `type: "mcp_approval_request"` - - The type of the item. Always `mcp_approval_request`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - - A response to an MCP approval request. - - - `approval_request_id: string` - - The ID of the approval request being answered. - - - `approve: boolean` - - Whether the request was approved. - - - `type: "mcp_approval_response"` - - The type of the item. Always `mcp_approval_response`. - - - `id: optional string` - - The unique ID of the approval response - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` + - `created_by: optional string` - The canonical name of the agent that produced this item. + The ID of the entity that created this tool call output. - - `reason: optional string` + - `output: optional string` - Optional reason for the decision. + Optional textual output returned by the apply patch tool. - `mcp_call: object { id, arguments, name, 7 more }` @@ -24717,106 +23087,105 @@ Get a model response - `"failed"` - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The output of a custom tool call from your code, being sent back to the model. + A list of tools available on an MCP server. - - `call_id: string` + - `id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the list. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `server_label: string` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The label of the MCP server. - - `string output: string` + - `tools: array of object { input_schema, name, annotations, description }` - A string of the output of the custom tool call. + The tools available on the server. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `input_schema: unknown` - Text, image, or file output of the custom tool call. + The JSON schema describing the tool's input. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `name: string` - A text input to the model. + The name of the tool. - - `text: string` + - `annotations: optional unknown` - The text input to the model. + Additional annotations about the tool. - - `type: "input_text"` + - `description: optional string` - The type of the input item. Always `input_text`. + The description of the tool. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "mcp_list_tools"` - 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. + The type of the item. Always `mcp_list_tools`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The agent that produced this item. - - `detail: "low" or "high" or "auto" or "original"` + - `agent_name: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The canonical name of the agent that produced this item. - - `type: "input_image"` + - `error: optional string` - The type of the input item. Always `input_image`. + Error message if the server could not list tools. - - `file_id: optional string` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - The ID of the file to be sent to the model. + A request for human approval of a tool invocation. - - `image_url: optional string` + - `id: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The unique ID of the approval request. - - `prompt_cache_breakpoint: optional object { mode }` + - `arguments: string` - 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. + A JSON string of arguments for the tool. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `name: string` - A file input to the model. + The name of the tool to run. - - `type: "input_file"` + - `server_label: string` - The type of the input item. Always `input_file`. + The label of the MCP server making the request. - - `detail: optional "auto" or "low" or "high"` + - `type: "mcp_approval_request"` - 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`. + The type of the item. Always `mcp_approval_request`. - - `file_data: optional string` + - `agent: optional object { agent_name }` - The content of the file to be sent to the model. + The agent that produced this item. - - `file_id: optional string` + - `agent_name: string` - The ID of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_url: optional string` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - The URL of the file to be sent to the model. + A response to an MCP approval request. - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique ID of the approval response - - `prompt_cache_breakpoint: optional object { mode }` + - `approval_request_id: string` - 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. + The ID of the approval request being answered. - - `type: "custom_tool_call_output"` + - `approve: boolean` - The type of the custom tool call output. Always `custom_tool_call_output`. + Whether the request was approved. - - `id: optional string` + - `type: "mcp_approval_response"` - The unique ID of the custom tool call output in the OpenAI platform. + The type of the item. Always `mcp_approval_response`. - `agent: optional object { agent_name }` @@ -24826,21 +23195,9 @@ Get a model response The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` + - `reason: optional string` - The caller type. Always `program`. + Optional reason for the decision. - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` @@ -24892,340 +23249,323 @@ Get a model response The namespace of the custom tool being called. - - `compaction_trigger: object { type, agent }` - - Compacts the current context. Must be the final input item. - - - `type: "compaction_trigger"` - - The type of the item. Always `compaction_trigger`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `item_reference: object { id, agent, type }` - - An internal identifier for an item to reference. - - - `id: string` - - The ID of the item to reference. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `type: optional "item_reference"` - - The type of item to reference. Always `item_reference`. - - - `"item_reference"` - - - `program: object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of this program item. - - - `call_id: string` - - The stable call ID of the program item. - - - `code: string` - - The JavaScript source executed by programmatic tool calling. - - - `fingerprint: string` - - Opaque program replay fingerprint that must be round-tripped. - - - `type: "program"` - - The item type. Always `program`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `program_output: object { id, call_id, result, 3 more }` + The output of a custom tool call from your code, being sent back to the model. - `id: string` - The unique ID of this program output item. - - - `call_id: string` - - The call ID of the program item. - - - `result: string` + The unique ID of the custom tool call output item. - The result produced by the program item. + - `status: "in_progress" or "completed" or "incomplete"` - - `status: "completed" or "incomplete"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The terminal status of the program output. + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` - - The item type. Always `program_output`. + - `created_by: optional string` - - `agent: optional object { agent_name }` + The identifier of the actor that created the item. - The agent that produced this item. + - `usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `agent_name: string` + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - The canonical name of the agent that produced this item. + - `input_tokens: number` - - `metadata: map[string]` + The number of input tokens. - 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. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A detailed breakdown of the input tokens. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `cache_write_tokens: number` - Model ID used to generate the response, like `gpt-4o` 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. + The number of input tokens that were written to the cache. - - `"gpt-5.6-sol"` + - `cached_tokens: number` - - `"gpt-5.6-terra"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `"gpt-5.6-luna"` + - `output_tokens: number` - - `"gpt-5.4"` + The number of output tokens. - - `"gpt-5.4-mini"` + - `output_tokens_details: object { reasoning_tokens }` - - `"gpt-5.4-nano"` + A detailed breakdown of the output tokens. - - `"gpt-5.4-mini-2026-03-17"` + - `reasoning_tokens: number` - - `"gpt-5.4-nano-2026-03-17"` + The number of reasoning tokens. - - `"gpt-5.3-chat-latest"` + - `total_tokens: number` - - `"gpt-5.2"` + The total number of tokens used. - - `"gpt-5.2-2025-12-11"` +### Example - - `"gpt-5.2-chat-latest"` +```cli +openai beta:responses compact \ + --api-key 'My API Key' \ + --model gpt-5.6-sol +``` - - `"gpt-5.2-pro"` +#### Response - - `"gpt-5.2-pro-2025-12-11"` +```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 + } +} +``` - - `"gpt-5.1"` +## Domain Types - - `"gpt-5.1-2025-11-13"` +### Beta Apply Patch Tool - - `"gpt-5.1-codex"` +- `beta_apply_patch_tool: object { type, allowed_callers }` - - `"gpt-5.1-mini"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"gpt-5.1-chat-latest"` + - `type: "apply_patch"` - - `"gpt-5"` + The type of the tool. Always `apply_patch`. - - `"gpt-5-mini"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5-nano"` + The tool invocation context(s). - - `"gpt-5-2025-08-07"` + - `"direct"` - - `"gpt-5-mini-2025-08-07"` + - `"programmatic"` - - `"gpt-5-nano-2025-08-07"` +### Beta Compacted Response - - `"gpt-5-chat-latest"` +- `beta_compacted_response: object { id, created_at, object, 2 more }` - - `"gpt-4.1"` + - `id: string` - - `"gpt-4.1-mini"` + The unique identifier for the compacted response. - - `"gpt-4.1-nano"` + - `created_at: number` - - `"gpt-4.1-2025-04-14"` + Unix timestamp (in seconds) when the compacted conversation was created. - - `"gpt-4.1-mini-2025-04-14"` + - `object: "response.compaction"` - - `"gpt-4.1-nano-2025-04-14"` + The object type. Always `response.compaction`. - - `"o4-mini"` + - `output: array of BetaResponseOutputItem` - - `"o4-mini-2025-04-16"` + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - - `"o3"` + - `beta_response_output_message: object { id, content, role, 4 more }` - - `"o3-2025-04-16"` + An output message from the model. - - `"o3-mini"` + - `id: string` - - `"o3-mini-2025-01-31"` + The unique ID of the output message. - - `"o1"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"o1-2024-12-17"` + The content of the output message. - - `"o1-preview"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `"o1-preview-2024-09-12"` + A text output from the model. - - `"o1-mini"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `"o1-mini-2024-09-12"` + The annotations of the text output. - - `"gpt-4o"` + - `file_citation: object { file_id, filename, index, type }` - - `"gpt-4o-2024-11-20"` + A citation to a file. - - `"gpt-4o-2024-08-06"` + - `file_id: string` - - `"gpt-4o-2024-05-13"` + The ID of the file. - - `"gpt-4o-audio-preview"` + - `filename: string` - - `"gpt-4o-audio-preview-2024-10-01"` + The filename of the file cited. - - `"gpt-4o-audio-preview-2024-12-17"` + - `index: number` - - `"gpt-4o-audio-preview-2025-06-03"` + The index of the file in the list of files. - - `"gpt-4o-mini-audio-preview"` + - `type: "file_citation"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The type of the file citation. Always `file_citation`. - - `"gpt-4o-search-preview"` + - `url_citation: object { end_index, start_index, title, 2 more }` - - `"gpt-4o-mini-search-preview"` + A citation for a web resource used to generate a model response. - - `"gpt-4o-search-preview-2025-03-11"` + - `end_index: number` - - `"gpt-4o-mini-search-preview-2025-03-11"` + The index of the last character of the URL citation in the message. - - `"chatgpt-4o-latest"` + - `start_index: number` - - `"codex-mini-latest"` + The index of the first character of the URL citation in the message. - - `"gpt-4o-mini"` + - `title: string` - - `"gpt-4o-mini-2024-07-18"` + The title of the web resource. - - `"gpt-4-turbo"` + - `type: "url_citation"` - - `"gpt-4-turbo-2024-04-09"` + The type of the URL citation. Always `url_citation`. - - `"gpt-4-0125-preview"` + - `url: string` - - `"gpt-4-turbo-preview"` + The URL of the web resource. - - `"gpt-4-1106-preview"` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `"gpt-4-vision-preview"` + A citation for a container file used to generate a model response. - - `"gpt-4"` + - `container_id: string` - - `"gpt-4-0314"` + The ID of the container file. - - `"gpt-4-0613"` + - `end_index: number` - - `"gpt-4-32k"` + The index of the last character of the container file citation in the message. - - `"gpt-4-32k-0314"` + - `file_id: string` - - `"gpt-4-32k-0613"` + The ID of the file. - - `"gpt-3.5-turbo"` + - `filename: string` - - `"gpt-3.5-turbo-16k"` + The filename of the container file cited. - - `"gpt-3.5-turbo-0301"` + - `start_index: number` - - `"gpt-3.5-turbo-0613"` + The index of the first character of the container file citation in the message. - - `"gpt-3.5-turbo-1106"` + - `type: "container_file_citation"` - - `"gpt-3.5-turbo-0125"` + The type of the container file citation. Always `container_file_citation`. - - `"gpt-3.5-turbo-16k-0613"` + - `file_path: object { file_id, index, type }` - - `"o1-pro"` + A path to a file. - - `"o1-pro-2025-03-19"` + - `file_id: string` - - `"o3-pro"` + The ID of the file. - - `"o3-pro-2025-06-10"` + - `index: number` - - `"o3-deep-research"` + The index of the file in the list of files. - - `"o3-deep-research-2025-06-26"` + - `type: "file_path"` - - `"o4-mini-deep-research"` + The type of the file path. Always `file_path`. - - `"o4-mini-deep-research-2025-06-26"` + - `text: string` - - `"computer-use-preview"` + The text output from the model. - - `"computer-use-preview-2025-03-11"` + - `type: "output_text"` - - `"gpt-5-codex"` + The type of the output text. Always `output_text`. - - `"gpt-5-pro"` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `"gpt-5-pro-2025-10-06"` + - `token: string` - - `"gpt-5.1-codex-max"` + - `bytes: array of number` - - `object: "response"` + - `logprob: number` - The object type of this resource - always set to `response`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `output: array of BetaResponseOutputItem` + - `token: string` - An array of content items generated by the model. + - `bytes: array of number` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `logprob: number` - - `beta_response_output_message: object { id, content, role, 4 more }` + - `beta_response_output_refusal: object { refusal, type }` - An output message from the model. + A refusal from the model. - - `id: string` + - `refusal: string` - The unique ID of the output message. + The refusal explanation from the model. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `type: "refusal"` - The content of the output message. + The type of the refusal. Always `refusal`. - `role: "assistant"` @@ -25236,6 +23576,12 @@ Get a model response The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + - `type: "message"` The type of the output message. Always `message`. @@ -25244,12 +23590,20 @@ Get a model response The agent that produced this item. - - `phase: optional "commentary"` + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"commentary"` + + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -25268,6 +23622,16 @@ Get a model response The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + - `type: "file_search_call"` The type of the file search tool call. Always `file_search_call`. @@ -25276,10 +23640,44 @@ Get a model response The agent that produced this item. + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `results: optional array of object { attributes, file_id, filename, 2 more }` The results of the file search tool call. + - `attributes: optional map[string or number or boolean]` + + 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. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` A tool call to run a function. See the @@ -25309,10 +23707,24 @@ Get a model response The agent that produced this item. + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + - `namespace: optional string` The namespace of the function to run. @@ -25322,6 +23734,12 @@ Get a model response The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - `id: string` @@ -25349,14 +23767,100 @@ Get a model response A text input to the model. + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or @@ -25642,105 +24146,102 @@ Get a model response 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). - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `search: object { type, queries, query, sources }` - The status of the web search tool call. + Action type "search" - Performs a web search query. - - `type: "web_search_call"` + - `type: "search"` - The type of the web search tool call. Always `web_search_call`. + The action type. - - `agent: optional object { agent_name }` + - `queries: optional array of string` - The agent that produced this item. + The search queries. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `query: optional string` - 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. + The search query. - - `id: string` + - `sources: optional array of object { type, url }` - The unique ID of the computer call. + The sources used in the search. - - `call_id: string` + - `type: "url"` - An identifier used when responding to the tool call with output. + The type of source. Always `url`. - - `pending_safety_checks: array of object { id, code, message }` + - `url: string` - The pending safety checks for the computer call. + The URL of the source. - - `status: "in_progress" or "completed" or "incomplete"` + - `open_page: object { type, url }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Action type "open_page" - Opens a specific URL from search results. - - `type: "computer_call"` + - `type: "open_page"` - The type of the computer call. Always `computer_call`. + The action type. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `url: optional string` - A click action. + The URL opened by the model. - - `actions: optional array of BetaComputerAction` + - `find_in_page: object { pattern, type, url }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `agent: optional object { agent_name }` + - `pattern: string` - The agent that produced this item. + The pattern or text to search for within the page. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `type: "find_in_page"` - - `id: string` + The action type. - The unique ID of the computer call tool output. + - `url: string` - - `call_id: string` + The URL of the page searched for the pattern. - The ID of the computer tool call that produced the output. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `output: object { type, file_id, image_url }` + The status of the web search tool call. - A computer screenshot image used with the computer use tool. + - `"in_progress"` - - `type: "computer_screenshot"` + - `"searching"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"completed"` - - `file_id: optional string` + - `"failed"` - The identifier of an uploaded file that contains the screenshot. + - `type: "web_search_call"` - - `image_url: optional string` + The type of the web search tool call. Always `web_search_call`. - The URL of the screenshot image. + - `agent: optional object { agent_name }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + The agent that produced this item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `agent_name: string` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `"failed"` + 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. - - `"in_progress"` + - `id: string` - - `type: "computer_call_output"` + The unique ID of the computer call. - The type of the computer tool call output. Always `computer_call_output`. + - `call_id: string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + An identifier used when responding to the tool call with output. - The safety checks reported by the API that have been acknowledged by the - developer. + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. - `id: string` @@ -25754,266 +24255,232 @@ Get a model response Details about the pending safety check. - - `agent: optional object { agent_name }` + - `status: "in_progress" or "completed" or "incomplete"` - The agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"completed"` - - `created_by: optional string` + - `"incomplete"` - The identifier of the actor that created the item. + - `type: "computer_call"` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + The type of the computer call. Always `computer_call`. - 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). + - `"computer_call"` - - `id: string` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - The unique identifier of the reasoning content. + A click action. - - `summary: array of object { text, type }` + - `click: object { button, type, x, 2 more }` - Reasoning summary content. + A click action. - - `type: "reasoning"` + - `button: "left" or "right" or "wheel" or 2 more` - The type of the object. Always `reasoning`. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `agent: optional object { agent_name }` + - `"left"` - The agent that produced this item. + - `"right"` - - `content: optional array of object { text, type }` + - `"wheel"` - Reasoning text content. + - `"back"` - - `encrypted_content: optional string` + - `"forward"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: "click"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Specifies the event type. For a click action, this property is always `click`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `x: number` - - `program: object { id, call_id, code, 3 more }` + The x-coordinate where the click occurred. - - `id: string` + - `y: number` - The unique ID of the program item. + The y-coordinate where the click occurred. - - `call_id: string` + - `keys: optional array of string` - The stable call ID of the program item. + The keys being held while clicking. - - `code: string` + - `double_click: object { keys, type, x, y }` - The JavaScript source executed by programmatic tool calling. + A double click action. - - `fingerprint: string` + - `keys: array of string` - Opaque program replay fingerprint that must be round-tripped. + The keys being held while double-clicking. - - `type: "program"` + - `type: "double_click"` - The type of the item. Always `program`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `agent: optional object { agent_name }` + - `x: number` - The agent that produced this item. + The x-coordinate where the double click occurred. - - `agent_name: string` + - `y: number` - The canonical name of the agent that produced this item. + The y-coordinate where the double click occurred. - - `program_output: object { id, call_id, result, 3 more }` + - `drag: object { path, type, keys }` - - `id: string` + A drag action. - The unique ID of the program output item. + - `path: array of object { x, y }` - - `call_id: string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The call ID of the program item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `result: string` + - `x: number` - The result produced by the program item. + The x-coordinate. - - `status: "completed" or "incomplete"` + - `y: number` - The terminal status of the program output item. + The y-coordinate. - - `"completed"` + - `type: "drag"` - - `"incomplete"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `type: "program_output"` + - `keys: optional array of string` - The type of the item. Always `program_output`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - - `id: string` - - The unique ID of the tool search call item. - - - `arguments: unknown` - - Arguments used for the tool search call. - - - `call_id: string` - - The unique ID of the tool search call generated by the model. - - - `execution: "server" or "client"` - - Whether tool search was executed by the server or by the client. - - - `"server"` - - - `"client"` - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the tool search call item that was recorded. + The keys being held while dragging the mouse. - - `"in_progress"` + - `keypress: object { keys, type }` - - `"completed"` + A collection of keypresses the model would like to perform. - - `"incomplete"` + - `keys: array of string` - - `type: "tool_search_call"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The type of the item. Always `tool_search_call`. + - `type: "keypress"` - - `agent: optional object { agent_name }` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The agent that produced this item. + - `move: object { type, x, y, keys }` - - `agent_name: string` + A mouse move action. - The canonical name of the agent that produced this item. + - `type: "move"` - - `created_by: optional string` + Specifies the event type. For a move action, this property is always set to `move`. - The identifier of the actor that created the item. + - `x: number` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + The x-coordinate to move to. - - `id: string` + - `y: number` - The unique ID of the tool search output item. + The y-coordinate to move to. - - `call_id: string` + - `keys: optional array of string` - The unique ID of the tool search call generated by the model. + The keys being held while moving the mouse. - - `execution: "server" or "client"` + - `screenshot: object { type }` - Whether tool search was executed by the server or by the client. + A screenshot action. - - `"server"` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `"client"` + A scroll action. - - `status: "in_progress" or "completed" or "incomplete"` + - `scroll_x: number` - The status of the tool search output item that was recorded. + The horizontal scroll distance. - - `"in_progress"` + - `scroll_y: number` - - `"completed"` + The vertical scroll distance. - - `"incomplete"` + - `type: "scroll"` - - `tools: array of BetaTool` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The loaded tool definitions returned by tool search. + - `x: number` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The x-coordinate where the scroll occurred. - 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). + - `y: number` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The y-coordinate where the scroll occurred. - 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). + - `keys: optional array of string` - - `beta_computer_tool: object { type }` + The keys being held while scrolling. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: object { text, type }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + An action to type in text. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `text: string` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The text to type. - 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"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + Specifies the event type. For a type action, this property is always set to `type`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `wait: object { type }` - - `code_interpreter: object { container, type, allowed_callers }` + A wait action. - A tool that runs Python code to help generate a response to a prompt. + - `actions: optional array of BetaComputerAction` - - `programmatic_tool_calling: object { type }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `image_generation: object { type, action, background, 9 more }` + - `click: object { button, type, x, 2 more }` - A tool that generates images using the GPT image models. + A click action. - - `local_shell: object { type }` + - `double_click: object { keys, type, x, y }` - A tool that allows the model to execute shell commands in a local environment. + A double click action. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `drag: object { path, type, keys }` - A tool that allows the model to execute shell commands. + A drag action. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `keypress: object { keys, type }` - 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) + A collection of keypresses the model would like to perform. - - `beta_namespace_tool: object { description, name, tools, type }` + - `move: object { type, x, y, keys }` - Groups function/custom tools under a shared namespace. + A mouse move action. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `screenshot: object { type }` - Hosted or BYOT tool search configuration for deferred tools. + A screenshot action. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - 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). + A scroll action. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `type: object { text, type }` - Allows the assistant to create, delete, or update files using unified diffs. + An action to type in text. - - `type: "tool_search_output"` + - `wait: object { type }` - The type of the item. Always `tool_search_output`. + A wait action. - `agent: optional object { agent_name }` @@ -26023,107 +24490,105 @@ Get a model response The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `additional_tools: object { id, role, tools, 2 more }` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - `id: string` - The unique ID of the additional tools item. - - - `role: "unknown" or "user" or "assistant" or 5 more` + The unique ID of the computer call tool output. - The role that provided the additional tools. + - `call_id: string` - - `"unknown"` + The ID of the computer tool call that produced the output. - - `"user"` + - `output: object { type, file_id, image_url }` - - `"assistant"` + A computer screenshot image used with the computer use tool. - - `"system"` + - `type: "computer_screenshot"` - - `"critic"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"discriminator"` + - `file_id: optional string` - - `"developer"` + The identifier of an uploaded file that contains the screenshot. - - `"tool"` + - `image_url: optional string` - - `tools: array of BetaTool` + The URL of the screenshot image. - The additional tool definitions made available at this item. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - 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). + - `"completed"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `"incomplete"` - 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). + - `"failed"` - - `beta_computer_tool: object { type }` + - `"in_progress"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "computer_call_output"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The type of the computer tool call output. Always `computer_call_output`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The safety checks reported by the API that have been acknowledged by the + developer. - 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). + - `id: string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The ID of the pending safety check. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `code: optional string` - - `code_interpreter: object { container, type, allowed_callers }` + The type of the pending safety check. - A tool that runs Python code to help generate a response to a prompt. + - `message: optional string` - - `programmatic_tool_calling: object { type }` + Details about the pending safety check. - - `image_generation: object { type, action, background, 9 more }` + - `agent: optional object { agent_name }` - A tool that generates images using the GPT image models. + The agent that produced this item. - - `local_shell: object { type }` + - `agent_name: string` - A tool that allows the model to execute shell commands in a local environment. + The canonical name of the agent that produced this item. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `created_by: optional string` - A tool that allows the model to execute shell commands. + The identifier of the actor that created the item. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - 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) + 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). - - `beta_namespace_tool: object { description, name, tools, type }` + - `id: string` - Groups function/custom tools under a shared namespace. + The unique identifier of the reasoning content. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `summary: array of object { text, type }` - Hosted or BYOT tool search configuration for deferred tools. + Reasoning summary content. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `text: string` - 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). + A summary of the reasoning output from the model so far. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `type: "summary_text"` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the object. Always `summary_text`. - - `type: "additional_tools"` + - `type: "reasoning"` - The type of the item. Always `additional_tools`. + The type of the object. Always `reasoning`. - `agent: optional object { agent_name }` @@ -26133,61 +24598,55 @@ Get a model response The canonical name of the agent that produced this item. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `id: string` + - `content: optional array of object { text, type }` - The unique ID of the compaction item. + Reasoning text content. - - `encrypted_content: string` + - `text: string` - The encrypted content that was produced by compaction. + The reasoning text from the model. - - `type: "compaction"` + - `type: "reasoning_text"` - The type of the item. Always `compaction`. + The type of the reasoning text. Always `reasoning_text`. - - `agent: optional object { agent_name }` + - `encrypted_content: optional string` - The agent that produced this item. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `agent_name: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `created_by: optional string` + - `"in_progress"` - The identifier of the actor that created the item. + - `"completed"` - - `image_generation_call: object { id, result, status, 2 more }` + - `"incomplete"` - An image generation request made by the model. + - `program: object { id, call_id, code, 3 more }` - `id: string` - The unique ID of the image generation call. - - - `result: string` - - The generated image encoded in base64. + The unique ID of the program item. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `call_id: string` - The status of the image generation call. + The stable call ID of the program item. - - `"in_progress"` + - `code: string` - - `"completed"` + The JavaScript source executed by programmatic tool calling. - - `"generating"` + - `fingerprint: string` - - `"failed"` + Opaque program replay fingerprint that must be round-tripped. - - `type: "image_generation_call"` + - `type: "program"` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `program`. - `agent: optional object { agent_name }` @@ -26197,82 +24656,65 @@ Get a model response The canonical name of the agent that produced this item. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - A tool call to run code. + - `program_output: object { id, call_id, result, 3 more }` - `id: string` - The unique ID of the code interpreter tool call. + The unique ID of the program output item. - - `code: string` + - `call_id: string` - The code to run, or null if not available. + The call ID of the program item. - - `container_id: string` + - `result: string` - The ID of the container used to run the code. + The result produced by the program item. - - `outputs: array of object { logs, type } or object { type, url }` + - `status: "completed" or "incomplete"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The terminal status of the program output item. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"completed"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"incomplete"` - - `type: "code_interpreter_call"` + - `type: "program_output"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the item. Always `program_output`. - `agent: optional object { agent_name }` The agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` - - A tool call to run a command on the local shell. - - - `id: string` - - The unique ID of the local shell call. - - - `action: object { command, env, type, 3 more }` - - Execute a shell command on the server. - - - `command: array of string` - - The command to run. + - `agent_name: string` - - `env: map[string]` + The canonical name of the agent that produced this item. - Environment variables to set for the command. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `type: "exec"` + - `id: string` - The type of the local shell action. Always `exec`. + The unique ID of the tool search call item. - - `timeout_ms: optional number` + - `arguments: unknown` - Optional timeout in milliseconds for the command. + Arguments used for the tool search call. - - `user: optional string` + - `call_id: string` - Optional user to run the command as. + The unique ID of the tool search call generated by the model. - - `working_directory: optional string` + - `execution: "server" or "client"` - Optional working directory to run the command in. + Whether tool search was executed by the server or by the client. - - `call_id: string` + - `"server"` - The unique ID of the local shell tool call generated by the model. + - `"client"` - `status: "in_progress" or "completed" or "incomplete"` - The status of the local shell call. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -26280,9 +24722,9 @@ Get a model response - `"incomplete"` - - `type: "local_shell_call"` + - `type: "tool_search_call"` - The type of the local shell call. Always `local_shell_call`. + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -26292,33 +24734,31 @@ Get a model response The canonical name of the agent that produced this item. - - `local_shell_call_output: object { id, output, type, 2 more }` - - The output of a local shell tool call. + - `created_by: optional string` - - `id: string` + The identifier of the actor that created the item. - The unique ID of the local shell tool call generated by the model. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `output: string` + - `id: string` - A JSON string of the output of the local shell tool call. + The unique ID of the tool search output item. - - `type: "local_shell_call_output"` + - `call_id: string` - The type of the local shell tool call output. Always `local_shell_call_output`. + The unique ID of the tool search call generated by the model. - - `agent: optional object { agent_name }` + - `execution: "server" or "client"` - The agent that produced this item. + Whether tool search was executed by the server or by the client. - - `agent_name: string` + - `"server"` - The canonical name of the agent that produced this item. + - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -26326,1990 +24766,1756 @@ Get a model response - `"incomplete"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `tools: array of BetaTool` - A tool call that executes one or more shell commands in a managed environment. + The loaded tool definitions returned by tool search. - - `id: string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The unique ID of the shell tool call. Populated when this item is returned via API. + 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). - - `action: object { commands, max_output_length, timeout_ms }` + - `name: string` - The shell commands and limits that describe how to run the tool call. + The name of the function to call. - - `commands: array of string` + - `parameters: map[unknown]` - - `max_output_length: number` + A JSON schema object describing the parameters of the function. - Optional maximum number of characters to return from each command. + - `strict: boolean` - - `timeout_ms: number` + Whether strict parameter validation is enforced for this function tool. - Optional timeout in milliseconds for the commands. + - `type: "function"` - - `call_id: string` + The type of the function tool. Always `function`. - The unique ID of the shell tool call generated by the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The tool invocation context(s). - Represents the use of a local environment to perform shell actions. + - `"direct"` - - `beta_response_local_environment: object { type }` + - `"programmatic"` - Represents the use of a local environment to perform shell actions. + - `defer_loading: optional boolean` - - `type: "local"` + Whether this function is deferred and loaded via tool search. - The environment type. Always `local`. + - `description: optional string` - - `beta_response_container_reference: object { container_id, type }` + A description of the function. Used by the model to determine whether or not to call the function. - Represents a container created with /v1/containers. + - `output_schema: optional map[unknown]` - - `container_id: string` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `type: "container_reference"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The environment type. Always `container_reference`. + 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). - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "file_search"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The type of the file search tool. Always `file_search`. - - `"in_progress"` + - `vector_store_ids: array of string` - - `"completed"` + The IDs of the vector stores to search. - - `"incomplete"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `type: "shell_call"` + A filter to apply. - The type of the item. Always `shell_call`. + - `Comparison Filter: object { key, type, value }` - - `agent: optional object { agent_name }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The agent that produced this item. + - `key: string` - - `agent_name: string` + The key to compare against the value. - The canonical name of the agent that produced this item. + - `type: "eq" or "ne" or "gt" or 5 more` - - `caller: optional object { type } or object { caller_id, type }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The execution context that produced this tool call. + - `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 - - `direct: object { type }` + - `"eq"` - - `program: object { caller_id, type }` + - `"ne"` - - `caller_id: string` + - `"gt"` - The call ID of the program item that produced this tool call. + - `"gte"` - - `type: "program"` + - `"lt"` - - `created_by: optional string` + - `"lte"` - The ID of the entity that created this tool call. + - `"in"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `"nin"` - The output of a shell tool call that was emitted. + - `value: string or number or boolean or array of string or number` - - `id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The unique ID of the shell call output. Populated when this item is returned via API. + - `union_member_0: string` - - `call_id: string` + - `union_member_1: number` - The unique ID of the shell tool call generated by the model. + - `union_member_2: boolean` - - `max_output_length: number` + - `union_member_3: array of string or number` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `union_member_0: string` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `union_member_1: number` - An array of shell call output contents + - `Compound Filter: object { filters, type }` - - `outcome: object { type } or object { exit_code, type }` + Combine multiple filters using `and` or `or`. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `filters: array of object { key, type, value } or unknown` - - `timeout: object { type }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Indicates that the shell call exceeded its configured time limit. + - `Comparison Filter: object { key, type, value }` - - `exit: object { exit_code, type }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Indicates that the shell commands finished and returned an exit code. + - `key: string` - - `exit_code: number` + The key to compare against the value. - Exit code from the shell process. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "exit"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The outcome type. Always `exit`. + - `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 - - `stderr: string` + - `"eq"` - The standard error output that was captured. + - `"ne"` - - `stdout: string` + - `"gt"` - The standard output that was captured. + - `"gte"` - - `created_by: optional string` + - `"lt"` - The identifier of the actor that created the item. + - `"lte"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"in"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `"nin"` - - `"in_progress"` + - `value: string or number or boolean or array of string or number` - - `"completed"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"incomplete"` + - `union_member_0: string` - - `type: "shell_call_output"` + - `union_member_1: number` - The type of the shell call output. Always `shell_call_output`. + - `union_member_2: boolean` - - `agent: optional object { agent_name }` + - `union_member_3: array of string or number` - The agent that produced this item. + - `union_member_0: string` - - `agent_name: string` + - `union_member_1: number` - The canonical name of the agent that produced this item. + - `union_member_1: unknown` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "and" or "or"` - The execution context that produced this tool call. + Type of operation: `and` or `or`. - - `direct: object { type }` + - `"and"` - - `program: object { caller_id, type }` + - `"or"` - - `caller_id: string` + - `max_num_results: optional number` - The call ID of the program item that produced this tool call. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: "program"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `created_by: optional string` + Ranking options for search. - The identifier of the actor that created the item. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - A tool call that applies file diffs by creating, deleting, or updating files. + - `embedding_weight: number` - - `id: string` + The weight of the embedding in the reciprocal ranking fusion. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `text_weight: number` - - `call_id: string` + The weight of the text in the reciprocal ranking fusion. - The unique ID of the apply patch tool call generated by the model. + - `ranker: optional "auto" or "default-2024-11-15"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The ranker to use for the file search. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `"auto"` - - `create_file: object { diff, path, type }` + - `"default-2024-11-15"` - Instruction describing how to create a file via the apply_patch tool. + - `score_threshold: optional number` - - `diff: string` + 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. - Diff to apply. + - `beta_computer_tool: object { type }` - - `path: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Path of the file to create. + - `type: "computer"` - - `type: "create_file"` + The type of the computer tool. Always `computer`. - Create a new file with the provided diff. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `delete_file: object { path, type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Instruction describing how to delete a file via the apply_patch tool. + - `display_height: number` - - `path: string` + The height of the computer display. - Path of the file to delete. + - `display_width: number` - - `type: "delete_file"` + The width of the computer display. - Delete the specified file. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `update_file: object { diff, path, type }` + The type of computer environment to control. - Instruction describing how to update a file via the apply_patch tool. + - `"windows"` - - `diff: string` + - `"mac"` - Diff to apply. + - `"linux"` - - `path: string` + - `"ubuntu"` - Path of the file to update. + - `"browser"` - - `type: "update_file"` + - `type: "computer_use_preview"` - Update an existing file with the provided diff. + The type of the computer use tool. Always `computer_use_preview`. - - `status: "in_progress" or "completed"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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). - - `"in_progress"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"completed"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: "apply_patch_call"` + - `"web_search"` - The type of the item. Always `apply_patch_call`. + - `"web_search_2025_08_26"` - - `agent: optional object { agent_name }` + - `filters: optional object { allowed_domains }` - The agent that produced this item. + Filters for the search. - - `agent_name: string` + - `allowed_domains: optional array of string` - The canonical name of the agent that produced this item. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `caller: optional object { type } or object { caller_id, type }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The execution context that produced this tool call. + - `search_context_size: optional "low" or "medium" or "high"` - - `direct: object { type }` + 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. - - `program: object { caller_id, type }` + - `"low"` - - `caller_id: string` + - `"medium"` - The call ID of the program item that produced this tool call. + - `"high"` - - `type: "program"` + - `user_location: optional object { city, country, region, 2 more }` - - `created_by: optional string` + The approximate location of the user. - The ID of the entity that created this tool call. + - `city: optional string` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + Free text input for the city of the user, e.g. `San Francisco`. - The output emitted by an apply patch tool call. + - `country: optional string` - - `id: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `region: optional string` - - `call_id: string` + Free text input for the region of the user, e.g. `California`. - The unique ID of the apply patch tool call generated by the model. + - `timezone: optional string` - - `status: "completed" or "failed"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `type: optional "approximate"` - - `"completed"` + The type of location approximation. Always `approximate`. - - `"failed"` + - `"approximate"` - - `type: "apply_patch_call_output"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The type of the item. Always `apply_patch_call_output`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `agent: optional object { agent_name }` + - `server_label: string` - The agent that produced this item. + A label for this MCP server, used to identify it in tool calls. - - `agent_name: string` + - `type: "mcp"` - The canonical name of the agent that produced this item. + The type of the MCP tool. Always `mcp`. - - `caller: optional object { type } or object { caller_id, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The execution context that produced this tool call. + The tool invocation context(s). - - `direct: object { type }` + - `"direct"` - - `program: object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The call ID of the program item that produced this tool call. + List of allowed tool names or a filter object. - - `type: "program"` + - `MCP allowed tools: array of string` - - `created_by: optional string` + A string array of allowed tool names - The ID of the entity that created this tool call output. + - `MCP tool filter: object { read_only, tool_names }` - - `output: optional string` + A filter object to specify which tools are allowed. - Optional textual output returned by the apply patch tool. + - `read_only: optional boolean` - - `mcp_call: object { id, arguments, name, 7 more }` + 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. - An invocation of a tool on an MCP server. + - `tool_names: optional array of string` - - `id: string` + List of allowed tool names. - The unique ID of the tool call. + - `authorization: optional string` - - `arguments: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A JSON string of the arguments passed to the tool. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `name: string` + 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). - The name of the tool that was run. + Currently supported `connector_id` values are: - - `server_label: string` + - 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` - The label of the MCP server running the tool. + - `"connector_dropbox"` - - `type: "mcp_call"` + - `"connector_gmail"` - The type of the item. Always `mcp_call`. + - `"connector_googlecalendar"` - - `agent: optional object { agent_name }` + - `"connector_googledrive"` - The agent that produced this item. + - `"connector_microsoftteams"` - - `agent_name: string` + - `"connector_outlookcalendar"` - The canonical name of the agent that produced this item. + - `"connector_outlookemail"` - - `approval_request_id: optional string` + - `"connector_sharepoint"` - 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. + - `defer_loading: optional boolean` - - `error: optional string` + Whether this MCP tool is deferred and discovered via tool search. - The error from the tool call, if any. + - `headers: optional map[string]` - - `output: optional string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The output from the tool call. + - `require_approval: optional object { always, never } or "always" or "never"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + Specify which of the MCP server's tools require approval. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `MCP tool approval filter: object { always, never }` - - `"in_progress"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"completed"` + - `always: optional object { read_only, tool_names }` - - `"incomplete"` + A filter object to specify which tools are allowed. - - `"calling"` + - `read_only: optional boolean` - - `"failed"` + 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. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `tool_names: optional array of string` - A list of tools available on an MCP server. + List of allowed tool names. - - `id: string` + - `never: optional object { read_only, tool_names }` - The unique ID of the list. + A filter object to specify which tools are allowed. - - `server_label: string` + - `read_only: optional boolean` - The label of the MCP server. + 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. - - `tools: array of object { input_schema, name, annotations, description }` + - `tool_names: optional array of string` - The tools available on the server. + List of allowed tool names. - - `input_schema: unknown` + - `MCP tool approval setting: "always" or "never"` - The JSON schema describing the tool's input. + 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. - - `name: string` + - `"always"` - The name of the tool. + - `"never"` - - `annotations: optional unknown` + - `server_description: optional string` - Additional annotations about the tool. + Optional description of the MCP server, used to provide more context. - - `description: optional string` + - `server_url: optional string` - The description of the tool. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "mcp_list_tools"` + - `tunnel_id: optional string` - The type of the item. Always `mcp_list_tools`. + 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. - - `agent: optional object { agent_name }` + - `code_interpreter: object { container, type, allowed_callers }` - The agent that produced this item. + A tool that runs Python code to help generate a response to a prompt. - - `agent_name: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The canonical name of the agent that produced this item. + 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. - - `error: optional string` + - `union_member_0: string` - Error message if the server could not list tools. + The container ID. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - A request for human approval of a tool invocation. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `id: string` + - `type: "auto"` - The unique ID of the approval request. + Always `auto`. - - `arguments: string` + - `file_ids: optional array of string` - A JSON string of arguments for the tool. + An optional list of uploaded files to make available to your code. - - `name: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The name of the tool to run. + The memory limit for the code interpreter container. - - `server_label: string` + - `"1g"` - The label of the MCP server making the request. + - `"4g"` - - `type: "mcp_approval_request"` + - `"16g"` - The type of the item. Always `mcp_approval_request`. + - `"64g"` - - `agent: optional object { agent_name }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The agent that produced this item. + Network access policy for the container. - - `agent_name: string` + - `beta_container_network_policy_disabled: object { type }` - The canonical name of the agent that produced this item. + - `type: "disabled"` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + Disable outbound network access. Always `disabled`. - A response to an MCP approval request. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `id: string` + - `allowed_domains: array of string` - The unique ID of the approval response + A list of allowed domains when type is `allowlist`. - - `approval_request_id: string` + - `type: "allowlist"` - The ID of the approval request being answered. + Allow outbound network access only to specified domains. Always `allowlist`. - - `approve: boolean` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - Whether the request was approved. + Optional domain-scoped secrets for allowlisted domains. - - `type: "mcp_approval_response"` + - `domain: string` - The type of the item. Always `mcp_approval_response`. + The domain associated with the secret. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The name of the secret to inject for the domain. - - `agent_name: string` + - `value: string` - The canonical name of the agent that produced this item. + The secret value to inject for the domain. - - `reason: optional string` + - `type: "code_interpreter"` - Optional reason for the decision. + The type of the code interpreter tool. Always `code_interpreter`. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A call to a custom tool created by the model. + The tool invocation context(s). - - `call_id: string` + - `"direct"` - An identifier used to map this custom tool call to a tool call output. + - `"programmatic"` - - `input: string` + - `programmatic_tool_calling: object { type }` - The input for the custom tool call generated by the model. + - `image_generation: object { type, action, background, 9 more }` - - `name: string` + A tool that generates images using the GPT image models. - The name of the custom tool being called. + - `type: "image_generation"` - - `type: "custom_tool_call"` + The type of the image generation tool. Always `image_generation`. - The type of the custom tool call. Always `custom_tool_call`. + - `action: optional "generate" or "edit" or "auto"` - - `id: optional string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The unique ID of the custom tool call in the OpenAI platform. + - `"generate"` - - `agent: optional object { agent_name }` + - `"edit"` - The agent that produced this item. + - `"auto"` - - `caller: optional object { type } or object { caller_id, type }` + - `background: optional "transparent" or "opaque" or "auto"` - The execution context that produced this tool call. + 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. - - `namespace: optional string` + `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. - The namespace of the custom tool being called. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `"transparent"` - The output of a custom tool call from your code, being sent back to the model. + - `"opaque"` - - `id: string` + - `"auto"` - The unique ID of the custom tool call output item. + - `input_fidelity: optional "high" or "low"` - - `status: "in_progress" or "completed" or "incomplete"` + 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`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"high"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `input_image_mask: optional object { file_id, image_url }` - - `"incomplete"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `created_by: optional string` + - `file_id: optional string` - The identifier of the actor that created the item. + File ID for the mask image. - - `parallel_tool_calls: boolean` + - `image_url: optional string` - Whether to allow the model to run tool calls in parallel. + Base64-encoded mask image. - - `temperature: number` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + The image generation model to use. Default: `gpt-image-1`. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"gpt-image-1"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `"gpt-image-1-mini"` - - `beta_tool_choice_options: "none" or "auto" or "required"` + - `"gpt-image-2"` - Controls which (if any) tool is called by the model. + - `"gpt-image-2-2026-04-21"` - `none` means the model will not call any tool and instead generates a message. + - `"gpt-image-1.5"` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `"chatgpt-image-latest"` - `required` means the model must call one or more tools. + - `moderation: optional "auto" or "low"` - - `"none"` + Moderation level for the generated image. Default: `auto`. - `"auto"` - - `"required"` + - `"low"` - - `beta_tool_choice_allowed: object { mode, tools, type }` + - `output_compression: optional number` - Constrains the tools available to the model to a pre-defined set. + Compression level for the output image. Default: 100. - - `mode: "auto" or "required"` + - `output_format: optional "png" or "webp" or "jpeg"` - Constrains the tools available to the model to a pre-defined set. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `"png"` - `required` requires the model to call one or more of the allowed tools. + - `"webp"` - - `"auto"` + - `"jpeg"` - - `"required"` + - `partial_images: optional number` - - `tools: array of map[unknown]` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - A list of tool definitions that the model should be allowed to call. + - `quality: optional "low" or "medium" or "high" or "auto"` - For the Responses API, the list of tool definitions might look like: + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"low"` - - `type: "allowed_tools"` + - `"medium"` - Allowed tool configuration type. Always `allowed_tools`. + - `"high"` - - `beta_tool_choice_types: object { type }` + - `"auto"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + 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`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"1024x1024"` - Allowed values are: + - `"1024x1536"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"1536x1024"` - - `"file_search"` + - `"auto"` - - `"web_search_preview"` + - `local_shell: object { type }` - - `"computer"` + A tool that allows the model to execute shell commands in a local environment. - - `"computer_use_preview"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"computer_use"` + A tool that allows the model to execute shell commands. - - `"web_search_preview_2025_03_11"` + - `type: "shell"` - - `"image_generation"` + The type of the shell tool. Always `shell`. - - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `beta_tool_choice_function: object { name, type }` + The tool invocation context(s). - Use this option to force the model to call a specific function. + - `"direct"` - - `name: string` + - `"programmatic"` - The name of the function to call. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `type: "function"` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - For function calling, the type is always `function`. + - `type: "container_auto"` - - `beta_tool_choice_mcp: object { server_label, type, name }` + Automatically creates a container for this request - Use this option to force the model to call a specific tool on a remote MCP server. + - `file_ids: optional array of string` - - `server_label: string` + An optional list of uploaded files to make available to your code. - The label of the MCP server to use. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "mcp"` + The memory limit for the container. - For MCP tools, the type is always `mcp`. + - `"1g"` - - `name: optional string` + - `"4g"` - The name of the tool to call on the server. + - `"16g"` - - `beta_tool_choice_custom: object { name, type }` + - `"64g"` - Use this option to force the model to call a specific custom tool. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `name: string` + Network access policy for the container. - The name of the custom tool to call. + - `beta_container_network_policy_disabled: object { type }` - - `type: "custom"` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - For custom tool calling, the type is always `custom`. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + An optional list of skills referenced by id or inline data. - - `beta_tool_choice_apply_patch: object { type }` + - `beta_skill_reference: object { skill_id, type, version }` - Forces the model to call the apply_patch tool when executing a tool call. + - `skill_id: string` - - `type: "apply_patch"` + The ID of the referenced skill. - The tool to call. Always `apply_patch`. + - `type: "skill_reference"` - - `beta_tool_choice_shell: object { type }` + References a skill created with the /v1/skills endpoint. - Forces the model to call the shell tool when a tool call is required. + - `version: optional string` - - `type: "shell"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The tool to call. Always `shell`. + - `beta_inline_skill: object { description, name, source, type }` - - `tools: array of BetaTool` + - `description: string` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The description of the skill. - We support the following categories of tools: + - `name: string` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The name of the skill. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `source: object { data, media_type, type }` - 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). + Inline skill payload - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `data: string` - 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). + Base64-encoded skill zip bundle. - - `beta_computer_tool: object { type }` + - `media_type: "application/zip"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The media type of the inline skill payload. Must be `application/zip`. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `type: "base64"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the inline skill source. Must be `base64`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `type: "inline"` - 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). + Defines an inline skill for this request. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `beta_local_environment: object { type, skills }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "local"` - - `code_interpreter: object { container, type, allowed_callers }` + Use a local computer environment. - A tool that runs Python code to help generate a response to a prompt. + - `skills: optional array of BetaLocalSkill` - - `programmatic_tool_calling: object { type }` + An optional list of skills. - - `image_generation: object { type, action, background, 9 more }` + - `description: string` - A tool that generates images using the GPT image models. + The description of the skill. - - `local_shell: object { type }` + - `name: string` - A tool that allows the model to execute shell commands in a local environment. + The name of the skill. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `path: string` - A tool that allows the model to execute shell commands. + The path to the directory containing the skill. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `beta_container_reference: object { container_id, type }` - 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) + - `container_id: string` - - `beta_namespace_tool: object { description, name, tools, type }` + The ID of the referenced container. - Groups function/custom tools under a shared namespace. + - `type: "container_reference"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + References a container created with the /v1/containers endpoint - Hosted or BYOT tool search configuration for deferred tools. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + 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) - 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). + - `name: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The name of the custom tool, used to identify it in tool calls. - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "custom"` - - `top_p: number` + The type of the custom tool. Always `custom`. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `allowed_callers: optional array of "direct" or "programmatic"` - We generally recommend altering this or `temperature` but not both. + The tool invocation context(s). - - `background: optional boolean` + - `"direct"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"programmatic"` - - `completed_at: optional number` + - `defer_loading: optional boolean` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + Whether this tool should be deferred and discovered via tool search. - - `conversation: optional object { id }` + - `description: optional string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + Optional description of the custom tool, used to provide more context. - - `id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The unique ID of the conversation that this response was associated with. + The input format for the custom tool. Default is unconstrained text. - - `max_output_tokens: optional number` + - `text: object { type }` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + Unconstrained free-form text. - - `max_tool_calls: optional number` + - `grammar: object { definition, syntax, type }` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + A grammar defined by the user. - - `moderation: optional object { input, output }` + - `definition: string` - Moderation results for the response input and output, if moderated completions were requested. + The grammar definition. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `syntax: "lark" or "regex"` - Moderation for the response input. + The syntax of the grammar definition. One of `lark` or `regex`. - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `"lark"` - A moderation result produced for the response input or output. + - `"regex"` - - `categories: map[boolean]` + - `type: "grammar"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Grammar format. Always `grammar`. - - `category_applied_input_types: map[array of "text" or "image"]` + - `beta_namespace_tool: object { description, name, tools, type }` - Which modalities of input are reflected by the score for each category. + Groups function/custom tools under a shared namespace. - - `"text"` + - `description: string` - - `"image"` + A description of the namespace shown to the model. - - `category_scores: map[number]` + - `name: string` - A dictionary of moderation categories to scores. + The namespace name used in tool calls (for example, `crm`). - - `flagged: boolean` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - A boolean indicating whether the content was flagged by any category. + The function/custom tools available inside this namespace. - - `model: string` + - `function: object { name, type, allowed_callers, 5 more }` - The moderation model that produced this result. + - `name: string` - - `type: "moderation_result"` + - `type: "function"` - The object type, which was always `moderation_result` for successful moderation results. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `error: object { code, message, type }` + The tool invocation context(s). - An error produced while attempting moderation for the response input or output. + - `"direct"` - - `code: string` + - `"programmatic"` - The error code. + - `defer_loading: optional boolean` - - `message: string` + Whether this function should be deferred and discovered via tool search. - The error message. + - `description: optional string` - - `type: "error"` + - `output_schema: optional map[unknown]` - The object type, which was always `error` for moderation failures. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `parameters: optional unknown` - Moderation for the response output. + - `strict: optional boolean` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + 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. - A moderation result produced for the response input or output. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `categories: map[boolean]` + 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) - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `name: string` - - `category_applied_input_types: map[array of "text" or "image"]` + The name of the custom tool, used to identify it in tool calls. - Which modalities of input are reflected by the score for each category. + - `type: "custom"` - - `"text"` + The type of the custom tool. Always `custom`. - - `"image"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `category_scores: map[number]` + The tool invocation context(s). - A dictionary of moderation categories to scores. + - `defer_loading: optional boolean` - - `flagged: boolean` + Whether this tool should be deferred and discovered via tool search. - A boolean indicating whether the content was flagged by any category. + - `description: optional string` - - `model: string` + Optional description of the custom tool, used to provide more context. - The moderation model that produced this result. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "moderation_result"` + The input format for the custom tool. Default is unconstrained text. - The object type, which was always `moderation_result` for successful moderation results. + - `type: "namespace"` - - `error: object { code, message, type }` + The type of the tool. Always `namespace`. - An error produced while attempting moderation for the response input or output. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `code: string` + Hosted or BYOT tool search configuration for deferred tools. - The error code. + - `type: "tool_search"` - - `message: string` + The type of the tool. Always `tool_search`. - The error message. + - `description: optional string` - - `type: "error"` + Description shown to the model for a client-executed tool search tool. - The object type, which was always `error` for moderation failures. + - `execution: optional "server" or "client"` - - `previous_response_id: optional string` + Whether tool search is executed by the server or by the client. - 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`. + - `"server"` - - `prompt: optional object { id, variables, version }` + - `"client"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `parameters: optional unknown` - - `id: string` + Parameter schema for a client-executed tool search tool. - The unique identifier of the prompt template to use. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + 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). - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `union_member_0: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"web_search_preview"` - A text input to the model. + - `"web_search_preview_2025_03_11"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `search_content_types: optional array of "text" or "image"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"text"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"image"` - A file input to the model. + - `search_context_size: optional "low" or "medium" or "high"` - - `version: optional string` + 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. - Optional version of the prompt template. + - `"low"` - - `prompt_cache_key: optional string` + - `"medium"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"high"` - - `prompt_cache_options: optional object { mode, ttl }` + - `user_location: optional object { type, city, country, 2 more }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The user's location. - - `mode: "implicit" or "explicit"` + - `type: "approximate"` - Whether implicit prompt-cache breakpoints were enabled. + The type of location approximation. Always `approximate`. - - `"implicit"` + - `city: optional string` - - `"explicit"` + Free text input for the city of the user, e.g. `San Francisco`. - - `ttl: "30m"` + - `country: optional string` - The minimum lifetime applied to each cache breakpoint. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"30m"` + - `region: optional string` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Free text input for the region of the user, e.g. `California`. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `timezone: optional string` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `beta_apply_patch_tool: object { type, allowed_callers }` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Allows the assistant to create, delete, or update files using unified diffs. - - `"in_memory"` + - `type: "apply_patch"` - - `"24h"` + The type of the tool. Always `apply_patch`. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - **gpt-5 and o-series models only** + The tool invocation context(s). - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"direct"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `"programmatic"` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `type: "tool_search_output"` - - `"auto"` + The type of the item. Always `tool_search_output`. - - `"current_turn"` + - `agent: optional object { agent_name }` - - `"all_turns"` + The agent that produced this item. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `agent_name: string` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The canonical name of the agent that produced this item. - - `"none"` + - `created_by: optional string` - - `"minimal"` + The identifier of the actor that created the item. - - `"low"` + - `additional_tools: object { id, role, tools, 2 more }` - - `"medium"` + - `id: string` - - `"high"` + The unique ID of the additional tools item. - - `"xhigh"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `"max"` + The role that provided the additional tools. - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `"unknown"` - **Deprecated:** use `summary` instead. + - `"user"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"assistant"` - - `"auto"` + - `"system"` - - `"concise"` + - `"critic"` - - `"detailed"` + - `"discriminator"` - - `mode: optional string or "standard" or "pro"` + - `"developer"` - Controls the reasoning execution mode for the request. + - `"tool"` - When returned on a response, this is the effective execution mode. + - `tools: array of BetaTool` - - `"standard"` + The additional tool definitions made available at this item. - - `"pro"` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `summary: optional "auto" or "concise" or "detailed"` + 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). - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + 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). - - `"auto"` + - `beta_computer_tool: object { type }` - - `"concise"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"detailed"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `safety_identifier: optional string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + 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). - Specifies the processing type used for serving the request. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `code_interpreter: object { container, type, allowed_callers }` - - `"auto"` + A tool that runs Python code to help generate a response to a prompt. - - `"default"` + - `programmatic_tool_calling: object { type }` - - `"flex"` + - `image_generation: object { type, action, background, 9 more }` - - `"scale"` + A tool that generates images using the GPT image models. - - `"priority"` + - `local_shell: object { type }` - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + A tool that allows the model to execute shell commands in a local environment. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"completed"` + A tool that allows the model to execute shell commands. - - `"failed"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"in_progress"` + 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) - - `"cancelled"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `"queued"` + Groups function/custom tools under a shared namespace. - - `"incomplete"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `text: optional object { format, verbosity }` + Hosted or BYOT tool search configuration for deferred tools. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + 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). - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - An object specifying the format that the model must output. + Allows the assistant to create, delete, or update files using unified diffs. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "additional_tools"` - The default format is `{ "type": "text" }` with no additional options. + The type of the item. Always `additional_tools`. - **Not recommended for gpt-4o and newer models:** + - `agent: optional object { agent_name }` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The agent that produced this item. - - `text: object { type }` + - `agent_name: string` - Default response format. Used to generate text responses. + The canonical name of the agent that produced this item. - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `name: string` + - `id: string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The unique ID of the compaction item. - - `schema: map[unknown]` + - `encrypted_content: string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The encrypted content that was produced by compaction. - - `type: "json_schema"` + - `type: "compaction"` - The type of response format being defined. Always `json_schema`. + The type of the item. Always `compaction`. - - `description: optional string` + - `agent: optional object { agent_name }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The agent that produced this item. - - `strict: optional boolean` + - `agent_name: string` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - - `json_object: object { type }` + - `created_by: optional string` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The identifier of the actor that created the item. - - `verbosity: optional "low" or "medium" or "high"` + - `image_generation_call: object { id, result, status, 2 more }` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + An image generation request made by the model. - - `"low"` + - `id: string` - - `"medium"` + The unique ID of the image generation call. - - `"high"` + - `result: string` - - `top_logprobs: optional number` + The generated image encoded in base64. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `truncation: optional "auto" or "disabled"` + The status of the image generation call. - The truncation strategy to use for the model response. + - `"in_progress"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"completed"` - - `"auto"` + - `"generating"` - - `"disabled"` + - `"failed"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `type: "image_generation_call"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The type of the image generation call. Always `image_generation_call`. - - `input_tokens: number` + - `agent: optional object { agent_name }` - The number of input tokens. + The agent that produced this item. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `agent_name: string` - A detailed breakdown of the input tokens. + The canonical name of the agent that produced this item. - - `cache_write_tokens: number` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - The number of input tokens that were written to the cache. + A tool call to run code. - - `cached_tokens: number` + - `id: string` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The unique ID of the code interpreter tool call. - - `output_tokens: number` + - `code: string` - The number of output tokens. + The code to run, or null if not available. - - `output_tokens_details: object { reasoning_tokens }` + - `container_id: string` - A detailed breakdown of the output tokens. + The ID of the container used to run the code. - - `reasoning_tokens: number` + - `outputs: array of object { logs, type } or object { type, url }` - The number of reasoning tokens. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `total_tokens: number` + - `logs: object { logs, type }` - The total number of tokens used. + The logs output from the code interpreter. - - `user: optional string` + - `logs: string` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The logs output from the code interpreter. -### Example + - `type: "logs"` -```cli -openai beta:responses retrieve \ - --api-key 'My API Key' \ - --response-id resp_677efb5139a88190b512bc3fef8e535d -``` + The type of the output. Always `logs`. -#### Response + - `image: object { type, url }` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "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" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "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 - }, - "user": "user-1234" -} -``` + The image output from the code interpreter. -## Delete a model response + - `type: "image"` -`$ openai beta:responses delete` + The type of the output. Always `image`. -**delete** `/responses/{response_id}?beta=true` + - `url: string` -Delete a model response + The URL of the image output from the code interpreter. -### Parameters + - `status: "in_progress" or "completed" or "incomplete" or 2 more` -- `--response-id: string` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The ID of the response to delete. + - `"in_progress"` -- `--beta: optional array of "responses_multi_agent=v1"` + - `"completed"` - Optional beta features to enable for this request. + - `"incomplete"` -### Example + - `"interpreting"` -```cli -openai beta:responses delete \ - --api-key 'My API Key' \ - --response-id resp_677efb5139a88190b512bc3fef8e535d -``` + - `"failed"` -## Cancel a response + - `type: "code_interpreter_call"` -`$ openai beta:responses cancel` + The type of the code interpreter tool call. Always `code_interpreter_call`. -**post** `/responses/{response_id}/cancel?beta=true` + - `agent: optional object { agent_name }` -Cancel a response + The agent that produced this item. -### Parameters + - `agent_name: string` -- `--response-id: string` + The canonical name of the agent that produced this item. - The ID of the response to cancel. + - `local_shell_call: object { id, action, call_id, 3 more }` -- `--beta: optional array of "responses_multi_agent=v1"` + A tool call to run a command on the local shell. - Optional beta features to enable for this request. + - `id: string` -### Returns + The unique ID of the local shell call. -- `beta_response: object { id, created_at, error, 31 more }` + - `action: object { command, env, type, 3 more }` - - `id: string` + Execute a shell command on the server. - Unique identifier for this Response. + - `command: array of string` - - `created_at: number` + The command to run. - Unix timestamp (in seconds) of when this Response was created. + - `env: map[string]` - - `error: object { code, message }` + Environment variables to set for the command. - An error object returned when the model fails to generate a Response. + - `type: "exec"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + The type of the local shell action. Always `exec`. - The error code for the response. + - `timeout_ms: optional number` - - `"server_error"` + Optional timeout in milliseconds for the command. - - `"rate_limit_exceeded"` + - `user: optional string` - - `"invalid_prompt"` + Optional user to run the command as. - - `"bio_policy"` + - `working_directory: optional string` - - `"vector_store_timeout"` + Optional working directory to run the command in. - - `"invalid_image"` + - `call_id: string` - - `"invalid_image_format"` + The unique ID of the local shell tool call generated by the model. - - `"invalid_base64_image"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"invalid_image_url"` + The status of the local shell call. - - `"image_too_large"` + - `"in_progress"` - - `"image_too_small"` + - `"completed"` - - `"image_parse_error"` + - `"incomplete"` - - `"image_content_policy_violation"` + - `type: "local_shell_call"` - - `"invalid_image_mode"` + The type of the local shell call. Always `local_shell_call`. - - `"image_file_too_large"` + - `agent: optional object { agent_name }` - - `"unsupported_image_media_type"` + The agent that produced this item. - - `"empty_image_file"` + - `agent_name: string` - - `"failed_to_download_image"` + The canonical name of the agent that produced this item. - - `"image_file_not_found"` + - `local_shell_call_output: object { id, output, type, 2 more }` - - `message: string` + The output of a local shell tool call. - A human-readable description of the error. + - `id: string` - - `incomplete_details: object { reason }` + The unique ID of the local shell tool call generated by the model. - Details about why the response is incomplete. + - `output: string` - - `reason: optional "max_output_tokens" or "content_filter"` + A JSON string of the output of the local shell tool call. - The reason why the response is incomplete. + - `type: "local_shell_call_output"` - - `"max_output_tokens"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"content_filter"` + - `agent: optional object { agent_name }` - - `instructions: string or array of BetaResponseInputItem` + The agent that produced this item. - A system (or developer) message inserted into the model's context. + - `agent_name: string` - When using 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. + The canonical name of the agent that produced this item. - - `union_member_0: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - A text input to the model, equivalent to a text input with the - `developer` role. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `Input item list: array of BetaResponseInputItem` + - `"in_progress"` - A list of one or many input items to the model, containing - different content types. + - `"completed"` - - `beta_easy_input_message: object { content, role, phase, type }` + - `"incomplete"` - 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. + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - `content: string or BetaResponseInputMessageContentList` + A tool call that executes one or more shell commands in a managed environment. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `id: string` - - `Text input: string` + The unique ID of the shell tool call. Populated when this item is returned via API. - A text input to the model. + - `action: object { commands, max_output_length, timeout_ms }` - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + The shell commands and limits that describe how to run the tool call. - A list of one or many input items to the model, containing different content - types. + - `commands: array of string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `max_output_length: number` - A text input to the model. + Optional maximum number of characters to return from each command. - - `text: string` + - `timeout_ms: number` - The text input to the model. + Optional timeout in milliseconds for the commands. - - `type: "input_text"` + - `call_id: string` - The type of the input item. Always `input_text`. + The unique ID of the shell tool call generated by the model. - - `prompt_cache_breakpoint: optional object { mode }` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - 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. + Represents the use of a local environment to perform shell actions. - - `mode: "explicit"` + - `beta_response_local_environment: object { type }` - The breakpoint mode. Always `explicit`. + Represents the use of a local environment to perform shell actions. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `type: "local"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The environment type. Always `local`. - - `detail: "low" or "high" or "auto" or "original"` + - `beta_response_container_reference: object { container_id, type }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Represents a container created with /v1/containers. - - `"low"` + - `container_id: string` - - `"high"` + - `type: "container_reference"` - - `"auto"` + The environment type. Always `container_reference`. - - `"original"` + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "input_image"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The type of the input item. Always `input_image`. + - `"in_progress"` - - `file_id: optional string` + - `"completed"` - The ID of the file to be sent to the model. + - `"incomplete"` - - `image_url: optional string` + - `type: "shell_call"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The type of the item. Always `shell_call`. - - `prompt_cache_breakpoint: optional object { mode }` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - - `mode: "explicit"` + - `agent_name: string` - The breakpoint mode. Always `explicit`. + The canonical name of the agent that produced this item. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - A file input to the model. + The execution context that produced this tool call. - - `type: "input_file"` + - `direct: object { type }` - The type of the input item. Always `input_file`. + - `program: object { caller_id, type }` - - `detail: optional "auto" or "low" or "high"` + - `caller_id: string` - 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`. + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `"low"` + - `created_by: optional string` - - `"high"` + The ID of the entity that created this tool call. - - `file_data: optional string` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - The content of the file to be sent to the model. + The output of a shell tool call that was emitted. - - `file_id: optional string` + - `id: string` - The ID of the file to be sent to the model. + The unique ID of the shell call output. Populated when this item is returned via API. - - `file_url: optional string` + - `call_id: string` - The URL of the file to be sent to the model. + The unique ID of the shell tool call generated by the model. - - `filename: optional string` + - `max_output_length: number` - The name of the file to be sent to the model. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `prompt_cache_breakpoint: optional object { mode }` + - `output: array of object { outcome, stderr, stdout, created_by }` - 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. + An array of shell call output contents - - `mode: "explicit"` + - `outcome: object { type } or object { exit_code, type }` - The breakpoint mode. Always `explicit`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `role: "user" or "assistant" or "system" or "developer"` + - `timeout: object { type }` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Indicates that the shell call exceeded its configured time limit. - - `"user"` + - `exit: object { exit_code, type }` - - `"assistant"` + Indicates that the shell commands finished and returned an exit code. - - `"system"` + - `exit_code: number` - - `"developer"` + Exit code from the shell process. - - `phase: optional "commentary"` + - `type: "exit"` - 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. + The outcome type. Always `exit`. - - `"commentary"` + - `stderr: string` - - `type: optional "message"` + The standard error output that was captured. - The type of the message input. Always `message`. + - `stdout: string` - - `"message"` + The standard output that was captured. - - `message: object { content, role, agent, 2 more }` + - `created_by: optional string` - 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. + The identifier of the actor that created the item. - - `content: array of BetaResponseInputContent` + - `status: "in_progress" or "completed" or "incomplete"` - A list of one or many input items to the model, containing different content - types. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"in_progress"` - A text input to the model. + - `"completed"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"incomplete"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: "shell_call_output"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The type of the shell call output. Always `shell_call_output`. - A file input to the model. + - `agent: optional object { agent_name }` - - `role: "user" or "system" or "developer"` + The agent that produced this item. - The role of the message input. One of `user`, `system`, or `developer`. + - `agent_name: string` - - `"user"` + The canonical name of the agent that produced this item. - - `"system"` + - `caller: optional object { type } or object { caller_id, type }` - - `"developer"` + The execution context that produced this tool call. - - `agent: optional object { agent_name }` + - `direct: object { type }` - The agent that produced this item. + - `program: object { caller_id, type }` - - `agent_name: string` + - `caller_id: string` - The canonical name of the agent that produced this item. + The call ID of the program item that produced this tool call. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "program"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `type: optional "message"` + - `id: string` - The type of the message input. Always set to `message`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"message"` + - `call_id: string` - - `beta_response_output_message: object { id, content, role, 4 more }` + The unique ID of the apply patch tool call generated by the model. - An output message from the model. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `id: string` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The unique ID of the output message. + - `create_file: object { diff, path, type }` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + Instruction describing how to create a file via the apply_patch tool. - The content of the output message. + - `diff: string` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + Diff to apply. - A text output from the model. + - `path: string` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + Path of the file to create. - The annotations of the text output. + - `type: "create_file"` - - `file_citation: object { file_id, filename, index, type }` + Create a new file with the provided diff. - A citation to a file. + - `delete_file: object { path, type }` - - `file_id: string` + Instruction describing how to delete a file via the apply_patch tool. - The ID of the file. + - `path: string` - - `filename: string` + Path of the file to delete. - The filename of the file cited. + - `type: "delete_file"` - - `index: number` + Delete the specified file. - The index of the file in the list of files. + - `update_file: object { diff, path, type }` - - `type: "file_citation"` + Instruction describing how to update a file via the apply_patch tool. - The type of the file citation. Always `file_citation`. + - `diff: string` - - `url_citation: object { end_index, start_index, title, 2 more }` + Diff to apply. - A citation for a web resource used to generate a model response. + - `path: string` - - `end_index: number` + Path of the file to update. - The index of the last character of the URL citation in the message. + - `type: "update_file"` - - `start_index: number` + Update an existing file with the provided diff. - The index of the first character of the URL citation in the message. + - `status: "in_progress" or "completed"` - - `title: string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The title of the web resource. + - `"in_progress"` - - `type: "url_citation"` + - `"completed"` - The type of the URL citation. Always `url_citation`. + - `type: "apply_patch_call"` - - `url: string` + The type of the item. Always `apply_patch_call`. - The URL of the web resource. + - `agent: optional object { agent_name }` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + The agent that produced this item. - A citation for a container file used to generate a model response. + - `agent_name: string` - - `container_id: string` + The canonical name of the agent that produced this item. - The ID of the container file. + - `caller: optional object { type } or object { caller_id, type }` - - `end_index: number` + The execution context that produced this tool call. - The index of the last character of the container file citation in the message. + - `direct: object { type }` - - `file_id: string` + - `program: object { caller_id, type }` - The ID of the file. + - `caller_id: string` - - `filename: string` + The call ID of the program item that produced this tool call. - The filename of the container file cited. + - `type: "program"` - - `start_index: number` + - `created_by: optional string` - The index of the first character of the container file citation in the message. + The ID of the entity that created this tool call. - - `type: "container_file_citation"` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - The type of the container file citation. Always `container_file_citation`. + The output emitted by an apply patch tool call. - - `file_path: object { file_id, index, type }` + - `id: string` - A path to a file. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `file_id: string` + - `call_id: string` - The ID of the file. + The unique ID of the apply patch tool call generated by the model. - - `index: number` + - `status: "completed" or "failed"` - The index of the file in the list of files. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: "file_path"` + - `"completed"` - The type of the file path. Always `file_path`. + - `"failed"` - - `text: string` + - `type: "apply_patch_call_output"` - The text output from the model. + The type of the item. Always `apply_patch_call_output`. - - `type: "output_text"` + - `agent: optional object { agent_name }` - The type of the output text. Always `output_text`. + The agent that produced this item. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `agent_name: string` - - `token: string` + The canonical name of the agent that produced this item. - - `bytes: array of number` + - `caller: optional object { type } or object { caller_id, type }` - - `logprob: number` + The execution context that produced this tool call. - - `top_logprobs: array of object { token, bytes, logprob }` + - `direct: object { type }` - - `token: string` + - `program: object { caller_id, type }` - - `bytes: array of number` + - `caller_id: string` - - `logprob: number` + The call ID of the program item that produced this tool call. - - `beta_response_output_refusal: object { refusal, type }` + - `type: "program"` - A refusal from the model. + - `created_by: optional string` - - `refusal: string` + The ID of the entity that created this tool call output. - The refusal explanation from the model. + - `output: optional string` - - `type: "refusal"` + Optional textual output returned by the apply patch tool. - The type of the refusal. Always `refusal`. + - `mcp_call: object { id, arguments, name, 7 more }` - - `role: "assistant"` + An invocation of a tool on an MCP server. - The role of the output message. Always `assistant`. + - `id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The unique ID of the tool call. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `arguments: string` - - `"in_progress"` + A JSON string of the arguments passed to the tool. - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the tool that was run. - - `type: "message"` + - `server_label: string` - The type of the output message. Always `message`. + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` @@ -28319,45 +26525,68 @@ Cancel a response The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `approval_request_id: optional string` - 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. + 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. - - `"commentary"` + - `error: optional string` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + The error from the tool call, if any. - 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. + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. - `id: string` - The unique ID of the file search tool call. + The unique ID of the list. - - `queries: array of string` + - `server_label: string` - The queries used to search for files. + The label of the MCP server. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `tools: array of object { input_schema, name, annotations, description }` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The tools available on the server. - - `"in_progress"` + - `input_schema: unknown` - - `"searching"` + The JSON schema describing the tool's input. - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the tool. - - `"failed"` + - `annotations: optional unknown` - - `type: "file_search_call"` + Additional annotations about the tool. - The type of the file search tool call. Always `file_search_call`. + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. - `agent: optional object { agent_name }` @@ -28367,68 +26596,131 @@ Cancel a response The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `error: optional string` - The results of the file search tool call. + Error message if the server could not list tools. - - `attributes: optional map[string or number or boolean]` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - 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. + A request for human approval of a tool invocation. - - `union_member_0: string` + - `id: string` - - `union_member_1: number` + The unique ID of the approval request. - - `union_member_2: boolean` + - `arguments: string` - - `file_id: optional string` + A JSON string of arguments for the tool. - The unique ID of the file. + - `name: string` - - `filename: optional string` + The name of the tool to run. - The name of the file. + - `server_label: string` - - `score: optional number` + The label of the MCP server making the request. - The relevance score of the file - a value between 0 and 1. + - `type: "mcp_approval_request"` - - `text: optional string` + The type of the item. Always `mcp_approval_request`. - The text that was retrieved from the file. + - `agent: optional object { agent_name }` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + The agent that produced this item. - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + + A response to an MCP approval request. - `id: string` - The unique ID of the computer call. + The unique ID of the approval response + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. - `call_id: string` - An identifier used when responding to the tool call with output. + An identifier used to map this custom tool call to a tool call output. - - `pending_safety_checks: array of object { id, code, message }` + - `input: string` - The pending safety checks for the computer call. + The input for the custom tool call generated by the model. - - `id: string` + - `name: string` - The ID of the pending safety check. + The name of the custom tool being called. - - `code: optional string` + - `type: "custom_tool_call"` - The type of the pending safety check. + The type of the custom tool call. Always `custom_tool_call`. - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: string` + + The unique ID of the custom tool call output item. - `status: "in_progress" or "completed" or "incomplete"` @@ -28441,13 +26733,50 @@ Cancel a response - `"incomplete"` - - `type: "computer_call"` + - `created_by: optional string` - The type of the computer call. Always `computer_call`. + The identifier of the actor that created the item. - - `"computer_call"` + - `usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + Token accounting for the compaction pass, including cached, reasoning, and total tokens. + + - `input_tokens: number` + + The number of input tokens. + + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: number` + + The number of input tokens that were written to the cache. + + - `cached_tokens: number` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: number` + + The number of output tokens. + + - `output_tokens_details: object { reasoning_tokens }` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: number` + + The number of reasoning tokens. + + - `total_tokens: number` + + The total number of tokens used. + +### Beta Computer Action + +- `beta_computer_action: object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -28616,7 +26945,9 @@ Cancel a response A wait action. - - `actions: optional array of BetaComputerAction` +### Beta Computer Action List + +- `beta_computer_action_list: array of BetaComputerAction` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. @@ -28625,766 +26956,593 @@ Cancel a response A click action. - - `double_click: object { keys, type, x, y }` + - `button: "left" or "right" or "wheel" or 2 more` - A double click action. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `drag: object { path, type, keys }` + - `"left"` - A drag action. + - `"right"` - - `keypress: object { keys, type }` + - `"wheel"` - A collection of keypresses the model would like to perform. + - `"back"` - - `move: object { type, x, y, keys }` + - `"forward"` - A mouse move action. + - `type: "click"` - - `screenshot: object { type }` + Specifies the event type. For a click action, this property is always `click`. - A screenshot action. + - `x: number` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + The x-coordinate where the click occurred. - A scroll action. + - `y: number` - - `type: object { text, type }` + The y-coordinate where the click occurred. - An action to type in text. + - `keys: optional array of string` - - `wait: object { type }` + The keys being held while clicking. - A wait action. + - `double_click: object { keys, type, x, y }` - - `agent: optional object { agent_name }` + A double click action. - The agent that produced this item. + - `keys: array of string` - - `agent_name: string` + The keys being held while double-clicking. - The canonical name of the agent that produced this item. + - `type: "double_click"` - - `computer_call_output: object { call_id, output, type, 4 more }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The output of a computer tool call. + - `x: number` - - `call_id: string` + The x-coordinate where the double click occurred. - The ID of the computer tool call that produced the output. + - `y: number` - - `output: object { type, file_id, image_url }` + The y-coordinate where the double click occurred. - A computer screenshot image used with the computer use tool. + - `drag: object { path, type, keys }` - - `type: "computer_screenshot"` + A drag action. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `path: array of object { x, y }` - - `file_id: optional string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The identifier of an uploaded file that contains the screenshot. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `image_url: optional string` + - `x: number` - The URL of the screenshot image. + The x-coordinate. - - `type: "computer_call_output"` + - `y: number` - The type of the computer tool call output. Always `computer_call_output`. + The y-coordinate. - - `id: optional string` + - `type: "drag"` - The ID of the computer tool call output. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `keys: optional array of string` - The safety checks reported by the API that have been acknowledged by the developer. + The keys being held while dragging the mouse. - - `id: string` + - `keypress: object { keys, type }` - The ID of the pending safety check. + A collection of keypresses the model would like to perform. - - `code: optional string` + - `keys: array of string` - The type of the pending safety check. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `message: optional string` + - `type: "keypress"` - Details about the pending safety check. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `agent: optional object { agent_name }` + - `move: object { type, x, y, keys }` - The agent that produced this item. + A mouse move action. - - `agent_name: string` + - `type: "move"` - The canonical name of the agent that produced this item. + Specifies the event type. For a move action, this property is always set to `move`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `x: number` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The x-coordinate to move to. - - `"in_progress"` + - `y: number` - - `"completed"` + The y-coordinate to move to. - - `"incomplete"` + - `keys: optional array of string` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + The keys being held while moving the mouse. - 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. + - `screenshot: object { type }` - - `id: string` + A screenshot action. - The unique ID of the web search tool call. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + A scroll 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). + - `scroll_x: number` - - `search: object { type, queries, query, sources }` + The horizontal scroll distance. - Action type "search" - Performs a web search query. + - `scroll_y: number` - - `type: "search"` + The vertical scroll distance. - The action type. + - `type: "scroll"` - - `queries: optional array of string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The search queries. + - `x: number` - - `query: optional string` + The x-coordinate where the scroll occurred. - The search query. + - `y: number` - - `sources: optional array of object { type, url }` + The y-coordinate where the scroll occurred. - The sources used in the search. + - `keys: optional array of string` - - `type: "url"` + The keys being held while scrolling. - The type of source. Always `url`. + - `type: object { text, type }` - - `url: string` + An action to type in text. - The URL of the source. + - `text: string` - - `open_page: object { type, url }` + The text to type. - Action type "open_page" - Opens a specific URL from search results. + - `type: "type"` - - `type: "open_page"` + Specifies the event type. For a type action, this property is always set to `type`. - The action type. + - `wait: object { type }` - - `url: optional string` + A wait action. - The URL opened by the model. +### Beta Computer Tool - - `find_in_page: object { pattern, type, url }` +- `beta_computer_tool: object { type }` - Action type "find_in_page": Searches for a pattern within a loaded page. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `pattern: string` + - `type: "computer"` - The pattern or text to search for within the page. + The type of the computer tool. Always `computer`. - - `type: "find_in_page"` +### Beta Computer Use Preview Tool - The action type. +- `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `url: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The URL of the page searched for the pattern. + - `display_height: number` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The height of the computer display. - The status of the web search tool call. + - `display_width: number` - - `"in_progress"` + The width of the computer display. - - `"searching"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"completed"` + The type of computer environment to control. - - `"failed"` + - `"windows"` - - `type: "web_search_call"` + - `"mac"` - The type of the web search tool call. Always `web_search_call`. + - `"linux"` - - `agent: optional object { agent_name }` + - `"ubuntu"` - The agent that produced this item. + - `"browser"` - - `agent_name: string` + - `type: "computer_use_preview"` - The canonical name of the agent that produced this item. + The type of the computer use tool. Always `computer_use_preview`. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` +### Beta Container Auto - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. +- `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `arguments: string` + - `type: "container_auto"` - A JSON string of the arguments to pass to the function. + Automatically creates a container for this request - - `call_id: string` + - `file_ids: optional array of string` - The unique ID of the function tool call generated by the model. + An optional list of uploaded files to make available to your code. - - `name: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The name of the function to run. + The memory limit for the container. - - `type: "function_call"` + - `"1g"` - The type of the function tool call. Always `function_call`. + - `"4g"` - - `id: optional string` + - `"16g"` - The unique ID of the function tool call. + - `"64g"` - - `agent: optional object { agent_name }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The agent that produced this item. + Network access policy for the container. - - `agent_name: string` + - `beta_container_network_policy_disabled: object { type }` - The canonical name of the agent that produced this item. + - `type: "disabled"` - - `caller: optional object { type } or object { caller_id, type }` + Disable outbound network access. Always `disabled`. - The execution context that produced this tool call. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `direct: object { type }` + - `allowed_domains: array of string` - - `program: object { caller_id, type }` + A list of allowed domains when type is `allowlist`. - - `caller_id: string` + - `type: "allowlist"` - The call ID of the program item that produced this tool call. + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "program"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `namespace: optional string` + Optional domain-scoped secrets for allowlisted domains. - The namespace of the function to run. + - `domain: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The domain associated with the secret. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `name: string` - - `"in_progress"` + The name of the secret to inject for the domain. - - `"completed"` + - `value: string` - - `"incomplete"` + The secret value to inject for the domain. - - `function_call_output: object { call_id, output, type, 4 more }` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The output of a function tool call. + An optional list of skills referenced by id or inline data. - - `call_id: string` + - `beta_skill_reference: object { skill_id, type, version }` - The unique ID of the function tool call generated by the model. + - `skill_id: string` - - `output: string or BetaResponseFunctionCallOutputItemList` + The ID of the referenced skill. - Text, image, or file output of the function tool call. + - `type: "skill_reference"` - - `union_member_0: string` + References a skill created with the /v1/skills endpoint. - A JSON string of the output of the function tool call. + - `version: optional string` - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - An array of content outputs (text, image, file) for the function tool call. + - `beta_inline_skill: object { description, name, source, type }` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `description: string` - A text input to the model. + The description of the skill. - - `text: string` + - `name: string` - The text input to the model. + The name of the skill. - - `type: "input_text"` + - `source: object { data, media_type, type }` - The type of the input item. Always `input_text`. + Inline skill payload - - `prompt_cache_breakpoint: optional object { mode }` + - `data: string` - 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. + Base64-encoded skill zip bundle. - - `mode: "explicit"` + - `media_type: "application/zip"` - The breakpoint mode. Always `explicit`. + The media type of the inline skill payload. Must be `application/zip`. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `type: "base64"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The type of the inline skill source. Must be `base64`. - - `type: "input_image"` + - `type: "inline"` - The type of the input item. Always `input_image`. + Defines an inline skill for this request. - - `detail: optional "low" or "high" or "auto" or "original"` +### Beta Container Network Policy Allowlist - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +- `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `"low"` + - `allowed_domains: array of string` - - `"high"` + A list of allowed domains when type is `allowlist`. - - `"auto"` + - `type: "allowlist"` - - `"original"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `file_id: optional string` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The ID of the file to be sent to the model. + Optional domain-scoped secrets for allowlisted domains. - - `image_url: optional string` + - `domain: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The domain associated with the secret. - - `prompt_cache_breakpoint: optional object { mode }` + - `name: string` - 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. + The name of the secret to inject for the domain. - - `mode: "explicit"` + - `value: string` - The breakpoint mode. Always `explicit`. + The secret value to inject for the domain. - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` +### Beta Container Network Policy Disabled - A file input to the model. +- `beta_container_network_policy_disabled: object { type }` - - `type: "input_file"` + - `type: "disabled"` - The type of the input item. Always `input_file`. + Disable outbound network access. Always `disabled`. - - `detail: optional "auto" or "low" or "high"` +### Beta Container Network Policy Domain Secret - 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`. +- `beta_container_network_policy_domain_secret: object { domain, name, value }` - - `"auto"` + - `domain: string` - - `"low"` + The domain associated with the secret. - - `"high"` + - `name: string` - - `file_data: optional string` + The name of the secret to inject for the domain. - The base64-encoded data of the file to be sent to the model. + - `value: string` - - `file_id: optional string` + The secret value to inject for the domain. - The ID of the file to be sent to the model. +### Beta Container Reference - - `file_url: optional string` +- `beta_container_reference: object { container_id, type }` - The URL of the file to be sent to the model. + - `container_id: string` - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` + The ID of the referenced container. - The breakpoint mode. Always `explicit`. + - `type: "container_reference"` - - `type: "function_call_output"` + References a container created with the /v1/containers endpoint - The type of the function tool call output. Always `function_call_output`. +### Beta Custom Tool - - `id: optional string` +- `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The unique ID of the function tool call output. Populated when this item is returned via API. + 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) - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The name of the custom tool, used to identify it in tool calls. - - `agent_name: string` + - `type: "custom"` - The canonical name of the agent that produced this item. + The type of the custom tool. Always `custom`. - - `caller: optional object { type } or object { caller_id, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The execution context that produced this tool call. + The tool invocation context(s). - - `direct: object { type }` + - `"direct"` - - `program: object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `defer_loading: optional boolean` - The call ID of the program item that produced this tool call. + Whether this tool should be deferred and discovered via tool search. - - `type: "program"` + - `description: optional string` - The caller type. Always `program`. + Optional description of the custom tool, used to provide more context. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `format: optional object { type } or object { definition, syntax, type }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The input format for the custom tool. Default is unconstrained text. - - `"in_progress"` + - `text: object { type }` - - `"completed"` + Unconstrained free-form text. - - `"incomplete"` + - `grammar: object { definition, syntax, type }` - - `agent_message: object { author, content, recipient, 3 more }` + A grammar defined by the user. - A message routed between agents. + - `definition: string` - - `author: string` + The grammar definition. - The sending agent identity. + - `syntax: "lark" or "regex"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The syntax of the grammar definition. One of `lark` or `regex`. - Plaintext, image, or encrypted content sent between agents. + - `"lark"` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `"regex"` - A text input to the model. + - `type: "grammar"` - - `text: string` + Grammar format. Always `grammar`. - The text input to the model. +### Beta Easy Input Message - - `type: "input_text"` +- `beta_easy_input_message: object { content, role, phase, type }` - The type of the input item. Always `input_text`. + 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. - - `prompt_cache_breakpoint: optional object { mode }` + - `content: string or BetaResponseInputMessageContentList` - 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. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `Text input: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A text input to the model. - - `type: "input_image"` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - The type of the input item. Always `input_image`. + A list of one or many input items to the model, containing different content + types. - - `detail: optional "low" or "high" or "auto" or "original"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A text input to the model. - - `file_id: optional string` + - `text: string` - The ID of the file to be sent to the model. + The text input to the model. - - `image_url: optional string` + - `type: "input_text"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The type of the input item. Always `input_text`. - `prompt_cache_breakpoint: optional object { mode }` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `encrypted_content: object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `recipient: string` - - The destination agent identity. - - - `type: "agent_message"` - - The item type. Always `agent_message`. - - - `id: optional string` - - The unique ID of this agent message item. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `arguments: string` - - The action arguments as a JSON string. - - - `call_id: string` - - The unique ID linking this call to its output. - - - `type: "multi_agent_call"` - - The item type. Always `multi_agent_call`. - - - `id: optional string` - - The unique ID of this multi-agent call. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: string` - - The unique ID of the multi-agent call. - - - `output: array of object { text, type, annotations }` - - Text output returned by the multi-agent action. - - - `text: string` - - The text content. - - - `type: "output_text"` - - The content type. Always `output_text`. - - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - Citations associated with the text content. - - - `union_member_0: array of object { file_id, filename, index, type }` - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the file cited. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_citation"` - - The citation type. Always `file_citation`. - - - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - - `end_index: number` - - The index of the last character of the citation in the message. - - - `start_index: number` - - The index of the first character of the citation in the message. - - - `title: string` - - The title of the cited resource. - - - `type: "url_citation"` - - The citation type. Always `url_citation`. - - - `url: string` - - The URL of the cited resource. - - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - - `container_id: string` - - The ID of the container. - - - `end_index: number` - - The index of the last character of the citation in the message. - - - `file_id: string` - - The ID of the container file. - - - `filename: string` - - The filename of the container file cited. - - - `start_index: number` - - The index of the first character of the citation in the message. - - - `type: "container_file_citation"` + - `mode: "explicit"` - The citation type. Always `container_file_citation`. + The breakpoint mode. Always `explicit`. - - `type: "multi_agent_call_output"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The item type. Always `multi_agent_call_output`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `id: optional string` + - `detail: "low" or "high" or "auto" or "original"` - The unique ID of this multi-agent call output. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `"high"` - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"original"` - - `tool_search_call: object { arguments, type, id, 4 more }` + - `type: "input_image"` - - `arguments: unknown` + The type of the input item. Always `input_image`. - The arguments supplied to the tool search call. + - `file_id: optional string` - - `type: "tool_search_call"` + The ID of the file to be sent to the model. - The item type. Always `tool_search_call`. + - `image_url: optional string` - - `id: optional string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The unique ID of this tool search call. + - `prompt_cache_breakpoint: optional object { mode }` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + - `mode: "explicit"` - - `agent_name: string` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `call_id: optional string` + A file input to the model. - The unique ID of the tool search call generated by the model. + - `type: "input_file"` - - `execution: optional "server" or "client"` + The type of the input item. Always `input_file`. - Whether tool search was executed by the server or by the client. + - `detail: optional "auto" or "low" or "high"` - - `"server"` + 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`. - - `"client"` + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"low"` - The status of the tool search call. + - `"high"` - - `"in_progress"` + - `file_data: optional string` - - `"completed"` + The content of the file to be sent to the model. - - `"incomplete"` + - `file_id: optional string` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + The ID of the file to be sent to the model. - - `tools: array of BetaTool` + - `file_url: optional string` - The loaded tool definitions returned by the tool search output. + The URL of the file to be sent to the model. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `filename: optional string` - 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). + The name of the file to be sent to the model. - - `name: string` + - `prompt_cache_breakpoint: optional object { mode }` - The name of the function to call. + 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. - - `parameters: map[unknown]` + - `mode: "explicit"` - A JSON schema object describing the parameters of the function. + The breakpoint mode. Always `explicit`. - - `strict: boolean` + - `role: "user" or "assistant" or "system" or "developer"` - Whether strict parameter validation is enforced for this function tool. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `type: "function"` + - `"user"` - The type of the function tool. Always `function`. + - `"assistant"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"system"` - The tool invocation context(s). + - `"developer"` - - `"direct"` + - `phase: optional "commentary" or "final_answer"` - - `"programmatic"` + 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. - - `defer_loading: optional boolean` + - `"commentary"` - Whether this function is deferred and loaded via tool search. + - `"final_answer"` - - `description: optional string` + - `type: optional "message"` - A description of the function. Used by the model to determine whether or not to call the function. + The type of the message input. Always `message`. - - `output_schema: optional map[unknown]` + - `"message"` - A JSON schema object describing the JSON value encoded in string outputs for this function. +### Beta File Search Tool - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` +- `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` 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). @@ -29437,7 +27595,7 @@ Cancel a response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -29447,7 +27605,11 @@ Cancel a response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -29494,7 +27656,7 @@ Cancel a response - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -29504,7 +27666,11 @@ Cancel a response - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -29548,116 +27714,15 @@ Cancel a response 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. - - `beta_computer_tool: object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `type: "computer"` - - The type of the computer tool. Always `computer`. - - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `display_height: number` - - The height of the computer display. - - - `display_width: number` - - The width of the computer display. - - - `environment: "windows" or "mac" or "linux" or 2 more` - - The type of computer environment to control. - - - `"windows"` - - - `"mac"` - - - `"linux"` - - - `"ubuntu"` - - - `"browser"` - - - `type: "computer_use_preview"` - - The type of the computer use tool. Always `computer_use_preview`. - - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `type: "web_search" or "web_search_2025_08_26"` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - - `"web_search"` - - - `"web_search_2025_08_26"` - - - `filters: optional object { allowed_domains }` - - Filters for the search. - - - `allowed_domains: optional array of string` - - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - - - `search_context_size: optional "low" or "medium" or "high"` - - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` - - Free text input for the city of the user, e.g. `San Francisco`. - - - `country: optional string` - - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - - `region: optional string` - - Free text input for the region of the user, e.g. `California`. - - - `timezone: optional string` - - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - - `type: optional "approximate"` - - The type of location approximation. Always `approximate`. - - - `"approximate"` - - - `mcp: object { server_label, type, allowed_callers, 9 more }` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). +### Beta Function Shell Tool - - `server_label: string` +- `beta_function_shell_tool: object { type, allowed_callers, environment }` - A label for this MCP server, used to identify it in tool calls. + A tool that allows the model to execute shell commands. - - `type: "mcp"` + - `type: "shell"` - The type of the MCP tool. Always `mcp`. + The type of the shell tool. Always `shell`. - `allowed_callers: optional array of "direct" or "programmatic"` @@ -29667,159 +27732,13 @@ Cancel a response - `"programmatic"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` - - List of allowed tool names or a filter object. - - - `MCP allowed tools: array of string` - - A string array of allowed tool names - - - `MCP tool filter: object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `authorization: optional string` - - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. - - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - - Currently supported `connector_id` values are: - - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` - - - `"connector_dropbox"` - - - `"connector_gmail"` - - - `"connector_googlecalendar"` - - - `"connector_googledrive"` - - - `"connector_microsoftteams"` - - - `"connector_outlookcalendar"` - - - `"connector_outlookemail"` - - - `"connector_sharepoint"` - - - `defer_loading: optional boolean` - - Whether this MCP tool is deferred and discovered via tool search. - - - `headers: optional map[string]` - - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. - - - `require_approval: optional object { always, never } or "always" or "never"` - - Specify which of the MCP server's tools require approval. - - - `MCP tool approval filter: object { always, never }` - - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. - - - `always: optional object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `never: optional object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `MCP tool approval setting: "always" or "never"` - - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. - - - `"always"` - - - `"never"` - - - `server_description: optional string` - - Optional description of the MCP server, used to provide more context. - - - `server_url: optional string` - - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. - - - `tunnel_id: optional string` - - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. - - - `code_interpreter: object { container, type, allowed_callers }` - - A tool that runs Python code to help generate a response to a prompt. - - - `container: string or object { type, file_ids, memory_limit, network_policy }` - - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. - - - `union_member_0: string` - - The container ID. - - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `type: "auto"` + - `type: "container_auto"` - Always `auto`. + Automatically creates a container for this request - `file_ids: optional array of string` @@ -29827,7 +27746,7 @@ Cancel a response - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The memory limit for the code interpreter container. + The memory limit for the container. - `"1g"` @@ -29873,160 +27792,107 @@ Cancel a response The secret value to inject for the domain. - - `type: "code_interpreter"` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `programmatic_tool_calling: object { type }` - - - `image_generation: object { type, action, background, 9 more }` - - A tool that generates images using the GPT image models. - - - `type: "image_generation"` - - The type of the image generation tool. Always `image_generation`. - - - `action: optional "generate" or "edit" or "auto"` - - Whether to generate a new image or edit an existing image. Default: `auto`. - - - `"generate"` - - - `"edit"` - - - `"auto"` - - - `background: optional "transparent" or "opaque" or "auto"` - - Allows to set transparency for the background of the generated image(s). - This parameter is only supported for GPT image models that support - transparent backgrounds. Must be one of `transparent`, `opaque`, or - `auto` (default value). When `auto` is used, the model will - automatically determine the best background for the image. - - `gpt-image-2` and `gpt-image-2-2026-04-21` do not support - transparent backgrounds. Requests with `background` set to - `transparent` will return an error for these models; use `opaque` or - `auto` instead. - - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. - - - `"transparent"` - - - `"opaque"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"auto"` + An optional list of skills referenced by id or inline data. - - `input_fidelity: optional "high" or "low"` + - `beta_skill_reference: object { skill_id, type, version }` - 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`. + - `skill_id: string` - - `"high"` + The ID of the referenced skill. - - `"low"` + - `type: "skill_reference"` - - `input_image_mask: optional object { file_id, image_url }` + References a skill created with the /v1/skills endpoint. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `version: optional string` - - `file_id: optional string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - File ID for the mask image. + - `beta_inline_skill: object { description, name, source, type }` - - `image_url: optional string` + - `description: string` - Base64-encoded mask image. + The description of the skill. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `name: string` - The image generation model to use. Default: `gpt-image-1`. + The name of the skill. - - `"gpt-image-1"` + - `source: object { data, media_type, type }` - - `"gpt-image-1-mini"` + Inline skill payload - - `"gpt-image-2"` + - `data: string` - - `"gpt-image-2-2026-04-21"` + Base64-encoded skill zip bundle. - - `"gpt-image-1.5"` + - `media_type: "application/zip"` - - `"chatgpt-image-latest"` + The media type of the inline skill payload. Must be `application/zip`. - - `moderation: optional "auto" or "low"` + - `type: "base64"` - Moderation level for the generated image. Default: `auto`. + The type of the inline skill source. Must be `base64`. - - `"auto"` + - `type: "inline"` - - `"low"` + Defines an inline skill for this request. - - `output_compression: optional number` + - `beta_local_environment: object { type, skills }` - Compression level for the output image. Default: 100. + - `type: "local"` - - `output_format: optional "png" or "webp" or "jpeg"` + Use a local computer environment. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `skills: optional array of BetaLocalSkill` - - `"png"` + An optional list of skills. - - `"webp"` + - `description: string` - - `"jpeg"` + The description of the skill. - - `partial_images: optional number` + - `name: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The name of the skill. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `path: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The path to the directory containing the skill. - - `"low"` + - `beta_container_reference: object { container_id, type }` - - `"medium"` + - `container_id: string` - - `"high"` + The ID of the referenced container. - - `"auto"` + - `type: "container_reference"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + References a container created with the /v1/containers endpoint - 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`. +### Beta Function Tool - - `"1024x1024"` +- `beta_function_tool: object { name, parameters, strict, 5 more }` - - `"1024x1536"` + 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). - - `"1536x1024"` + - `name: string` - - `"auto"` + The name of the function to call. - - `local_shell: object { type }` + - `parameters: map[unknown]` - A tool that allows the model to execute shell commands in a local environment. + A JSON schema object describing the parameters of the function. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `strict: boolean` - A tool that allows the model to execute shell commands. + Whether strict parameter validation is enforced for this function tool. - - `type: "shell"` + - `type: "function"` - The type of the shell tool. Always `shell`. + The type of the function tool. Always `function`. - `allowed_callers: optional array of "direct" or "programmatic"` @@ -30036,67 +27902,53 @@ Cancel a response - `"programmatic"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - - `type: "container_auto"` - - Automatically creates a container for this request - - - `file_ids: optional array of string` - - An optional list of uploaded files to make available to your code. - - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - The memory limit for the container. + - `defer_loading: optional boolean` - - `"1g"` + Whether this function is deferred and loaded via tool search. - - `"4g"` + - `description: optional string` - - `"16g"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"64g"` + - `output_schema: optional map[unknown]` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Network access policy for the container. +### Beta Inline Skill - - `beta_container_network_policy_disabled: object { type }` +- `beta_inline_skill: object { description, name, source, type }` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `description: string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The description of the skill. - An optional list of skills referenced by id or inline data. + - `name: string` - - `beta_skill_reference: object { skill_id, type, version }` + The name of the skill. - - `skill_id: string` + - `source: object { data, media_type, type }` - The ID of the referenced skill. + Inline skill payload - - `type: "skill_reference"` + - `data: string` - References a skill created with the /v1/skills endpoint. + Base64-encoded skill zip bundle. - - `version: optional string` + - `media_type: "application/zip"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The media type of the inline skill payload. Must be `application/zip`. - - `beta_inline_skill: object { description, name, source, type }` + - `type: "base64"` - - `description: string` + The type of the inline skill source. Must be `base64`. - The description of the skill. + - `type: "inline"` - - `name: string` + Defines an inline skill for this request. - The name of the skill. +### Beta Inline Skill Source - - `source: object { data, media_type, type }` +- `beta_inline_skill_source: object { data, media_type, type }` Inline skill payload @@ -30112,11 +27964,9 @@ Cancel a response The type of the inline skill source. Must be `base64`. - - `type: "inline"` - - Defines an inline skill for this request. +### Beta Local Environment - - `beta_local_environment: object { type, skills }` +- `beta_local_environment: object { type, skills }` - `type: "local"` @@ -30138,73 +27988,25 @@ Cancel a response The path to the directory containing the skill. - - `beta_container_reference: object { container_id, type }` - - - `container_id: string` - - The ID of the referenced container. - - - `type: "container_reference"` +### Beta Local Skill - References a container created with the /v1/containers endpoint +- `beta_local_skill: object { description, name, path }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `description: string` - 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) + The description of the skill. - `name: string` - The name of the custom tool, used to identify it in tool calls. - - - `type: "custom"` - - The type of the custom tool. Always `custom`. - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this tool should be deferred and discovered via tool search. - - - `description: optional string` - - Optional description of the custom tool, used to provide more context. - - - `format: optional object { type } or object { definition, syntax, type }` - - The input format for the custom tool. Default is unconstrained text. - - - `text: object { type }` - - Unconstrained free-form text. - - - `grammar: object { definition, syntax, type }` - - A grammar defined by the user. - - - `definition: string` - - The grammar definition. - - - `syntax: "lark" or "regex"` - - The syntax of the grammar definition. One of `lark` or `regex`. - - - `"lark"` + The name of the skill. - - `"regex"` + - `path: string` - - `type: "grammar"` + The path to the directory containing the skill. - Grammar format. Always `grammar`. +### Beta Namespace Tool - - `beta_namespace_tool: object { description, name, tools, type }` +- `beta_namespace_tool: object { description, name, tools, type }` Groups function/custom tools under a shared namespace. @@ -30266,6 +28068,10 @@ Cancel a response The tool invocation context(s). + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -30278,467 +28084,485 @@ Cancel a response The input format for the custom tool. Default is unconstrained text. - - `type: "namespace"` + - `text: object { type }` - The type of the tool. Always `namespace`. + Unconstrained free-form text. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `grammar: object { definition, syntax, type }` - Hosted or BYOT tool search configuration for deferred tools. + A grammar defined by the user. - - `type: "tool_search"` + - `definition: string` - The type of the tool. Always `tool_search`. + The grammar definition. - - `description: optional string` + - `syntax: "lark" or "regex"` - Description shown to the model for a client-executed tool search tool. + The syntax of the grammar definition. One of `lark` or `regex`. - - `execution: optional "server" or "client"` + - `"lark"` - Whether tool search is executed by the server or by the client. + - `"regex"` - - `"server"` + - `type: "grammar"` - - `"client"` + Grammar format. Always `grammar`. - - `parameters: optional unknown` + - `type: "namespace"` - Parameter schema for a client-executed tool search tool. + The type of the tool. Always `namespace`. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` +### Beta Response - 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). +- `beta_response: object { id, created_at, error, 31 more }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `id: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Unique identifier for this Response. - - `"web_search_preview"` + - `created_at: number` - - `"web_search_preview_2025_03_11"` + Unix timestamp (in seconds) of when this Response was created. - - `search_content_types: optional array of "text" or "image"` + - `error: object { code, message }` - - `"text"` + An error object returned when the model fails to generate a Response. - - `"image"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `search_context_size: optional "low" or "medium" or "high"` + The error code for the response. - 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. + - `"server_error"` - - `"low"` + - `"rate_limit_exceeded"` - - `"medium"` + - `"invalid_prompt"` - - `"high"` + - `"bio_policy"` - - `user_location: optional object { type, city, country, 2 more }` + - `"vector_store_timeout"` - The user's location. + - `"invalid_image"` - - `type: "approximate"` + - `"invalid_image_format"` - The type of location approximation. Always `approximate`. + - `"invalid_base64_image"` - - `city: optional string` + - `"invalid_image_url"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"image_too_large"` - - `country: optional string` + - `"image_too_small"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"image_parse_error"` - - `region: optional string` + - `"image_content_policy_violation"` - Free text input for the region of the user, e.g. `California`. + - `"invalid_image_mode"` - - `timezone: optional string` + - `"image_file_too_large"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"unsupported_image_media_type"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"empty_image_file"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"failed_to_download_image"` - - `type: "apply_patch"` + - `"image_file_not_found"` - The type of the tool. Always `apply_patch`. + - `message: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + A human-readable description of the error. - The tool invocation context(s). + - `incomplete_details: object { reason }` - - `"direct"` + Details about why the response is incomplete. - - `"programmatic"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `type: "tool_search_output"` + The reason why the response is incomplete. - The item type. Always `tool_search_output`. + - `"max_output_tokens"` - - `id: optional string` + - `"content_filter"` - The unique ID of this tool search output. + - `instructions: string or array of BetaResponseInputItem` - - `agent: optional object { agent_name }` + A system (or developer) message inserted into the model's context. - The agent that produced this item. + When using 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. - - `agent_name: string` + - `union_member_0: string` - The canonical name of the agent that produced this item. + A text input to the model, equivalent to a text input with the + `developer` role. - - `call_id: optional string` + - `Input item list: array of BetaResponseInputItem` - The unique ID of the tool search call generated by the model. + A list of one or many input items to the model, containing + different content types. - - `execution: optional "server" or "client"` + - `beta_easy_input_message: object { content, role, phase, type }` - Whether tool search was executed by the server or by the client. + 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. - - `"server"` + - `content: string or BetaResponseInputMessageContentList` - - `"client"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Text input: string` - The status of the tool search output. + A text input to the model. - - `"in_progress"` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - `"completed"` + A list of one or many input items to the model, containing different content + types. - - `"incomplete"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `additional_tools: object { role, tools, type, 2 more }` + A text input to the model. - - `role: "developer"` + - `text: string` - The role that provided the additional tools. Only `developer` is supported. + The text input to the model. - - `tools: array of BetaTool` + - `type: "input_text"` - A list of additional tools made available at this item. + The type of the input item. Always `input_text`. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `prompt_cache_breakpoint: optional object { mode }` - 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). + 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. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `mode: "explicit"` - 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). + The breakpoint mode. Always `explicit`. - - `beta_computer_tool: object { type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `detail: "low" or "high" or "auto" or "original"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `"low"` - 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). + - `"high"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `"auto"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"original"` - - `code_interpreter: object { container, type, allowed_callers }` + - `type: "input_image"` - A tool that runs Python code to help generate a response to a prompt. + The type of the input item. Always `input_image`. - - `programmatic_tool_calling: object { type }` + - `file_id: optional string` - - `image_generation: object { type, action, background, 9 more }` + The ID of the file to be sent to the model. - A tool that generates images using the GPT image models. + - `image_url: optional string` - - `local_shell: object { type }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - A tool that allows the model to execute shell commands in a local environment. + - `prompt_cache_breakpoint: optional object { mode }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + 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. - A tool that allows the model to execute shell commands. + - `mode: "explicit"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The breakpoint mode. Always `explicit`. - 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) + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `beta_namespace_tool: object { description, name, tools, type }` + A file input to the model. - Groups function/custom tools under a shared namespace. + - `type: "input_file"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The type of the input item. Always `input_file`. - Hosted or BYOT tool search configuration for deferred tools. + - `detail: optional "auto" or "low" or "high"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + 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`. - 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). + - `"auto"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"low"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"high"` - - `type: "additional_tools"` + - `file_data: optional string` - The item type. Always `additional_tools`. + The content of the file to be sent to the model. - - `id: optional string` + - `file_id: optional string` - The unique ID of this additional tools item. + The ID of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `file_url: optional string` - The agent that produced this item. + The URL of the file to be sent to the model. - - `agent_name: string` + - `filename: optional string` - The canonical name of the agent that produced this item. + The name of the file to be sent to the model. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `prompt_cache_breakpoint: optional object { mode }` - 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). + 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. - - `id: string` + - `mode: "explicit"` - The unique identifier of the reasoning content. + The breakpoint mode. Always `explicit`. - - `summary: array of object { text, type }` + - `role: "user" or "assistant" or "system" or "developer"` - Reasoning summary content. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `text: string` + - `"user"` - A summary of the reasoning output from the model so far. + - `"assistant"` - - `type: "summary_text"` + - `"system"` - The type of the object. Always `summary_text`. + - `"developer"` - - `type: "reasoning"` + - `phase: optional "commentary" or "final_answer"` - The type of the object. Always `reasoning`. + 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. - - `agent: optional object { agent_name }` + - `"commentary"` - The agent that produced this item. + - `"final_answer"` - - `agent_name: string` + - `type: optional "message"` - The canonical name of the agent that produced this item. + The type of the message input. Always `message`. - - `content: optional array of object { text, type }` + - `"message"` - Reasoning text content. + - `message: object { content, role, agent, 2 more }` - - `text: string` + 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. - The reasoning text from the model. + - `content: array of BetaResponseInputContent` - - `type: "reasoning_text"` + A list of one or many input items to the model, containing different content + types. - The type of the reasoning text. Always `reasoning_text`. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `encrypted_content: optional string` + A text input to the model. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"in_progress"` + A file input to the model. - - `"completed"` + - `role: "user" or "system" or "developer"` - - `"incomplete"` + The role of the message input. One of `user`, `system`, or `developer`. - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `"user"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"system"` - - `encrypted_content: string` + - `"developer"` - The encrypted content of the compaction summary. + - `agent: optional object { agent_name }` - - `type: "compaction"` + The agent that produced this item. - The type of the item. Always `compaction`. + - `agent_name: string` - - `id: optional string` + The canonical name of the agent that produced this item. - The ID of the compaction item. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The agent that produced this item. + - `"in_progress"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` - - `image_generation_call: object { id, result, status, 2 more }` + - `type: optional "message"` - An image generation request made by the model. + The type of the message input. Always set to `message`. + + - `"message"` + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. - `id: string` - The unique ID of the image generation call. + The unique ID of the output message. - - `result: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The generated image encoded in base64. + The content of the output message. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - The status of the image generation call. + A text output from the model. - - `"in_progress"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `"completed"` + The annotations of the text output. - - `"generating"` + - `file_citation: object { file_id, filename, index, type }` - - `"failed"` + A citation to a file. - - `type: "image_generation_call"` + - `file_id: string` - The type of the image generation call. Always `image_generation_call`. + The ID of the file. - - `agent: optional object { agent_name }` + - `filename: string` - The agent that produced this item. + The filename of the file cited. - - `agent_name: string` + - `index: number` - The canonical name of the agent that produced this item. + The index of the file in the list of files. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `type: "file_citation"` - A tool call to run code. + The type of the file citation. Always `file_citation`. - - `id: string` + - `url_citation: object { end_index, start_index, title, 2 more }` - The unique ID of the code interpreter tool call. + A citation for a web resource used to generate a model response. - - `code: string` + - `end_index: number` - The code to run, or null if not available. + The index of the last character of the URL citation in the message. - - `container_id: string` + - `start_index: number` - The ID of the container used to run the code. + The index of the first character of the URL citation in the message. - - `outputs: array of object { logs, type } or object { type, url }` + - `title: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The title of the web resource. - - `logs: object { logs, type }` + - `type: "url_citation"` - The logs output from the code interpreter. + The type of the URL citation. Always `url_citation`. - - `logs: string` + - `url: string` - The logs output from the code interpreter. + The URL of the web resource. - - `type: "logs"` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - The type of the output. Always `logs`. + A citation for a container file used to generate a model response. - - `image: object { type, url }` + - `container_id: string` - The image output from the code interpreter. + The ID of the container file. - - `type: "image"` + - `end_index: number` - The type of the output. Always `image`. + The index of the last character of the container file citation in the message. - - `url: string` + - `file_id: string` - The URL of the image output from the code interpreter. + The ID of the file. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `filename: string` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The filename of the container file cited. - - `"in_progress"` + - `start_index: number` - - `"completed"` + The index of the first character of the container file citation in the message. - - `"incomplete"` + - `type: "container_file_citation"` - - `"interpreting"` + The type of the container file citation. Always `container_file_citation`. - - `"failed"` + - `file_path: object { file_id, index, type }` - - `type: "code_interpreter_call"` + A path to a file. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `file_id: string` - - `agent: optional object { agent_name }` + The ID of the file. - The agent that produced this item. + - `index: number` - - `agent_name: string` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `type: "file_path"` - - `local_shell_call: object { id, action, call_id, 3 more }` + The type of the file path. Always `file_path`. - A tool call to run a command on the local shell. + - `text: string` - - `id: string` + The text output from the model. - The unique ID of the local shell call. + - `type: "output_text"` - - `action: object { command, env, type, 3 more }` + The type of the output text. Always `output_text`. - Execute a shell command on the server. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `command: array of string` + - `token: string` - The command to run. + - `bytes: array of number` - - `env: map[string]` + - `logprob: number` - Environment variables to set for the command. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "exec"` + - `token: string` - The type of the local shell action. Always `exec`. + - `bytes: array of number` - - `timeout_ms: optional number` + - `logprob: number` - Optional timeout in milliseconds for the command. + - `beta_response_output_refusal: object { refusal, type }` - - `user: optional string` + A refusal from the model. - Optional user to run the command as. + - `refusal: string` - - `working_directory: optional string` + The refusal explanation from the model. - Optional working directory to run the command in. + - `type: "refusal"` - - `call_id: string` + The type of the refusal. Always `refusal`. - The unique ID of the local shell tool call generated by the model. + - `role: "assistant"` + + The role of the output message. Always `assistant`. - `status: "in_progress" or "completed" or "incomplete"` - The status of the local shell call. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -30746,9 +28570,9 @@ Cancel a response - `"incomplete"` - - `type: "local_shell_call"` + - `type: "message"` - The type of the local shell call. Always `local_shell_call`. + The type of the output message. Always `message`. - `agent: optional object { agent_name }` @@ -30758,107 +28582,123 @@ Cancel a response The canonical name of the agent that produced this item. - - `local_shell_call_output: object { id, output, type, 2 more }` - - The output of a local shell tool call. - - - `id: string` + - `phase: optional "commentary" or "final_answer"` - The unique ID of the local shell tool call generated by the model. + 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. - - `output: string` + - `"commentary"` - A JSON string of the output of the local shell tool call. + - `"final_answer"` - - `type: "local_shell_call_output"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The type of the local shell tool call output. Always `local_shell_call_output`. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + The unique ID of the file search tool call. - - `agent_name: string` + - `queries: array of string` - The canonical name of the agent that produced this item. + The queries used to search for files. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - `"incomplete"` - - `shell_call: object { action, call_id, type, 5 more }` + - `"failed"` - A tool representing a request to execute one or more shell commands. + - `type: "file_search_call"` - - `action: object { commands, max_output_length, timeout_ms }` + The type of the file search tool call. Always `file_search_call`. - The shell commands and limits that describe how to run the tool call. + - `agent: optional object { agent_name }` - - `commands: array of string` + The agent that produced this item. - Ordered shell commands for the execution environment to run. + - `agent_name: string` - - `max_output_length: optional number` + The canonical name of the agent that produced this item. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `timeout_ms: optional number` + The results of the file search tool call. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `attributes: optional map[string or number or boolean]` - - `call_id: string` + 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. - The unique ID of the shell tool call generated by the model. + - `union_member_0: string` - - `type: "shell_call"` + - `union_member_1: number` - The type of the item. Always `shell_call`. + - `union_member_2: boolean` - - `id: optional string` + - `file_id: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + The unique ID of the file. - - `agent: optional object { agent_name }` + - `filename: optional string` - The agent that produced this item. + The name of the file. - - `agent_name: string` + - `score: optional number` - The canonical name of the agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `caller: optional object { type } or object { caller_id, type }` + - `text: optional string` - The execution context that produced this tool call. + The text that was retrieved from the file. - - `direct: object { type }` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `program: object { caller_id, type }` + 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. - - `caller_id: string` + - `id: string` - The call ID of the program item that produced this tool call. + The unique ID of the computer call. - - `type: "program"` + - `call_id: string` - The caller type. Always `program`. + An identifier used when responding to the tool call with output. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `pending_safety_checks: array of object { id, code, message }` - The environment to execute the shell commands in. + The pending safety checks for the computer call. - - `beta_local_environment: object { type, skills }` + - `id: string` - - `beta_container_reference: object { container_id, type }` + The ID of the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `code: optional string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -30866,211 +28706,221 @@ Cancel a response - `"incomplete"` - - `shell_call_output: object { call_id, output, type, 5 more }` + - `type: "computer_call"` - The streamed output items emitted by a shell tool call. + The type of the computer call. Always `computer_call`. - - `call_id: string` + - `"computer_call"` - The unique ID of the shell tool call generated by the model. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `output: array of BetaResponseFunctionShellCallOutputContent` + A click action. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `click: object { button, type, x, 2 more }` - - `outcome: object { type } or object { exit_code, type }` + A click action. - The exit or timeout outcome associated with this shell call. + - `button: "left" or "right" or "wheel" or 2 more` - - `timeout: object { type }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Indicates that the shell call exceeded its configured time limit. + - `"left"` - - `exit: object { exit_code, type }` + - `"right"` - Indicates that the shell commands finished and returned an exit code. + - `"wheel"` - - `exit_code: number` + - `"back"` - The exit code returned by the shell process. + - `"forward"` - - `type: "exit"` + - `type: "click"` - The outcome type. Always `exit`. + Specifies the event type. For a click action, this property is always `click`. - - `stderr: string` + - `x: number` - Captured stderr output for the shell call. + The x-coordinate where the click occurred. - - `stdout: string` + - `y: number` - Captured stdout output for the shell call. + The y-coordinate where the click occurred. - - `type: "shell_call_output"` + - `keys: optional array of string` - The type of the item. Always `shell_call_output`. + The keys being held while clicking. - - `id: optional string` + - `double_click: object { keys, type, x, y }` - The unique ID of the shell tool call output. Populated when this item is returned via API. + A double click action. - - `agent: optional object { agent_name }` + - `keys: array of string` - The agent that produced this item. + The keys being held while double-clicking. - - `agent_name: string` + - `type: "double_click"` - The canonical name of the agent that produced this item. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `caller: optional object { type } or object { caller_id, type }` + - `x: number` - The execution context that produced this tool call. + The x-coordinate where the double click occurred. - - `direct: object { type }` + - `y: number` - - `program: object { caller_id, type }` + The y-coordinate where the double click occurred. - - `caller_id: string` + - `drag: object { path, type, keys }` - The call ID of the program item that produced this tool call. + A drag action. - - `type: "program"` + - `path: array of object { x, y }` - The caller type. Always `program`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `max_output_length: optional number` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `x: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The x-coordinate. - The status of the shell call output. + - `y: number` - - `"in_progress"` + The y-coordinate. - - `"completed"` + - `type: "drag"` - - `"incomplete"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `keys: optional array of string` - A tool call representing a request to create, delete, or update files using diff patches. + The keys being held while dragging the mouse. - - `call_id: string` + - `keypress: object { keys, type }` - The unique ID of the apply patch tool call generated by the model. + A collection of keypresses the model would like to perform. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `keys: array of string` - The specific create, delete, or update instruction for the apply_patch tool call. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `create_file: object { diff, path, type }` + - `type: "keypress"` - Instruction for creating a new file via the apply_patch tool. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `diff: string` + - `move: object { type, x, y, keys }` - Unified diff content to apply when creating the file. + A mouse move action. - - `path: string` + - `type: "move"` - Path of the file to create relative to the workspace root. + Specifies the event type. For a move action, this property is always set to `move`. - - `type: "create_file"` + - `x: number` - The operation type. Always `create_file`. + The x-coordinate to move to. - - `delete_file: object { path, type }` + - `y: number` - Instruction for deleting an existing file via the apply_patch tool. + The y-coordinate to move to. - - `path: string` + - `keys: optional array of string` - Path of the file to delete relative to the workspace root. + The keys being held while moving the mouse. - - `type: "delete_file"` + - `screenshot: object { type }` - The operation type. Always `delete_file`. + A screenshot action. - - `update_file: object { diff, path, type }` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - Instruction for updating an existing file via the apply_patch tool. + A scroll action. - - `diff: string` + - `scroll_x: number` - Unified diff content to apply to the existing file. + The horizontal scroll distance. - - `path: string` + - `scroll_y: number` - Path of the file to update relative to the workspace root. + The vertical scroll distance. - - `type: "update_file"` + - `type: "scroll"` - The operation type. Always `update_file`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `status: "in_progress" or "completed"` + - `x: number` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The x-coordinate where the scroll occurred. - - `"in_progress"` + - `y: number` - - `"completed"` + The y-coordinate where the scroll occurred. - - `type: "apply_patch_call"` + - `keys: optional array of string` - The type of the item. Always `apply_patch_call`. + The keys being held while scrolling. - - `id: optional string` + - `type: object { text, type }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + An action to type in text. - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The text to type. - - `agent_name: string` + - `type: "type"` - The canonical name of the agent that produced this item. + Specifies the event type. For a type action, this property is always set to `type`. - - `caller: optional object { type } or object { caller_id, type }` + - `wait: object { type }` - The execution context that produced this tool call. + A wait action. - - `direct: object { type }` + - `actions: optional array of BetaComputerAction` - - `program: object { caller_id, type }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `caller_id: string` + - `click: object { button, type, x, 2 more }` - The call ID of the program item that produced this tool call. + A click action. - - `type: "program"` + - `double_click: object { keys, type, x, y }` - The caller type. Always `program`. + A double click action. - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `drag: object { path, type, keys }` - The streamed output emitted by an apply patch tool call. + A drag action. - - `call_id: string` + - `keypress: object { keys, type }` - The unique ID of the apply patch tool call generated by the model. + A collection of keypresses the model would like to perform. - - `status: "completed" or "failed"` + - `move: object { type, x, y, keys }` - The status of the apply patch tool call output. One of `completed` or `failed`. + A mouse move action. - - `"completed"` + - `screenshot: object { type }` - - `"failed"` + A screenshot action. - - `type: "apply_patch_call_output"` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The type of the item. Always `apply_patch_call_output`. + A scroll action. - - `id: optional string` + - `type: object { text, type }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + An action to type in text. + + - `wait: object { type }` + + A wait action. - `agent: optional object { agent_name }` @@ -31080,61 +28930,54 @@ Cancel a response The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` + - `computer_call_output: object { call_id, output, type, 4 more }` - The call ID of the program item that produced this tool call. + The output of a computer tool call. - - `type: "program"` + - `call_id: string` - The caller type. Always `program`. + The ID of the computer tool call that produced the output. - - `output: optional string` + - `output: object { type, file_id, image_url }` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + A computer screenshot image used with the computer use tool. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `type: "computer_screenshot"` - A list of tools available on an MCP server. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `id: string` + - `file_id: optional string` - The unique ID of the list. + The identifier of an uploaded file that contains the screenshot. - - `server_label: string` + - `image_url: optional string` - The label of the MCP server. + The URL of the screenshot image. - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "computer_call_output"` - The tools available on the server. + The type of the computer tool call output. Always `computer_call_output`. - - `input_schema: unknown` + - `id: optional string` - The JSON schema describing the tool's input. + The ID of the computer tool call output. - - `name: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The name of the tool. + The safety checks reported by the API that have been acknowledged by the developer. - - `annotations: optional unknown` + - `id: string` - Additional annotations about the tool. + The ID of the pending safety check. - - `description: optional string` + - `code: optional string` - The description of the tool. + The type of the pending safety check. - - `type: "mcp_list_tools"` + - `message: optional string` - The type of the item. Always `mcp_list_tools`. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -31144,61 +28987,101 @@ Cancel a response The canonical name of the agent that produced this item. - - `error: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Error message if the server could not list tools. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `"in_progress"` - A request for human approval of a tool invocation. + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_web_search: object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` - The unique ID of the approval request. + The unique ID of the web search tool call. - - `arguments: string` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - A JSON string of arguments for the tool. + 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). - - `name: string` + - `search: object { type, queries, query, sources }` - The name of the tool to run. + Action type "search" - Performs a web search query. - - `server_label: string` + - `type: "search"` - The label of the MCP server making the request. + The action type. - - `type: "mcp_approval_request"` + - `queries: optional array of string` - The type of the item. Always `mcp_approval_request`. + The search queries. - - `agent: optional object { agent_name }` + - `query: optional string` - The agent that produced this item. + The search query. - - `agent_name: string` + - `sources: optional array of object { type, url }` - The canonical name of the agent that produced this item. + The sources used in the search. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + - `type: "url"` - A response to an MCP approval request. + The type of source. Always `url`. - - `approval_request_id: string` + - `url: string` - The ID of the approval request being answered. + The URL of the source. - - `approve: boolean` + - `open_page: object { type, url }` - Whether the request was approved. + Action type "open_page" - Opens a specific URL from search results. - - `type: "mcp_approval_response"` + - `type: "open_page"` - The type of the item. Always `mcp_approval_response`. + The action type. - - `id: optional string` + - `url: optional string` - The unique ID of the approval response + The URL opened by the model. + + - `find_in_page: object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. - `agent: optional object { agent_name }` @@ -31208,33 +29091,30 @@ Cancel a response The canonical name of the agent that produced this item. - - `reason: optional string` - - Optional reason for the decision. - - - `mcp_call: object { id, arguments, name, 7 more }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - An invocation of a tool on an MCP server. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the tool call. + A JSON string of the arguments to pass to the function. - - `arguments: string` + - `call_id: string` - A JSON string of the arguments passed to the tool. + The unique ID of the function tool call generated by the model. - `name: string` - The name of the tool that was run. + The name of the function to run. - - `server_label: string` + - `type: "function_call"` - The label of the MCP server running the tool. + The type of the function tool call. Always `function_call`. - - `type: "mcp_call"` + - `id: optional string` - The type of the item. Always `mcp_call`. + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -31244,22 +29124,28 @@ Cancel a response The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - - `error: optional string` + - `direct: object { type }` - The error from the tool call, if any. + - `program: object { caller_id, type }` - - `output: optional string` + - `caller_id: string` - The output from the tool call. + The call ID of the program item that produced this tool call. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `type: "program"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -31267,32 +29153,27 @@ Cancel a response - `"incomplete"` - - `"calling"` - - - `"failed"` - - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `function_call_output: object { call_id, output, type, 4 more }` - The output of a custom tool call from your code, being sent back to the model. + The output of a function tool call. - `call_id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the function tool call generated by the model. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `output: string or BetaResponseFunctionCallOutputItemList` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Text, image, or file output of the function tool call. - - `string output: string` + - `union_member_0: string` - A string of the output of the custom tool call. + A JSON string of the output of the function tool call. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - Text, image, or file output of the custom tool call. + An array of content outputs (text, image, file) for the function tool call. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -31308,18 +29189,30 @@ Cancel a response 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. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The breakpoint mode. Always `explicit`. - - `detail: "low" or "high" or "auto" or "original"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` The type of the input item. Always `input_image`. + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + - `file_id: optional string` The ID of the file to be sent to the model. @@ -31332,7 +29225,11 @@ Cancel a response 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. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` A file input to the model. @@ -31344,9 +29241,15 @@ Cancel a response The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"auto"` + + - `"low"` + + - `"high"` + - `file_data: optional string` - The content of the file to be sent to the model. + The base64-encoded data of the file to be sent to the model. - `file_id: optional string` @@ -31364,13 +29267,17 @@ Cancel a response 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. - - `type: "custom_tool_call_output"` + - `mode: "explicit"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The breakpoint mode. Always `explicit`. - - `id: optional string` + - `type: "function_call_output"` - The unique ID of the custom tool call output in the OpenAI platform. + The type of the function tool call output. Always `function_call_output`. + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -31396,79 +29303,91 @@ Cancel a response The caller type. Always `program`. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A call to a custom tool created by the model. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `call_id: string` + - `"in_progress"` - An identifier used to map this custom tool call to a tool call output. + - `"completed"` - - `input: string` + - `"incomplete"` - The input for the custom tool call generated by the model. + - `agent_message: object { author, content, recipient, 3 more }` - - `name: string` + A message routed between agents. - The name of the custom tool being called. + - `author: string` - - `type: "custom_tool_call"` + The sending agent identity. - The type of the custom tool call. Always `custom_tool_call`. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `id: optional string` + Plaintext, image, or encrypted content sent between agents. - The unique ID of the custom tool call in the OpenAI platform. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text input to the model. - The canonical name of the agent that produced this item. + - `type: "input_text"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the input item. Always `input_text`. - The execution context that produced this tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `direct: object { type }` + 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. - - `program: object { caller_id, type }` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `caller_id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The call ID of the program item that produced this tool call. + - `type: "input_image"` - - `type: "program"` + The type of the input item. Always `input_image`. - - `namespace: optional string` + - `detail: optional "low" or "high" or "auto" or "original"` - The namespace of the custom tool being called. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `compaction_trigger: object { type, agent }` + - `file_id: optional string` - Compacts the current context. Must be the final input item. + The ID of the file to be sent to the model. - - `type: "compaction_trigger"` + - `image_url: optional string` - The type of the item. Always `compaction_trigger`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent: optional object { agent_name }` + - `prompt_cache_breakpoint: optional object { mode }` - The agent that produced this item. + 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. - - `agent_name: string` + - `encrypted_content: object { encrypted_content, type }` - The canonical name of the agent that produced this item. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `item_reference: object { id, agent, type }` + - `encrypted_content: string` - An internal identifier for an item to reference. + Opaque encrypted content. - - `id: string` + - `type: "encrypted_content"` - The ID of the item to reference. + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The item type. Always `agent_message`. + + - `id: optional string` + + The unique ID of this agent message item. - `agent: optional object { agent_name }` @@ -31478,33 +29397,39 @@ Cancel a response The canonical name of the agent that produced this item. - - `type: optional "item_reference"` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - The type of item to reference. Always `item_reference`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"item_reference"` + The multi-agent action that was executed. - - `program: object { id, call_id, code, 3 more }` + - `"spawn_agent"` - - `id: string` + - `"interrupt_agent"` - The unique ID of this program item. + - `"list_agents"` - - `call_id: string` + - `"send_message"` - The stable call ID of the program item. + - `"followup_task"` - - `code: string` + - `"wait_agent"` - The JavaScript source executed by programmatic tool calling. + - `arguments: string` - - `fingerprint: string` + The action arguments as a JSON string. - Opaque program replay fingerprint that must be round-tripped. + - `call_id: string` - - `type: "program"` + The unique ID linking this call to its output. - The item type. Always `program`. + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. + + - `id: optional string` + + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -31514,1060 +29439,1221 @@ Cancel a response The canonical name of the agent that produced this item. - - `program_output: object { id, call_id, result, 3 more }` - - - `id: string` - - The unique ID of this program output item. + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - `call_id: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The call ID of the program item. + The multi-agent action that produced this result. - - `result: string` + - `"spawn_agent"` - The result produced by the program item. + - `"interrupt_agent"` - - `status: "completed" or "incomplete"` + - `"list_agents"` - The terminal status of the program output. + - `"send_message"` - - `"completed"` + - `"followup_task"` - - `"incomplete"` + - `"wait_agent"` - - `type: "program_output"` + - `call_id: string` - The item type. Always `program_output`. + The unique ID of the multi-agent call. - - `agent: optional object { agent_name }` + - `output: array of object { text, type, annotations }` - The agent that produced this item. + Text output returned by the multi-agent action. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + The text content. - - `metadata: map[string]` + - `type: "output_text"` - 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. + The content type. Always `output_text`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + Citations associated with the text content. - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. + - `union_member_0: array of object { file_id, filename, index, type }` - - `"gpt-5.6-sol"` + - `file_id: string` - - `"gpt-5.6-terra"` + The ID of the file. - - `"gpt-5.6-luna"` + - `filename: string` - - `"gpt-5.4"` + The filename of the file cited. - - `"gpt-5.4-mini"` + - `index: number` - - `"gpt-5.4-nano"` + The index of the file in the list of files. - - `"gpt-5.4-mini-2026-03-17"` + - `type: "file_citation"` - - `"gpt-5.4-nano-2026-03-17"` + The citation type. Always `file_citation`. - - `"gpt-5.3-chat-latest"` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - `"gpt-5.2"` + - `end_index: number` - - `"gpt-5.2-2025-12-11"` + The index of the last character of the citation in the message. - - `"gpt-5.2-chat-latest"` + - `start_index: number` - - `"gpt-5.2-pro"` + The index of the first character of the citation in the message. - - `"gpt-5.2-pro-2025-12-11"` + - `title: string` - - `"gpt-5.1"` + The title of the cited resource. - - `"gpt-5.1-2025-11-13"` + - `type: "url_citation"` - - `"gpt-5.1-codex"` + The citation type. Always `url_citation`. - - `"gpt-5.1-mini"` + - `url: string` - - `"gpt-5.1-chat-latest"` + The URL of the cited resource. - - `"gpt-5"` + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `"gpt-5-mini"` + - `container_id: string` - - `"gpt-5-nano"` + The ID of the container. - - `"gpt-5-2025-08-07"` + - `end_index: number` - - `"gpt-5-mini-2025-08-07"` + The index of the last character of the citation in the message. - - `"gpt-5-nano-2025-08-07"` + - `file_id: string` - - `"gpt-5-chat-latest"` + The ID of the container file. - - `"gpt-4.1"` + - `filename: string` - - `"gpt-4.1-mini"` + The filename of the container file cited. - - `"gpt-4.1-nano"` + - `start_index: number` - - `"gpt-4.1-2025-04-14"` + The index of the first character of the citation in the message. - - `"gpt-4.1-mini-2025-04-14"` + - `type: "container_file_citation"` - - `"gpt-4.1-nano-2025-04-14"` + The citation type. Always `container_file_citation`. - - `"o4-mini"` + - `type: "multi_agent_call_output"` - - `"o4-mini-2025-04-16"` + The item type. Always `multi_agent_call_output`. - - `"o3"` + - `id: optional string` - - `"o3-2025-04-16"` + The unique ID of this multi-agent call output. - - `"o3-mini"` + - `agent: optional object { agent_name }` - - `"o3-mini-2025-01-31"` + The agent that produced this item. - - `"o1"` + - `agent_name: string` - - `"o1-2024-12-17"` + The canonical name of the agent that produced this item. - - `"o1-preview"` + - `tool_search_call: object { arguments, type, id, 4 more }` - - `"o1-preview-2024-09-12"` + - `arguments: unknown` - - `"o1-mini"` + The arguments supplied to the tool search call. - - `"o1-mini-2024-09-12"` + - `type: "tool_search_call"` - - `"gpt-4o"` + The item type. Always `tool_search_call`. - - `"gpt-4o-2024-11-20"` + - `id: optional string` - - `"gpt-4o-2024-08-06"` + The unique ID of this tool search call. - - `"gpt-4o-2024-05-13"` + - `agent: optional object { agent_name }` - - `"gpt-4o-audio-preview"` + The agent that produced this item. - - `"gpt-4o-audio-preview-2024-10-01"` + - `agent_name: string` - - `"gpt-4o-audio-preview-2024-12-17"` + The canonical name of the agent that produced this item. - - `"gpt-4o-audio-preview-2025-06-03"` + - `call_id: optional string` - - `"gpt-4o-mini-audio-preview"` + The unique ID of the tool search call generated by the model. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `execution: optional "server" or "client"` - - `"gpt-4o-search-preview"` + Whether tool search was executed by the server or by the client. - - `"gpt-4o-mini-search-preview"` + - `"server"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"client"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"chatgpt-4o-latest"` + The status of the tool search call. - - `"codex-mini-latest"` + - `"in_progress"` - - `"gpt-4o-mini"` + - `"completed"` - - `"gpt-4o-mini-2024-07-18"` + - `"incomplete"` - - `"gpt-4-turbo"` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `"gpt-4-turbo-2024-04-09"` + - `tools: array of BetaTool` - - `"gpt-4-0125-preview"` + The loaded tool definitions returned by the tool search output. - - `"gpt-4-turbo-preview"` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `"gpt-4-1106-preview"` + 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). - - `"gpt-4-vision-preview"` + - `name: string` - - `"gpt-4"` + The name of the function to call. - - `"gpt-4-0314"` + - `parameters: map[unknown]` - - `"gpt-4-0613"` + A JSON schema object describing the parameters of the function. - - `"gpt-4-32k"` + - `strict: boolean` - - `"gpt-4-32k-0314"` + Whether strict parameter validation is enforced for this function tool. - - `"gpt-4-32k-0613"` + - `type: "function"` - - `"gpt-3.5-turbo"` + The type of the function tool. Always `function`. - - `"gpt-3.5-turbo-16k"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-3.5-turbo-0301"` + The tool invocation context(s). - - `"gpt-3.5-turbo-0613"` + - `"direct"` - - `"gpt-3.5-turbo-1106"` + - `"programmatic"` - - `"gpt-3.5-turbo-0125"` + - `defer_loading: optional boolean` - - `"gpt-3.5-turbo-16k-0613"` + Whether this function is deferred and loaded via tool search. - - `"o1-pro"` + - `description: optional string` - - `"o1-pro-2025-03-19"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"o3-pro"` + - `output_schema: optional map[unknown]` - - `"o3-pro-2025-06-10"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"o3-deep-research"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"o3-deep-research-2025-06-26"` + 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). - - `"o4-mini-deep-research"` + - `type: "file_search"` - - `"o4-mini-deep-research-2025-06-26"` + The type of the file search tool. Always `file_search`. - - `"computer-use-preview"` + - `vector_store_ids: array of string` - - `"computer-use-preview-2025-03-11"` + The IDs of the vector stores to search. - - `"gpt-5-codex"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"gpt-5-pro"` + A filter to apply. - - `"gpt-5-pro-2025-10-06"` + - `Comparison Filter: object { key, type, value }` - - `"gpt-5.1-codex-max"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `object: "response"` + - `key: string` - The object type of this resource - always set to `response`. + The key to compare against the value. - - `output: array of BetaResponseOutputItem` + - `type: "eq" or "ne" or "gt" or 5 more` - An array of content items generated by the model. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `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 - - `beta_response_output_message: object { id, content, role, 4 more }` + - `"eq"` - An output message from the model. + - `"ne"` - - `id: string` + - `"gt"` - The unique ID of the output message. + - `"gte"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"lt"` - The content of the output message. + - `"lte"` - - `role: "assistant"` + - `"in"` - The role of the output message. Always `assistant`. + - `"nin"` - - `status: "in_progress" or "completed" or "incomplete"` + - `value: string or number or boolean or array of string or number` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: "message"` + - `union_member_0: string` - The type of the output message. Always `message`. + - `union_member_1: number` - - `agent: optional object { agent_name }` + - `union_member_2: boolean` - The agent that produced this item. + - `union_member_3: array of string or number` - - `phase: optional "commentary"` + - `union_member_0: string` - 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. + - `union_member_1: number` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `Compound Filter: object { filters, type }` - 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. + Combine multiple filters using `and` or `or`. - - `id: string` + - `filters: array of object { key, type, value } or unknown` - The unique ID of the file search tool call. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `queries: array of string` + - `Comparison Filter: object { key, type, value }` - The queries used to search for files. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `key: string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The key to compare against the value. - - `type: "file_search_call"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of the file search tool call. Always `file_search_call`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent: optional object { agent_name }` + - `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 - The agent that produced this item. + - `"eq"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"ne"` - The results of the file search tool call. + - `"gt"` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `"gte"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"lt"` - - `arguments: string` + - `"lte"` - A JSON string of the arguments to pass to the function. + - `"in"` - - `call_id: string` + - `"nin"` - The unique ID of the function tool call generated by the model. + - `value: string or number or boolean or array of string or number` - - `name: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The name of the function to run. + - `union_member_0: string` - - `type: "function_call"` + - `union_member_1: number` - The type of the function tool call. Always `function_call`. + - `union_member_2: boolean` - - `id: optional string` + - `union_member_3: array of string or number` - The unique ID of the function tool call. + - `union_member_0: string` - - `agent: optional object { agent_name }` + - `union_member_1: number` - The agent that produced this item. + - `union_member_1: unknown` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "and" or "or"` - The execution context that produced this tool call. + Type of operation: `and` or `or`. - - `namespace: optional string` + - `"and"` - The namespace of the function to run. + - `"or"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `max_num_results: optional number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `id: string` + Ranking options for search. - The unique ID of the function call tool output. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `call_id: string` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The unique ID of the function tool call generated by the model. + - `embedding_weight: number` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The weight of the embedding in the reciprocal ranking fusion. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `text_weight: number` - - `string output: string` + The weight of the text in the reciprocal ranking fusion. - A string of the output of the function call. + - `ranker: optional "auto" or "default-2024-11-15"` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The ranker to use for the file search. - Text, image, or file output of the function call. + - `"auto"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"default-2024-11-15"` - A text input to the model. + - `score_threshold: optional number` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + 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. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `beta_computer_tool: object { type }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A file input to the model. + - `type: "computer"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the computer tool. Always `computer`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `"in_progress"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"completed"` + - `display_height: number` - - `"incomplete"` + The height of the computer display. - - `type: "function_call_output"` + - `display_width: number` - The type of the function tool call output. Always `function_call_output`. + The width of the computer display. - - `agent: optional object { agent_name }` + - `environment: "windows" or "mac" or "linux" or 2 more` - The agent that produced this item. + The type of computer environment to control. - - `agent_name: string` + - `"windows"` - The canonical name of the agent that produced this item. + - `"mac"` - - `caller: optional object { type } or object { caller_id, type }` + - `"linux"` - The execution context that produced this tool call. + - `"ubuntu"` - - `direct: object { type }` + - `"browser"` - - `program: object { caller_id, type }` + - `type: "computer_use_preview"` - - `caller_id: string` + The type of the computer use tool. Always `computer_use_preview`. - The call ID of the program item that produced this tool call. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `type: "program"` + 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). - The caller type. Always `program`. + - `type: "web_search" or "web_search_2025_08_26"` - - `created_by: optional string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The identifier of the actor that created the item. + - `"web_search"` - - `agent_message: object { id, author, content, 3 more }` + - `"web_search_2025_08_26"` - - `id: string` + - `filters: optional object { allowed_domains }` - The unique ID of the agent message. + Filters for the search. - - `author: string` + - `allowed_domains: optional array of string` - The sending agent identity. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Encrypted content sent between agents. + - `search_context_size: optional "low" or "medium" or "high"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + 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. - A text input to the model. + - `"low"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"medium"` - A text output from the model. + - `"high"` - - `text: object { text, type }` + - `user_location: optional object { city, country, region, 2 more }` - A text content. + The approximate location of the user. - - `text: string` + - `city: optional string` - - `type: "text"` + Free text input for the city of the user, e.g. `San Francisco`. - - `summary_text: object { text, type }` + - `country: optional string` - A summary text from the model. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `text: string` + - `region: optional string` - A summary of the reasoning output from the model so far. + Free text input for the region of the user, e.g. `California`. - - `type: "summary_text"` + - `timezone: optional string` - The type of the object. Always `summary_text`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `reasoning_text: object { text, type }` + - `type: optional "approximate"` - Reasoning text from the model. + The type of location approximation. Always `approximate`. - - `text: string` + - `"approximate"` - The reasoning text from the model. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `type: "reasoning_text"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The type of the reasoning text. Always `reasoning_text`. + - `server_label: string` - - `beta_response_output_refusal: object { refusal, type }` + A label for this MCP server, used to identify it in tool calls. - A refusal from the model. + - `type: "mcp"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The type of the MCP tool. Always `mcp`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + The tool invocation context(s). - A screenshot of a computer. + - `"direct"` - - `detail: "low" or "high" or "auto" or "original"` + - `"programmatic"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"low"` + List of allowed tool names or a filter object. - - `"high"` + - `MCP allowed tools: array of string` - - `"auto"` + A string array of allowed tool names - - `"original"` + - `MCP tool filter: object { read_only, tool_names }` - - `file_id: string` + A filter object to specify which tools are allowed. - The identifier of an uploaded file that contains the screenshot. + - `read_only: optional boolean` - - `image_url: string` + 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. - The URL of the screenshot image. + - `tool_names: optional array of string` - - `type: "computer_screenshot"` + List of allowed tool names. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `authorization: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + 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. - 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. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `mode: "explicit"` + 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). - The breakpoint mode. Always `explicit`. + Currently supported `connector_id` values are: - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - 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` - A file input to the model. + - `"connector_dropbox"` - - `encrypted_content: object { encrypted_content, type }` + - `"connector_gmail"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"connector_googlecalendar"` - - `encrypted_content: string` + - `"connector_googledrive"` - Opaque encrypted content. + - `"connector_microsoftteams"` - - `type: "encrypted_content"` + - `"connector_outlookcalendar"` - The type of the input item. Always `encrypted_content`. + - `"connector_outlookemail"` - - `recipient: string` + - `"connector_sharepoint"` - The destination agent identity. + - `defer_loading: optional boolean` - - `type: "agent_message"` + Whether this MCP tool is deferred and discovered via tool search. - The type of the item. Always `agent_message`. + - `headers: optional map[string]` - - `agent: optional object { agent_name }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The agent that produced this item. + - `require_approval: optional object { always, never } or "always" or "never"` - - `agent_name: string` + Specify which of the MCP server's tools require approval. - The canonical name of the agent that produced this item. + - `MCP tool approval filter: object { always, never }` - - `multi_agent_call: object { id, action, arguments, 3 more }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the multi-agent call item. + A filter object to specify which tools are allowed. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `read_only: optional boolean` - The multi-agent action to execute. + 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. - - `"spawn_agent"` + - `tool_names: optional array of string` - - `"interrupt_agent"` + List of allowed tool names. - - `"list_agents"` + - `never: optional object { read_only, tool_names }` - - `"send_message"` + A filter object to specify which tools are allowed. - - `"followup_task"` + - `read_only: optional boolean` - - `"wait_agent"` + 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. - - `arguments: string` + - `tool_names: optional array of string` - The JSON string of arguments generated for the action. + List of allowed tool names. - - `call_id: string` + - `MCP tool approval setting: "always" or "never"` - The unique ID linking this call to its output. + 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. - - `type: "multi_agent_call"` + - `"always"` - The type of the multi-agent call. Always `multi_agent_call`. + - `"never"` - - `agent: optional object { agent_name }` + - `server_description: optional string` - The agent that produced this item. + Optional description of the MCP server, used to provide more context. - - `agent_name: string` + - `server_url: optional string` - The canonical name of the agent that produced this item. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `tunnel_id: optional string` - - `id: string` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The unique ID of the multi-agent call output item. + - `code_interpreter: object { container, type, allowed_callers }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + A tool that runs Python code to help generate a response to a prompt. - The multi-agent action that produced this result. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + - `union_member_0: string` - - `"list_agents"` + The container ID. - - `"send_message"` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `"followup_task"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"wait_agent"` + - `type: "auto"` - - `call_id: string` + Always `auto`. - The unique ID of the multi-agent call. + - `file_ids: optional array of string` - - `output: array of BetaResponseOutputText` + An optional list of uploaded files to make available to your code. - Text output returned by the multi-agent action. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The memory limit for the code interpreter container. - The annotations of the text output. + - `"1g"` - - `text: string` + - `"4g"` - The text output from the model. + - `"16g"` - - `type: "output_text"` + - `"64g"` - The type of the output text. Always `output_text`. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Network access policy for the container. - - `type: "multi_agent_call_output"` + - `beta_container_network_policy_disabled: object { type }` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `type: "disabled"` - - `agent: optional object { agent_name }` + Disable outbound network access. Always `disabled`. - The agent that produced this item. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `agent_name: string` + - `allowed_domains: array of string` - The canonical name of the agent that produced this item. + A list of allowed domains when type is `allowlist`. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `type: "allowlist"` - 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. + Allow outbound network access only to specified domains. Always `allowlist`. - - `id: string` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The unique ID of the web search tool call. + Optional domain-scoped secrets for allowlisted domains. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `domain: string` - 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). + The domain associated with the secret. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `name: string` - The status of the web search tool call. + The name of the secret to inject for the domain. - - `type: "web_search_call"` + - `value: string` - The type of the web search tool call. Always `web_search_call`. + The secret value to inject for the domain. - - `agent: optional object { agent_name }` + - `type: "code_interpreter"` - The agent that produced this item. + The type of the code interpreter tool. Always `code_interpreter`. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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. + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique ID of the computer call. + - `"programmatic"` - - `call_id: string` + - `programmatic_tool_calling: object { type }` - An identifier used when responding to the tool call with output. + - `image_generation: object { type, action, background, 9 more }` - - `pending_safety_checks: array of object { id, code, message }` + A tool that generates images using the GPT image models. - The pending safety checks for the computer call. + - `type: "image_generation"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the image generation tool. Always `image_generation`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `action: optional "generate" or "edit" or "auto"` - - `type: "computer_call"` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the computer call. Always `computer_call`. + - `"generate"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `"edit"` - A click action. + - `"auto"` - - `actions: optional array of BetaComputerAction` + - `background: optional "transparent" or "opaque" or "auto"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + 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. - - `agent: optional object { agent_name }` + `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. - The agent that produced this item. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `"transparent"` - - `id: string` + - `"opaque"` - The unique ID of the computer call tool output. + - `"auto"` - - `call_id: string` + - `input_fidelity: optional "high" or "low"` - The ID of the computer tool call that produced the output. + 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`. - - `output: object { type, file_id, image_url }` + - `"high"` - A computer screenshot image used with the computer use tool. + - `"low"` - - `type: "computer_screenshot"` + - `input_image_mask: optional object { file_id, image_url }` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - `file_id: optional string` - The identifier of an uploaded file that contains the screenshot. + File ID for the mask image. - `image_url: optional string` - The URL of the screenshot image. + Base64-encoded mask image. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The image generation model to use. Default: `gpt-image-1`. - - `"completed"` + - `"gpt-image-1"` - - `"incomplete"` + - `"gpt-image-1-mini"` - - `"failed"` + - `"gpt-image-2"` - - `"in_progress"` + - `"gpt-image-2-2026-04-21"` - - `type: "computer_call_output"` + - `"gpt-image-1.5"` - The type of the computer tool call output. Always `computer_call_output`. + - `"chatgpt-image-latest"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `moderation: optional "auto" or "low"` - The safety checks reported by the API that have been acknowledged by the - developer. + Moderation level for the generated image. Default: `auto`. - - `id: string` + - `"auto"` - The ID of the pending safety check. + - `"low"` - - `code: optional string` + - `output_compression: optional number` - The type of the pending safety check. + Compression level for the output image. Default: 100. - - `message: optional string` + - `output_format: optional "png" or "webp" or "jpeg"` - Details about the pending safety check. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `agent: optional object { agent_name }` + - `"png"` - The agent that produced this item. + - `"webp"` - - `agent_name: string` + - `"jpeg"` - The canonical name of the agent that produced this item. + - `partial_images: optional number` - - `created_by: optional string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The identifier of the actor that created the item. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - 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). + - `"low"` - - `id: string` + - `"medium"` - The unique identifier of the reasoning content. + - `"high"` - - `summary: array of object { text, type }` + - `"auto"` - Reasoning summary content. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "reasoning"` + 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`. - The type of the object. Always `reasoning`. + - `"1024x1024"` - - `agent: optional object { agent_name }` + - `"1024x1536"` - The agent that produced this item. + - `"1536x1024"` - - `content: optional array of object { text, type }` + - `"auto"` - Reasoning text content. + - `local_shell: object { type }` - - `encrypted_content: optional string` + A tool that allows the model to execute shell commands in a local environment. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A tool that allows the model to execute shell commands. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "shell"` - - `program: object { id, call_id, code, 3 more }` + The type of the shell tool. Always `shell`. - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the program item. + The tool invocation context(s). - - `call_id: string` + - `"direct"` - The stable call ID of the program item. + - `"programmatic"` - - `code: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The JavaScript source executed by programmatic tool calling. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `fingerprint: string` + - `type: "container_auto"` - Opaque program replay fingerprint that must be round-tripped. + Automatically creates a container for this request - - `type: "program"` + - `file_ids: optional array of string` - The type of the item. Always `program`. + An optional list of uploaded files to make available to your code. - - `agent: optional object { agent_name }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The agent that produced this item. + The memory limit for the container. - - `agent_name: string` + - `"1g"` - The canonical name of the agent that produced this item. + - `"4g"` - - `program_output: object { id, call_id, result, 3 more }` + - `"16g"` - - `id: string` + - `"64g"` - The unique ID of the program output item. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `call_id: string` + Network access policy for the container. - The call ID of the program item. + - `beta_container_network_policy_disabled: object { type }` - - `result: string` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The result produced by the program item. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `status: "completed" or "incomplete"` + An optional list of skills referenced by id or inline data. - The terminal status of the program output item. + - `beta_skill_reference: object { skill_id, type, version }` - - `"completed"` + - `skill_id: string` - - `"incomplete"` + The ID of the referenced skill. - - `type: "program_output"` + - `type: "skill_reference"` - The type of the item. Always `program_output`. + References a skill created with the /v1/skills endpoint. - - `agent: optional object { agent_name }` + - `version: optional string` - The agent that produced this item. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `agent_name: string` + - `beta_inline_skill: object { description, name, source, type }` - The canonical name of the agent that produced this item. + - `description: string` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + The description of the skill. - - `id: string` + - `name: string` - The unique ID of the tool search call item. + The name of the skill. - - `arguments: unknown` + - `source: object { data, media_type, type }` - Arguments used for the tool search call. + Inline skill payload - - `call_id: string` + - `data: string` - The unique ID of the tool search call generated by the model. + Base64-encoded skill zip bundle. - - `execution: "server" or "client"` + - `media_type: "application/zip"` - Whether tool search was executed by the server or by the client. + The media type of the inline skill payload. Must be `application/zip`. - - `"server"` + - `type: "base64"` - - `"client"` + The type of the inline skill source. Must be `base64`. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "inline"` - The status of the tool search call item that was recorded. + Defines an inline skill for this request. - - `"in_progress"` + - `beta_local_environment: object { type, skills }` - - `"completed"` + - `type: "local"` - - `"incomplete"` + Use a local computer environment. - - `type: "tool_search_call"` + - `skills: optional array of BetaLocalSkill` - The type of the item. Always `tool_search_call`. + An optional list of skills. - - `agent: optional object { agent_name }` + - `description: string` - The agent that produced this item. + The description of the skill. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the skill. - - `created_by: optional string` + - `path: string` - The identifier of the actor that created the item. + The path to the directory containing the skill. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `beta_container_reference: object { container_id, type }` - - `id: string` + - `container_id: string` - The unique ID of the tool search output item. + The ID of the referenced container. - - `call_id: string` + - `type: "container_reference"` - The unique ID of the tool search call generated by the model. + References a container created with the /v1/containers endpoint - - `execution: "server" or "client"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Whether tool search was executed by the server or by the client. + 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) - - `"server"` + - `name: string` - - `"client"` + The name of the custom tool, used to identify it in tool calls. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "custom"` - The status of the tool search output item that was recorded. + The type of the custom tool. Always `custom`. - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `tools: array of BetaTool` + - `"programmatic"` - The loaded tool definitions returned by tool search. + - `defer_loading: optional boolean` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + Whether this tool should be deferred and discovered via tool search. - 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). + - `description: optional string` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + Optional description of the custom tool, used to provide more context. - 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). + - `format: optional object { type } or object { definition, syntax, type }` - - `beta_computer_tool: object { type }` + The input format for the custom tool. Default is unconstrained text. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `text: object { type }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + Unconstrained free-form text. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `grammar: object { definition, syntax, type }` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + A grammar defined by the user. - 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). + - `definition: string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The grammar definition. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `syntax: "lark" or "regex"` - - `code_interpreter: object { container, type, allowed_callers }` + The syntax of the grammar definition. One of `lark` or `regex`. - A tool that runs Python code to help generate a response to a prompt. + - `"lark"` - - `programmatic_tool_calling: object { type }` + - `"regex"` - - `image_generation: object { type, action, background, 9 more }` + - `type: "grammar"` - A tool that generates images using the GPT image models. + Grammar format. Always `grammar`. - - `local_shell: object { type }` + - `beta_namespace_tool: object { description, name, tools, type }` - A tool that allows the model to execute shell commands in a local environment. + Groups function/custom tools under a shared namespace. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `description: string` - A tool that allows the model to execute shell commands. + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + + The function/custom tools available inside this namespace. + + - `function: object { name, type, allowed_callers, 5 more }` + + - `name: string` + + - `type: "function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: optional unknown` + + - `strict: optional boolean` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` 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) - - `beta_namespace_tool: object { description, name, tools, type }` + - `name: string` - Groups function/custom tools under a shared namespace. + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. - `beta_tool_search_tool: object { type, description, execution, parameters }` Hosted or BYOT tool search configuration for deferred tools. + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `beta_apply_patch_tool: object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. + + - `id: optional string` + + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -32577,39 +30663,37 @@ Cancel a response The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `call_id: optional string` - - `additional_tools: object { id, role, tools, 2 more }` + The unique ID of the tool search call generated by the model. - - `id: string` + - `execution: optional "server" or "client"` - The unique ID of the additional tools item. + Whether tool search was executed by the server or by the client. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"server"` - The role that provided the additional tools. + - `"client"` - - `"unknown"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"user"` + The status of the tool search output. - - `"assistant"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"critic"` + - `"incomplete"` - - `"discriminator"` + - `additional_tools: object { role, tools, type, 2 more }` - - `"developer"` + - `role: "developer"` - - `"tool"` + The role that provided the additional tools. Only `developer` is supported. - `tools: array of BetaTool` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -32677,7 +30761,11 @@ Cancel a response - `type: "additional_tools"` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -32687,22 +30775,85 @@ Cancel a response The canonical name of the agent that produced this item. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: string` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `type: "compaction"` The type of the item. Always `compaction`. + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -32711,10 +30862,6 @@ Cancel a response The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -32772,10 +30919,44 @@ Cancel a response The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + - `type: "code_interpreter_call"` The type of the code interpreter tool call. Always `code_interpreter_call`. @@ -32784,6 +30965,10 @@ Cancel a response The agent that produced this item. + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `local_shell_call: object { id, action, call_id, 3 more }` A tool call to run a command on the local shell. @@ -32880,13 +31065,9 @@ Cancel a response - `"incomplete"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: string` + - `shell_call: object { action, call_id, type, 5 more }` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - `action: object { commands, max_output_length, timeout_ms }` @@ -32894,54 +31075,28 @@ Cancel a response - `commands: array of string` - - `max_output_length: number` + Ordered shell commands for the execution environment to run. - Optional maximum number of characters to return from each command. + - `max_output_length: optional number` - - `timeout_ms: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Optional timeout in milliseconds for the commands. + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `beta_response_local_environment: object { type }` - - Represents the use of a local environment to perform shell actions. - - - `type: "local"` - - The environment type. Always `local`. - - - `beta_response_container_reference: object { container_id, type }` - - Represents a container created with /v1/containers. - - - `container_id: string` - - - `type: "container_reference"` - - The environment type. Always `container_reference`. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: "shell_call"` The type of the item. Always `shell_call`. + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -32964,33 +31119,41 @@ Cancel a response - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The ID of the entity that created this tool call. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + The environment to execute the shell commands in. - The output of a shell tool call that was emitted. + - `beta_local_environment: object { type, skills }` - - `id: string` + - `beta_container_reference: object { container_id, type }` - The unique ID of the shell call output. Populated when this item is returned via API. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `call_id: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call generated by the model. + - `"in_progress"` - - `max_output_length: number` + - `"completed"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"incomplete"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `shell_call_output: object { call_id, output, type, 5 more }` - An array of shell call output contents + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: object { type } or object { exit_code, type }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `timeout: object { type }` @@ -33002,7 +31165,7 @@ Cancel a response - `exit_code: number` - Exit code from the shell process. + The exit code returned by the shell process. - `type: "exit"` @@ -33010,29 +31173,19 @@ Cancel a response - `stderr: string` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: string` - The standard output that was captured. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` + Captured stdout output for the shell call. - - `"completed"` + - `type: "shell_call_output"` - - `"incomplete"` + The type of the item. Always `shell_call_output`. - - `type: "shell_call_output"` + - `id: optional string` - The type of the shell call output. Always `shell_call_output`. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -33056,17 +31209,25 @@ Cancel a response - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The identifier of the actor that created the item. + - `max_output_length: optional number` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + The maximum number of UTF-8 characters captured for this shell call's combined output. - A tool call that applies file diffs by creating, deleting, or updating files. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the shell call output. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` @@ -33074,51 +31235,51 @@ Cancel a response - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `create_file: object { diff, path, type }` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply when creating the file. - `path: string` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: "create_file"` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `delete_file: object { path, type }` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: string` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: "delete_file"` - Delete the specified file. + The operation type. Always `delete_file`. - `update_file: object { diff, path, type }` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply to the existing file. - `path: string` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: "update_file"` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `status: "in_progress" or "completed"` @@ -33132,6 +31293,10 @@ Cancel a response The type of the item. Always `apply_patch_call`. + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -33154,17 +31319,11 @@ Cancel a response - `type: "program"` - - `created_by: optional string` - - The ID of the entity that created this tool call. - - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - The output emitted by an apply patch tool call. + The caller type. Always `program`. - - `id: string` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. - `call_id: string` @@ -33182,6 +31341,10 @@ Cancel a response The type of the item. Always `apply_patch_call_output`. + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -33204,72 +31367,11 @@ Cancel a response - `type: "program"` - - `created_by: optional string` - - The ID of the entity that created this tool call output. - - - `output: optional string` - - Optional textual output returned by the apply patch tool. - - - `mcp_call: object { id, arguments, name, 7 more }` - - An invocation of a tool on an MCP server. - - - `id: string` - - The unique ID of the tool call. - - - `arguments: string` - - A JSON string of the arguments passed to the tool. - - - `name: string` - - The name of the tool that was run. - - - `server_label: string` - - The label of the MCP server running the tool. - - - `type: "mcp_call"` - - The type of the item. Always `mcp_call`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. + The caller type. Always `program`. - `output: optional string` - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `mcp_list_tools: object { id, server_label, tools, 3 more }` @@ -33351,14 +31453,10 @@ Cancel a response The canonical name of the agent that produced this item. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` A response to an MCP approval request. - - `id: string` - - The unique ID of the approval response - - `approval_request_id: string` The ID of the approval request being answered. @@ -33371,6 +31469,10 @@ Cancel a response The type of the item. Always `mcp_approval_response`. + - `id: optional string` + + The unique ID of the approval response + - `agent: optional object { agent_name }` The agent that produced this item. @@ -33383,54 +31485,54 @@ Cancel a response Optional reason for the decision. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `mcp_call: object { id, arguments, name, 7 more }` - A call to a custom tool created by the model. + An invocation of a tool on an MCP server. - - `call_id: string` + - `id: string` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the tool call. - - `input: string` + - `arguments: string` - The input for the custom tool call generated by the model. + A JSON string of the arguments passed to the tool. - `name: string` - The name of the custom tool being called. + The name of the tool that was run. - - `type: "custom_tool_call"` + - `server_label: string` - The type of the custom tool call. Always `custom_tool_call`. + The label of the MCP server running the tool. - - `id: optional string` + - `type: "mcp_call"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` The agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `agent_name: string` - The execution context that produced this tool call. + The canonical name of the agent that produced this item. - - `namespace: optional string` + - `approval_request_id: optional string` - The namespace of the custom tool being called. + 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. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `error: optional string` - The output of a custom tool call from your code, being sent back to the model. + The error from the tool call, if any. - - `id: string` + - `output: optional string` - The unique ID of the custom tool call output item. + The output from the tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` @@ -33438,420 +31540,637 @@ Cancel a response - `"incomplete"` - - `created_by: optional string` + - `"calling"` - The identifier of the actor that created the item. + - `"failed"` - - `parallel_tool_calls: boolean` + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - Whether to allow the model to run tool calls in parallel. + The output of a custom tool call from your code, being sent back to the model. - - `temperature: number` + - `call_id: string` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + The call ID, used to map this custom tool call output to a custom tool call. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `beta_tool_choice_options: "none" or "auto" or "required"` + - `string output: string` - Controls which (if any) tool is called by the model. + A string of the output of the custom tool call. - `none` means the model will not call any tool and instead generates a message. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - `auto` means the model can pick between generating a message or calling one or - more tools. + Text, image, or file output of the custom tool call. - `required` means the model must call one or more tools. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"none"` + A text input to the model. - - `"auto"` + - `text: string` - - `"required"` + The text input to the model. - - `beta_tool_choice_allowed: object { mode, tools, type }` + - `type: "input_text"` - Constrains the tools available to the model to a pre-defined set. + The type of the input item. Always `input_text`. - - `mode: "auto" or "required"` + - `prompt_cache_breakpoint: optional object { mode }` - Constrains the tools available to the model to a pre-defined set. + 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. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - `required` requires the model to call one or more of the allowed tools. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"auto"` + - `detail: "low" or "high" or "auto" or "original"` - - `"required"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `tools: array of map[unknown]` + - `type: "input_image"` - A list of tool definitions that the model should be allowed to call. + The type of the input item. Always `input_image`. - For the Responses API, the list of tool definitions might look like: + - `file_id: optional string` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The ID of the file to be sent to the model. - - `type: "allowed_tools"` + - `image_url: optional string` - Allowed tool configuration type. Always `allowed_tools`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `beta_tool_choice_types: object { type }` + - `prompt_cache_breakpoint: optional object { mode }` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + 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. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + A file input to the model. - Allowed values are: + - `type: "input_file"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The type of the input item. Always `input_file`. - - `"file_search"` + - `detail: optional "auto" or "low" or "high"` - - `"web_search_preview"` + 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`. - - `"computer"` + - `file_data: optional string` - - `"computer_use_preview"` + The content of the file to be sent to the model. - - `"computer_use"` + - `file_id: optional string` - - `"web_search_preview_2025_03_11"` + The ID of the file to be sent to the model. - - `"image_generation"` + - `file_url: optional string` - - `"code_interpreter"` + The URL of the file to be sent to the model. - - `beta_tool_choice_function: object { name, type }` + - `filename: optional string` - Use this option to force the model to call a specific function. + The name of the file to be sent to the model. - - `name: string` + - `prompt_cache_breakpoint: optional object { mode }` - The name of the function to call. + 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. - - `type: "function"` + - `type: "custom_tool_call_output"` - For function calling, the type is always `function`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `beta_tool_choice_mcp: object { server_label, type, name }` + - `id: optional string` - Use this option to force the model to call a specific tool on a remote MCP server. + The unique ID of the custom tool call output in the OpenAI platform. - - `server_label: string` + - `agent: optional object { agent_name }` - The label of the MCP server to use. + The agent that produced this item. - - `type: "mcp"` + - `agent_name: string` - For MCP tools, the type is always `mcp`. + The canonical name of the agent that produced this item. - - `name: optional string` + - `caller: optional object { type } or object { caller_id, type }` - The name of the tool to call on the server. + The execution context that produced this tool call. - - `beta_tool_choice_custom: object { name, type }` + - `direct: object { type }` - Use this option to force the model to call a specific custom tool. + - `program: object { caller_id, type }` - - `name: string` + - `caller_id: string` - The name of the custom tool to call. + The call ID of the program item that produced this tool call. - - `type: "custom"` + - `type: "program"` - For custom tool calling, the type is always `custom`. + The caller type. Always `program`. - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `beta_tool_choice_apply_patch: object { type }` + A call to a custom tool created by the model. - Forces the model to call the apply_patch tool when executing a tool call. + - `call_id: string` - - `type: "apply_patch"` + An identifier used to map this custom tool call to a tool call output. - The tool to call. Always `apply_patch`. + - `input: string` - - `beta_tool_choice_shell: object { type }` + The input for the custom tool call generated by the model. - Forces the model to call the shell tool when a tool call is required. + - `name: string` - - `type: "shell"` + The name of the custom tool being called. - The tool to call. Always `shell`. + - `type: "custom_tool_call"` - - `tools: array of BetaTool` + The type of the custom tool call. Always `custom_tool_call`. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `id: optional string` - We support the following categories of tools: + The unique ID of the custom tool call in the OpenAI platform. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `agent: optional object { agent_name }` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The agent that produced this item. - 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). + - `agent_name: string` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The canonical name of the agent that produced this item. - 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). + - `caller: optional object { type } or object { caller_id, type }` - - `beta_computer_tool: object { type }` + The execution context that produced this tool call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `direct: object { type }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `program: object { caller_id, type }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `caller_id: string` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The call ID of the program item that produced this tool call. - 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: "program"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `namespace: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The namespace of the custom tool being called. - - `code_interpreter: object { container, type, allowed_callers }` + - `compaction_trigger: object { type, agent }` - A tool that runs Python code to help generate a response to a prompt. + Compacts the current context. Must be the final input item. - - `programmatic_tool_calling: object { type }` + - `type: "compaction_trigger"` - - `image_generation: object { type, action, background, 9 more }` + The type of the item. Always `compaction_trigger`. - A tool that generates images using the GPT image models. + - `agent: optional object { agent_name }` - - `local_shell: object { type }` + The agent that produced this item. - A tool that allows the model to execute shell commands in a local environment. + - `agent_name: string` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands. + - `item_reference: object { id, agent, type }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + An internal identifier for an item to reference. - 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) + - `id: string` - - `beta_namespace_tool: object { description, name, tools, type }` + The ID of the item to reference. - Groups function/custom tools under a shared namespace. + - `agent: optional object { agent_name }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The agent that produced this item. - Hosted or BYOT tool search configuration for deferred tools. + - `agent_name: string` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The canonical name of the agent that produced this item. - 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: optional "item_reference"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The type of item to reference. Always `item_reference`. - Allows the assistant to create, delete, or update files using unified diffs. + - `"item_reference"` - - `top_p: number` + - `program: object { id, call_id, code, 3 more }` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `id: string` - We generally recommend altering this or `temperature` but not both. + The unique ID of this program item. - - `background: optional boolean` + - `call_id: string` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The stable call ID of the program item. - - `completed_at: optional number` + - `code: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The JavaScript source executed by programmatic tool calling. - - `conversation: optional object { id }` + - `fingerprint: string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` - `id: string` - The unique ID of the conversation that this response was associated with. + The unique ID of this program output item. - - `max_output_tokens: optional number` + - `call_id: string` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The call ID of the program item. - - `max_tool_calls: optional number` + - `result: string` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The result produced by the program item. - - `moderation: optional object { input, output }` + - `status: "completed" or "incomplete"` - Moderation results for the response input and output, if moderated completions were requested. + The terminal status of the program output. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"completed"` - Moderation for the response input. + - `"incomplete"` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `type: "program_output"` - A moderation result produced for the response input or output. + The item type. Always `program_output`. - - `categories: map[boolean]` + - `agent: optional object { agent_name }` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The agent that produced this item. - - `category_applied_input_types: map[array of "text" or "image"]` + - `agent_name: string` - Which modalities of input are reflected by the score for each category. + The canonical name of the agent that produced this item. - - `"text"` + - `metadata: map[string]` - - `"image"` + 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. - - `category_scores: map[number]` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A dictionary of moderation categories to scores. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `flagged: boolean` + Model ID used to generate the response, like `gpt-4o` 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. - A boolean indicating whether the content was flagged by any category. + - `"gpt-5.6-sol"` - - `model: string` + - `"gpt-5.6-terra"` - The moderation model that produced this result. + - `"gpt-5.6-luna"` - - `type: "moderation_result"` + - `"gpt-5.4"` - The object type, which was always `moderation_result` for successful moderation results. + - `"gpt-5.4-mini"` - - `error: object { code, message, type }` + - `"gpt-5.4-nano"` - An error produced while attempting moderation for the response input or output. + - `"gpt-5.4-mini-2026-03-17"` - - `code: string` + - `"gpt-5.4-nano-2026-03-17"` - The error code. + - `"gpt-5.3-chat-latest"` - - `message: string` + - `"gpt-5.2"` - The error message. + - `"gpt-5.2-2025-12-11"` - - `type: "error"` + - `"gpt-5.2-chat-latest"` - The object type, which was always `error` for moderation failures. + - `"gpt-5.2-pro"` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"gpt-5.2-pro-2025-12-11"` - Moderation for the response output. + - `"gpt-5.1"` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `"gpt-5.1-2025-11-13"` - A moderation result produced for the response input or output. + - `"gpt-5.1-codex"` - - `categories: map[boolean]` + - `"gpt-5.1-mini"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"gpt-5.1-chat-latest"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"gpt-5"` - Which modalities of input are reflected by the score for each category. + - `"gpt-5-mini"` - - `"text"` + - `"gpt-5-nano"` - - `"image"` + - `"gpt-5-2025-08-07"` - - `category_scores: map[number]` + - `"gpt-5-mini-2025-08-07"` - A dictionary of moderation categories to scores. + - `"gpt-5-nano-2025-08-07"` - - `flagged: boolean` + - `"gpt-5-chat-latest"` - A boolean indicating whether the content was flagged by any category. + - `"gpt-4.1"` - - `model: string` + - `"gpt-4.1-mini"` - The moderation model that produced this result. + - `"gpt-4.1-nano"` - - `type: "moderation_result"` + - `"gpt-4.1-2025-04-14"` - The object type, which was always `moderation_result` for successful moderation results. + - `"gpt-4.1-mini-2025-04-14"` - - `error: object { code, message, type }` + - `"gpt-4.1-nano-2025-04-14"` - An error produced while attempting moderation for the response input or output. + - `"o4-mini"` - - `code: string` + - `"o4-mini-2025-04-16"` - The error code. + - `"o3"` - - `message: string` + - `"o3-2025-04-16"` - The error message. + - `"o3-mini"` - - `type: "error"` + - `"o3-mini-2025-01-31"` - The object type, which was always `error` for moderation failures. + - `"o1"` - - `previous_response_id: optional string` + - `"o1-2024-12-17"` - 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`. + - `"o1-preview"` - - `prompt: optional object { id, variables, version }` + - `"o1-preview-2024-09-12"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `"o1-mini"` + + - `"o1-mini-2024-09-12"` + + - `"gpt-4o"` + + - `"gpt-4o-2024-11-20"` + + - `"gpt-4o-2024-08-06"` + + - `"gpt-4o-2024-05-13"` + + - `"gpt-4o-audio-preview"` + + - `"gpt-4o-audio-preview-2024-10-01"` + + - `"gpt-4o-audio-preview-2024-12-17"` + + - `"gpt-4o-audio-preview-2025-06-03"` + + - `"gpt-4o-mini-audio-preview"` + + - `"gpt-4o-mini-audio-preview-2024-12-17"` + + - `"gpt-4o-search-preview"` + + - `"gpt-4o-mini-search-preview"` + + - `"gpt-4o-search-preview-2025-03-11"` + + - `"gpt-4o-mini-search-preview-2025-03-11"` + + - `"chatgpt-4o-latest"` + + - `"codex-mini-latest"` + + - `"gpt-4o-mini"` + + - `"gpt-4o-mini-2024-07-18"` + + - `"gpt-4-turbo"` + + - `"gpt-4-turbo-2024-04-09"` + + - `"gpt-4-0125-preview"` + + - `"gpt-4-turbo-preview"` + + - `"gpt-4-1106-preview"` + + - `"gpt-4-vision-preview"` + + - `"gpt-4"` + + - `"gpt-4-0314"` + + - `"gpt-4-0613"` + + - `"gpt-4-32k"` + + - `"gpt-4-32k-0314"` + + - `"gpt-4-32k-0613"` + + - `"gpt-3.5-turbo"` + + - `"gpt-3.5-turbo-16k"` + + - `"gpt-3.5-turbo-0301"` + + - `"gpt-3.5-turbo-0613"` + + - `"gpt-3.5-turbo-1106"` + + - `"gpt-3.5-turbo-0125"` + + - `"gpt-3.5-turbo-16k-0613"` + + - `"o1-pro"` + + - `"o1-pro-2025-03-19"` + + - `"o3-pro"` + + - `"o3-pro-2025-06-10"` + + - `"o3-deep-research"` + + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` + + - `object: "response"` + + The object type of this resource - always set to `response`. + + - `output: array of BetaResponseOutputItem` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. - `id: string` - The unique identifier of the prompt template to use. + The unique ID of the output message. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The content of the output message. - - `union_member_0: string` + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `type: "message"` + + The type of the output message. Always `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `id: optional string` + + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the function call tool output. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the function call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the function call. - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` @@ -33865,712 +32184,14114 @@ Cancel a response A file input to the model. - - `version: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - Optional version of the prompt template. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `prompt_cache_key: optional string` + - `"in_progress"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"completed"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"incomplete"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `type: "function_call_output"` - - `mode: "implicit" or "explicit"` + The type of the function tool call output. Always `function_call_output`. - Whether implicit prompt-cache breakpoints were enabled. + - `agent: optional object { agent_name }` - - `"implicit"` + The agent that produced this item. - - `"explicit"` + - `agent_name: string` - - `ttl: "30m"` + The canonical name of the agent that produced this item. - The minimum lifetime applied to each cache breakpoint. + - `caller: optional object { type } or object { caller_id, type }` - - `"30m"` + The execution context that produced this tool call. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `direct: object { type }` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `program: object { caller_id, type }` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `caller_id: string` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The call ID of the program item that produced this tool call. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: "program"` - - `"in_memory"` + The caller type. Always `program`. - - `"24h"` + - `created_by: optional string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The identifier of the actor that created the item. - **gpt-5 and o-series models only** + - `agent_message: object { id, author, content, 3 more }` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `id: string` - - `context: optional "auto" or "current_turn" or "all_turns"` + The unique ID of the agent message. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `author: string` - - `"auto"` + The sending agent identity. - - `"current_turn"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `"all_turns"` + Encrypted content sent between agents. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + A text input to the model. - - `"none"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `"minimal"` + A text output from the model. - - `"low"` + - `text: object { text, type }` - - `"medium"` + A text content. - - `"high"` + - `text: string` - - `"xhigh"` + - `type: "text"` - - `"max"` + - `summary_text: object { text, type }` - - `generate_summary: optional "auto" or "concise" or "detailed"` + A summary text from the model. - **Deprecated:** use `summary` instead. + - `text: string` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + A summary of the reasoning output from the model so far. - - `"auto"` + - `type: "summary_text"` - - `"concise"` + The type of the object. Always `summary_text`. - - `"detailed"` + - `reasoning_text: object { text, type }` - - `mode: optional string or "standard" or "pro"` + Reasoning text from the model. - Controls the reasoning execution mode for the request. + - `text: string` - When returned on a response, this is the effective execution mode. + The reasoning text from the model. - - `"standard"` + - `type: "reasoning_text"` - - `"pro"` + The type of the reasoning text. Always `reasoning_text`. - - `summary: optional "auto" or "concise" or "detailed"` + - `beta_response_output_refusal: object { refusal, type }` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + A refusal from the model. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` - `"auto"` - - `"concise"` + - `"original"` - - `"detailed"` + - `file_id: string` - - `safety_identifier: optional string` + The identifier of an uploaded file that contains the screenshot. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `image_url: string` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The URL of the screenshot image. - Specifies the processing type used for serving the request. + - `type: "computer_screenshot"` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `prompt_cache_breakpoint: optional object { mode }` - - `"auto"` + 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. - - `"default"` + - `mode: "explicit"` - - `"flex"` + The breakpoint mode. Always `explicit`. - - `"scale"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"priority"` + A file input to the model. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `encrypted_content: object { encrypted_content, type }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"completed"` + - `encrypted_content: string` - - `"failed"` + Opaque encrypted content. - - `"in_progress"` + - `type: "encrypted_content"` - - `"cancelled"` + The type of the input item. Always `encrypted_content`. - - `"queued"` + - `recipient: string` - - `"incomplete"` + The destination agent identity. - - `text: optional object { format, verbosity }` + - `type: "agent_message"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The type of the item. Always `agent_message`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `agent: optional object { agent_name }` - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + The agent that produced this item. - An object specifying the format that the model must output. + - `agent_name: string` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The canonical name of the agent that produced this item. - The default format is `{ "type": "text" }` with no additional options. + - `multi_agent_call: object { id, action, arguments, 3 more }` - **Not recommended for gpt-4o and newer models:** + - `id: string` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The unique ID of the multi-agent call item. - - `text: object { type }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Default response format. Used to generate text responses. + The multi-agent action to execute. - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + - `"spawn_agent"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"interrupt_agent"` - - `name: string` + - `"list_agents"` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `"send_message"` - - `schema: map[unknown]` + - `"followup_task"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"wait_agent"` - - `type: "json_schema"` + - `arguments: string` - The type of response format being defined. Always `json_schema`. + The JSON string of arguments generated for the action. - - `description: optional string` + - `call_id: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The unique ID linking this call to its output. - - `strict: optional boolean` + - `type: "multi_agent_call"` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The type of the multi-agent call. Always `multi_agent_call`. - - `json_object: object { type }` + - `agent: optional object { agent_name }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The agent that produced this item. - - `verbosity: optional "low" or "medium" or "high"` + - `agent_name: string` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The canonical name of the agent that produced this item. - - `"low"` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - - `"medium"` + - `id: string` - - `"high"` + The unique ID of the multi-agent call output item. - - `top_logprobs: optional number` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The multi-agent action that produced this result. - - `truncation: optional "auto" or "disabled"` + - `"spawn_agent"` - The truncation strategy to use for the model response. + - `"interrupt_agent"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"list_agents"` - - `"auto"` + - `"send_message"` - - `"disabled"` + - `"followup_task"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `"wait_agent"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `call_id: string` - - `input_tokens: number` + The unique ID of the multi-agent call. - The number of input tokens. + - `output: array of BetaResponseOutputText` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + Text output returned by the multi-agent action. - A detailed breakdown of the input tokens. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `cache_write_tokens: number` + The annotations of the text output. - The number of input tokens that were written to the cache. + - `text: string` - - `cached_tokens: number` + The text output from the model. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `type: "output_text"` - - `output_tokens: number` + The type of the output text. Always `output_text`. - The number of output tokens. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `output_tokens_details: object { reasoning_tokens }` + - `type: "multi_agent_call_output"` - A detailed breakdown of the output tokens. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `reasoning_tokens: number` + - `agent: optional object { agent_name }` - The number of reasoning tokens. + The agent that produced this item. - - `total_tokens: number` + - `agent_name: string` - The total number of tokens used. + The canonical name of the agent that produced this item. - - `user: optional string` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + 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. -### Example + - `id: string` -```cli -openai beta:responses cancel \ - --api-key 'My API Key' \ - --response-id resp_677efb5139a88190b512bc3fef8e535d -``` + The unique ID of the web search tool call. -#### Response + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "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" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "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 - }, - "user": "user-1234" -} -``` + 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). -## Compact a response + - `status: "in_progress" or "searching" or "completed" or "failed"` -`$ openai beta:responses compact` + The status of the web search tool call. -**post** `/responses/compact?beta=true` + - `type: "web_search_call"` -Compact a response + The type of the web search tool call. Always `web_search_call`. -### Parameters + - `agent: optional object { agent_name }` -- `--model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + The agent that produced this item. - Body param: 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. + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` -- `--input: optional string or array of BetaResponseInputItem` + 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. - Body param: Text, image, or file inputs to the model, used to generate a response + - `id: string` -- `--instructions: optional string` + The unique ID of the computer call. - Body param: 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. + - `call_id: string` -- `--previous-response-id: optional string` + An identifier used when responding to the tool call with output. - Body param: 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`. + - `pending_safety_checks: array of object { id, code, message }` -- `--prompt-cache-key: optional string` + The pending safety checks for the computer call. - Body param: A key to use when reading from or writing to the prompt cache. + - `status: "in_progress" or "completed" or "incomplete"` -- `--prompt-cache-options: optional object { mode, ttl }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Body param: 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. + - `type: "computer_call"` -- `--prompt-cache-retention: optional "in_memory" or "24h"` + The type of the computer call. Always `computer_call`. - Body param: How long to retain a prompt cache entry created by this request. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` -- `--service-tier: optional "auto" or "default" or "flex" or "priority"` + A click action. - Body param: The service tier to use for this request. + - `actions: optional array of BetaComputerAction` -- `--beta: optional array of "responses_multi_agent=v1"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Header param: Optional beta features to enable for this request. + - `agent: optional object { agent_name }` -### Returns + The agent that produced this item. -- `beta_compacted_response: object { id, created_at, object, 2 more }` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - `id: string` - The unique identifier for the compacted response. + The unique ID of the computer call tool output. - - `created_at: number` + - `call_id: string` - Unix timestamp (in seconds) when the compacted conversation was created. + The ID of the computer tool call that produced the output. - - `object: "response.compaction"` + - `output: object { type, file_id, image_url }` - The object type. Always `response.compaction`. + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + + - `id: string` + + The unique ID of the tool search call item. + + - `arguments: unknown` + + Arguments used for the tool search call. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search call item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search output item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `tools: array of BetaTool` + + The loaded tool definitions returned by tool search. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "tool_search_output"` + + The type of the item. Always `tool_search_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `additional_tools: object { id, role, tools, 2 more }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of BetaTool` + + The additional tool definitions made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + - `max_output_length: number` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: number` + + Optional timeout in milliseconds for the commands. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `beta_response_local_environment: object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + + The output of a shell tool call that was emitted. + + - `id: string` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `max_output_length: number` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents + + - `outcome: object { type } or object { exit_code, type }` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + The standard error output that was captured. + + - `stdout: string` + + The standard output that was captured. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `id: string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `create_file: object { diff, path, type }` + + Instruction describing how to create a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to create. + + - `type: "create_file"` + + Create a new file with the provided diff. + + - `delete_file: object { path, type }` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: string` + + Path of the file to delete. + + - `type: "delete_file"` + + Delete the specified file. + + - `update_file: object { diff, path, type }` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to update. + + - `type: "update_file"` + + Update an existing file with the provided diff. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call output. + + - `output: optional string` + + Optional textual output returned by the apply patch tool. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + + A response to an MCP approval request. + + - `id: string` + + The unique ID of the approval response + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: string` + + The unique ID of the custom tool call output item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: boolean` + + Whether to allow the model to run tool calls in parallel. + + - `temperature: number` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `beta_tool_choice_options: "none" or "auto" or "required"` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `"none"` + + - `"auto"` + + - `"required"` + + - `beta_tool_choice_allowed: object { mode, tools, type }` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: "auto" or "required"` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `beta_tool_choice_types: object { type }` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `beta_tool_choice_function: object { name, type }` + + Use this option to force the model to call a specific function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `beta_tool_choice_mcp: object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `name: optional string` + + The name of the tool to call on the server. + + - `beta_tool_choice_custom: object { name, type }` + + Use this option to force the model to call a specific custom tool. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `BetaSpecificProgrammaticToolCallingParam: object { type }` + + - `beta_tool_choice_apply_patch: object { type }` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: "apply_patch"` + + The tool to call. Always `apply_patch`. + + - `beta_tool_choice_shell: object { type }` + + Forces the model to call the shell tool when a tool call is required. + + - `type: "shell"` + + The tool to call. Always `shell`. + + - `tools: array of BetaTool` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `top_p: number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `background: optional boolean` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: optional number` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: optional object { id }` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: string` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: optional number` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: optional object { input, output }` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response input. + + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `error: object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response output. + + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `error: object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `previous_response_id: optional string` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: optional object { id, variables, version }` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: string` + + The unique identifier of the prompt template to use. + + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `union_member_0: string` + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `version: optional string` + + Optional version of the prompt template. + + - `prompt_cache_key: optional string` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `prompt_cache_options: optional object { mode, ttl }` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: "implicit" or "explicit"` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: "30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: optional "in_memory" or "24h"` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `"in_memory"` + + - `"24h"` + + - `reasoning: optional object { context, effort, generate_summary, 2 more }` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: optional "auto" or "current_turn" or "all_turns"` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` + + - `"current_turn"` + + - `"all_turns"` + + - `effort: optional "none" or "minimal" or "low" or 4 more` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `generate_summary: optional "auto" or "concise" or "detailed"` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `mode: optional string or "standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + + - `summary: optional "auto" or "concise" or "detailed"` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `safety_identifier: optional string` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: optional "completed" or "failed" or "in_progress" or 3 more` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + + - `text: optional object { format, verbosity }` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `text: object { type }` + + Default response format. Used to generate text responses. + + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `schema: map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). + + - `json_object: object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `top_logprobs: optional number` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `truncation: optional "auto" or "disabled"` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: number` + + The number of input tokens. + + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: number` + + The number of input tokens that were written to the cache. + + - `cached_tokens: number` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: number` + + The number of output tokens. + + - `output_tokens_details: object { reasoning_tokens }` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: number` + + The number of reasoning tokens. + + - `total_tokens: number` + + The total number of tokens used. + + - `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + +### Beta Response Apply Patch Tool Call + +- `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `id: string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `create_file: object { diff, path, type }` + + Instruction describing how to create a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to create. + + - `type: "create_file"` + + Create a new file with the provided diff. + + - `delete_file: object { path, type }` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: string` + + Path of the file to delete. + + - `type: "delete_file"` + + Delete the specified file. + + - `update_file: object { diff, path, type }` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to update. + + - `type: "update_file"` + + Update an existing file with the provided diff. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + +### Beta Response Apply Patch Tool Call Output + +- `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call output. + + - `output: optional string` + + Optional textual output returned by the apply patch tool. + +### Beta Response Audio Delta Event + +- `beta_response_audio_delta_event: object { delta, sequence_number, type, agent }` + + Emitted when there is a partial audio response. + + - `delta: string` + + A chunk of Base64 encoded response audio bytes. + + - `sequence_number: number` + + A sequence number for this chunk of the stream response. + + - `type: "response.audio.delta"` + + The type of the event. Always `response.audio.delta`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Audio Done Event + +- `beta_response_audio_done_event: object { sequence_number, type, agent }` + + Emitted when the audio response is complete. + + - `sequence_number: number` + + The sequence number of the delta. + + - `type: "response.audio.done"` + + The type of the event. Always `response.audio.done`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Audio Transcript Delta Event + +- `beta_response_audio_transcript_delta_event: object { delta, sequence_number, type, agent }` + + Emitted when there is a partial transcript of audio. + + - `delta: string` + + The partial transcript of the audio response. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.audio.transcript.delta"` + + The type of the event. Always `response.audio.transcript.delta`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Audio Transcript Done Event + +- `beta_response_audio_transcript_done_event: object { sequence_number, type, agent }` + + Emitted when the full audio transcript is completed. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.audio.transcript.done"` + + The type of the event. Always `response.audio.transcript.done`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Code Delta Event + +- `beta_response_code_interpreter_call_code_delta_event: object { delta, item_id, output_index, 3 more }` + + Emitted when a partial code snippet is streamed by the code interpreter. + + - `delta: string` + + The partial code snippet being streamed by the code interpreter. + + - `item_id: string` + + The unique identifier of the code interpreter tool call item. + + - `output_index: number` + + The index of the output item in the response for which the code is being streamed. + + - `sequence_number: number` + + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call_code.delta"` + + The type of the event. Always `response.code_interpreter_call_code.delta`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Code Done Event + +- `beta_response_code_interpreter_call_code_done_event: object { code, item_id, output_index, 3 more }` + + Emitted when the code snippet is finalized by the code interpreter. + + - `code: string` + + The final code snippet output by the code interpreter. + + - `item_id: string` + + The unique identifier of the code interpreter tool call item. + + - `output_index: number` + + The index of the output item in the response for which the code is finalized. + + - `sequence_number: number` + + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call_code.done"` + + The type of the event. Always `response.code_interpreter_call_code.done`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Completed Event + +- `beta_response_code_interpreter_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + + Emitted when the code interpreter call is completed. + + - `item_id: string` + + The unique identifier of the code interpreter tool call item. + + - `output_index: number` + + The index of the output item in the response for which the code interpreter call is completed. + + - `sequence_number: number` + + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call.completed"` + + The type of the event. Always `response.code_interpreter_call.completed`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call In Progress Event + +- `beta_response_code_interpreter_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + + Emitted when a code interpreter call is in progress. + + - `item_id: string` + + The unique identifier of the code interpreter tool call item. + + - `output_index: number` + + The index of the output item in the response for which the code interpreter call is in progress. + + - `sequence_number: number` + + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call.in_progress"` + + The type of the event. Always `response.code_interpreter_call.in_progress`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Call Interpreting Event + +- `beta_response_code_interpreter_call_interpreting_event: object { item_id, output_index, sequence_number, 2 more }` + + Emitted when the code interpreter is actively interpreting the code snippet. + + - `item_id: string` + + The unique identifier of the code interpreter tool call item. + + - `output_index: number` + + The index of the output item in the response for which the code interpreter is interpreting code. + + - `sequence_number: number` + + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call.interpreting"` + + The type of the event. Always `response.code_interpreter_call.interpreting`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Code Interpreter Tool Call + +- `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Compaction Item + +- `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + +### Beta Response Compaction Item Param + +- `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `id: optional string` + + The ID of the compaction item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Completed Event + +- `beta_response_completed_event: object { response, sequence_number, type, agent }` + + Emitted when the model response is complete. + + - `response: object { id, created_at, error, 31 more }` + + Properties of the completed response. + + - `id: string` + + Unique identifier for this Response. + + - `created_at: number` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: object { code, message }` + + An error object returned when the model fails to generate a Response. + + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"bio_policy"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: string` + + A human-readable description of the error. + + - `incomplete_details: object { reason }` + + Details about why the response is incomplete. + + - `reason: optional "max_output_tokens" or "content_filter"` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: string or array of BetaResponseInputItem` + + A system (or developer) message inserted into the model's context. + + When using 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. + + - `union_member_0: string` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `Input item list: array of BetaResponseInputItem` + + A list of one or many input items to the model, containing + different content types. + + - `beta_easy_input_message: object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `Text input: string` + + A text input to the model. + + - `beta_response_input_message_content_list: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `message: object { content, role, agent, 2 more }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + + The content of the output message. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + 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. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `drag: object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `type: object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `wait: object { type }` + + A wait action. + + - `actions: optional array of BetaComputerAction` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `drag: object { path, type, keys }` + + A drag action. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `type: object { text, type }` + + An action to type in text. + + - `wait: object { type }` + + A wait action. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `computer_call_output: object { call_id, output, type, 4 more }` + + The output of a computer tool call. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `id: optional string` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_web_search: object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `search: object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `queries: optional array of string` + + The search queries. + + - `query: optional string` + + The search query. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `url: string` + + The URL of the source. + + - `open_page: object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `url: optional string` + + The URL opened by the model. + + - `find_in_page: object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `id: optional string` + + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `function_call_output: object { call_id, output, type, 4 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or BetaResponseFunctionCallOutputItemList` + + Text, image, or file output of the function tool call. + + - `union_member_0: string` + + A JSON string of the output of the function tool call. + + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + + An array of content outputs (text, image, file) for the function tool call. + + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `agent_message: object { author, content, recipient, 3 more }` + + A message routed between agents. + + - `author: string` + + The sending agent identity. + + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + + Plaintext, image, or encrypted content sent between agents. + + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The item type. Always `agent_message`. + + - `id: optional string` + + The unique ID of this agent message item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { action, arguments, call_id, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The action arguments as a JSON string. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. + + - `id: optional string` + + The unique ID of this multi-agent call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call_output: object { action, call_id, output, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of object { text, type, annotations }` + + Text output returned by the multi-agent action. + + - `text: string` + + The text content. + + - `type: "output_text"` + + The content type. Always `output_text`. + + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + + Citations associated with the text content. + + - `union_member_0: array of object { file_id, filename, index, type }` + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The citation type. Always `file_citation`. + + - `union_member_1: array of object { end_index, start_index, title, 2 more }` + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `title: string` + + The title of the cited resource. + + - `type: "url_citation"` + + The citation type. Always `url_citation`. + + - `url: string` + + The URL of the cited resource. + + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + + - `container_id: string` + + The ID of the container. + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `file_id: string` + + The ID of the container file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `type: "container_file_citation"` + + The citation type. Always `container_file_citation`. + + - `type: "multi_agent_call_output"` + + The item type. Always `multi_agent_call_output`. + + - `id: optional string` + + The unique ID of this multi-agent call output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `tool_search_call: object { arguments, type, id, 4 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `id: optional string` + + The unique ID of this tool search call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + + - `tools: array of BetaTool` + + The loaded tool definitions returned by the tool search output. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether strict parameter validation is enforced for this function tool. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional object { key, type, value } or object { filters, type }` + + A filter to apply. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `Compound Filter: object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of object { key, type, value } or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_1: unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `mcp: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `MCP allowed tools: array of string` + + A string array of allowed tool names + + - `MCP tool filter: object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `MCP tool approval filter: object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `MCP tool approval setting: "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: optional string` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `union_member_0: string` + + The container ID. + + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + + - `"gpt-image-1.5"` + + - `"chatgpt-image-latest"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `beta_skill_reference: object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `beta_inline_skill: object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: object { data, media_type, type }` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `type: "inline"` + + Defines an inline skill for this request. + + - `beta_local_environment: object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `skills: optional array of BetaLocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `beta_container_reference: object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `text: object { type }` + + Unconstrained free-form text. + + - `grammar: object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + + The function/custom tools available inside this namespace. + + - `function: object { name, type, allowed_callers, 5 more }` + + - `name: string` + + - `type: "function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: optional unknown` + + - `strict: optional boolean` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `id: optional string` + + The unique ID of this tool search output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `additional_tools: object { role, tools, type, 2 more }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `tools: array of BetaTool` + + A list of additional tools made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `id: optional string` + + The ID of the compaction item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call: object { action, call_id, type, 5 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `beta_local_environment: object { type, skills }` + + - `beta_container_reference: object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call_output: object { call_id, output, type, 5 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `create_file: object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `delete_file: object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `update_file: object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `apply_patch_call_output: object { call_id, status, type, 4 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the custom tool call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `compaction_trigger: object { type, agent }` + + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `item_reference: object { id, agent, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `metadata: map[string]` + + 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. + + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. + + - `"gpt-5.6-sol"` + + - `"gpt-5.6-terra"` + + - `"gpt-5.6-luna"` + + - `"gpt-5.4"` + + - `"gpt-5.4-mini"` + + - `"gpt-5.4-nano"` + + - `"gpt-5.4-mini-2026-03-17"` + + - `"gpt-5.4-nano-2026-03-17"` + + - `"gpt-5.3-chat-latest"` + + - `"gpt-5.2"` + + - `"gpt-5.2-2025-12-11"` + + - `"gpt-5.2-chat-latest"` + + - `"gpt-5.2-pro"` + + - `"gpt-5.2-pro-2025-12-11"` + + - `"gpt-5.1"` + + - `"gpt-5.1-2025-11-13"` + + - `"gpt-5.1-codex"` + + - `"gpt-5.1-mini"` + + - `"gpt-5.1-chat-latest"` + + - `"gpt-5"` + + - `"gpt-5-mini"` + + - `"gpt-5-nano"` + + - `"gpt-5-2025-08-07"` + + - `"gpt-5-mini-2025-08-07"` + + - `"gpt-5-nano-2025-08-07"` + + - `"gpt-5-chat-latest"` + + - `"gpt-4.1"` + + - `"gpt-4.1-mini"` + + - `"gpt-4.1-nano"` + + - `"gpt-4.1-2025-04-14"` + + - `"gpt-4.1-mini-2025-04-14"` + + - `"gpt-4.1-nano-2025-04-14"` + + - `"o4-mini"` + + - `"o4-mini-2025-04-16"` + + - `"o3"` + + - `"o3-2025-04-16"` + + - `"o3-mini"` + + - `"o3-mini-2025-01-31"` + + - `"o1"` + + - `"o1-2024-12-17"` + + - `"o1-preview"` + + - `"o1-preview-2024-09-12"` + + - `"o1-mini"` + + - `"o1-mini-2024-09-12"` + + - `"gpt-4o"` + + - `"gpt-4o-2024-11-20"` + + - `"gpt-4o-2024-08-06"` + + - `"gpt-4o-2024-05-13"` + + - `"gpt-4o-audio-preview"` + + - `"gpt-4o-audio-preview-2024-10-01"` + + - `"gpt-4o-audio-preview-2024-12-17"` + + - `"gpt-4o-audio-preview-2025-06-03"` + + - `"gpt-4o-mini-audio-preview"` + + - `"gpt-4o-mini-audio-preview-2024-12-17"` + + - `"gpt-4o-search-preview"` + + - `"gpt-4o-mini-search-preview"` + + - `"gpt-4o-search-preview-2025-03-11"` + + - `"gpt-4o-mini-search-preview-2025-03-11"` + + - `"chatgpt-4o-latest"` + + - `"codex-mini-latest"` + + - `"gpt-4o-mini"` + + - `"gpt-4o-mini-2024-07-18"` + + - `"gpt-4-turbo"` + + - `"gpt-4-turbo-2024-04-09"` + + - `"gpt-4-0125-preview"` + + - `"gpt-4-turbo-preview"` + + - `"gpt-4-1106-preview"` + + - `"gpt-4-vision-preview"` + + - `"gpt-4"` + + - `"gpt-4-0314"` + + - `"gpt-4-0613"` + + - `"gpt-4-32k"` + + - `"gpt-4-32k-0314"` + + - `"gpt-4-32k-0613"` + + - `"gpt-3.5-turbo"` + + - `"gpt-3.5-turbo-16k"` + + - `"gpt-3.5-turbo-0301"` + + - `"gpt-3.5-turbo-0613"` + + - `"gpt-3.5-turbo-1106"` + + - `"gpt-3.5-turbo-0125"` + + - `"gpt-3.5-turbo-16k-0613"` + + - `"o1-pro"` + + - `"o1-pro-2025-03-19"` + + - `"o3-pro"` + + - `"o3-pro-2025-06-10"` + + - `"o3-deep-research"` + + - `"o3-deep-research-2025-06-26"` + + - `"o4-mini-deep-research"` + + - `"o4-mini-deep-research-2025-06-26"` + + - `"computer-use-preview"` + + - `"computer-use-preview-2025-03-11"` + + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` + + - `object: "response"` + + The object type of this resource - always set to `response`. + + - `output: array of BetaResponseOutputItem` + + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + + The content of the output message. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `type: "message"` + + The type of the output message. Always `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `id: optional string` + + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the function call tool output. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the function call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the function call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `agent_message: object { id, author, content, 3 more }` + + - `id: string` + + The unique ID of the agent message. + + - `author: string` + + The sending agent identity. + + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + + Encrypted content sent between agents. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `text: object { text, type }` + + A text content. + + - `text: string` + + - `type: "text"` + + - `summary_text: object { text, type }` + + A summary text from the model. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `reasoning_text: object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: string` + + The URL of the screenshot image. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { id, action, arguments, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action to execute. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call_output: object { id, action, call_id, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call output item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of BetaResponseOutputText` + + Text output returned by the multi-agent action. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `type: "multi_agent_call_output"` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_function_web_search: object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `actions: optional array of BetaComputerAction` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + + - `id: string` + + The unique ID of the tool search call item. + + - `arguments: unknown` + + Arguments used for the tool search call. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search call item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the tool search output item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `tools: array of BetaTool` + + The loaded tool definitions returned by tool search. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "tool_search_output"` + + The type of the item. Always `tool_search_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `additional_tools: object { id, role, tools, 2 more }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of BetaTool` + + The additional tool definitions made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + - `max_output_length: number` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: number` + + Optional timeout in milliseconds for the commands. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `beta_response_local_environment: object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + + The output of a shell tool call that was emitted. + + - `id: string` + + The unique ID of the shell call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `max_output_length: number` + + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents + + - `outcome: object { type } or object { exit_code, type }` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + The standard error output that was captured. + + - `stdout: string` + + The standard output that was captured. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + + A tool call that applies file diffs by creating, deleting, or updating files. + + - `id: string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + One of the create_file, delete_file, or update_file operations applied via apply_patch. + + - `create_file: object { diff, path, type }` + + Instruction describing how to create a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to create. + + - `type: "create_file"` + + Create a new file with the provided diff. + + - `delete_file: object { path, type }` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: string` + + Path of the file to delete. + + - `type: "delete_file"` + + Delete the specified file. + + - `update_file: object { diff, path, type }` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to update. + + - `type: "update_file"` + + Update an existing file with the provided diff. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call output. + + - `output: optional string` + + Optional textual output returned by the apply patch tool. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + + A response to an MCP approval request. + + - `id: string` + + The unique ID of the approval response + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + + The output of a custom tool call from your code, being sent back to the model. + + - `id: string` + + The unique ID of the custom tool call output item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: boolean` + + Whether to allow the model to run tool calls in parallel. + + - `temperature: number` + + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. + + - `beta_tool_choice_options: "none" or "auto" or "required"` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `"none"` + + - `"auto"` + + - `"required"` + + - `beta_tool_choice_allowed: object { mode, tools, type }` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: "auto" or "required"` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `beta_tool_choice_types: object { type }` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `beta_tool_choice_function: object { name, type }` + + Use this option to force the model to call a specific function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `beta_tool_choice_mcp: object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `name: optional string` + + The name of the tool to call on the server. + + - `beta_tool_choice_custom: object { name, type }` + + Use this option to force the model to call a specific custom tool. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `BetaSpecificProgrammaticToolCallingParam: object { type }` + + - `beta_tool_choice_apply_patch: object { type }` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: "apply_patch"` + + The tool to call. Always `apply_patch`. + + - `beta_tool_choice_shell: object { type }` + + Forces the model to call the shell tool when a tool call is required. + + - `type: "shell"` + + The tool to call. Always `shell`. + + - `tools: array of BetaTool` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `top_p: number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `background: optional boolean` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: optional number` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: optional object { id }` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: string` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: optional number` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: optional object { input, output }` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response input. + + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `error: object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response output. + + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `error: object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `previous_response_id: optional string` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: optional object { id, variables, version }` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: string` + + The unique identifier of the prompt template to use. + + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `union_member_0: string` + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `version: optional string` + + Optional version of the prompt template. + + - `prompt_cache_key: optional string` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + + - `prompt_cache_options: optional object { mode, ttl }` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: "implicit" or "explicit"` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: "30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: optional "in_memory" or "24h"` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `"in_memory"` + + - `"24h"` + + - `reasoning: optional object { context, effort, generate_summary, 2 more }` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: optional "auto" or "current_turn" or "all_turns"` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` + + - `"current_turn"` + + - `"all_turns"` + + - `effort: optional "none" or "minimal" or "low" or 4 more` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `generate_summary: optional "auto" or "concise" or "detailed"` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `mode: optional string or "standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + + - `summary: optional "auto" or "concise" or "detailed"` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `safety_identifier: optional string` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: optional "completed" or "failed" or "in_progress" or 3 more` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + + - `text: optional object { format, verbosity }` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `text: object { type }` + + Default response format. Used to generate text responses. + + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `schema: map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). + + - `json_object: object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `top_logprobs: optional number` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `truncation: optional "auto" or "disabled"` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: number` + + The number of input tokens. + + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: number` + + The number of input tokens that were written to the cache. + + - `cached_tokens: number` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + + - `output_tokens: number` + + The number of output tokens. + + - `output_tokens_details: object { reasoning_tokens }` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: number` + + The number of reasoning tokens. + + - `total_tokens: number` + + The total number of tokens used. + + - `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `sequence_number: number` + + The sequence number for this event. + + - `type: "response.completed"` + + The type of the event. Always `response.completed`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Computer Tool Call + +- `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `drag: object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `type: object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `wait: object { type }` + + A wait action. + + - `actions: optional array of BetaComputerAction` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `drag: object { path, type, keys }` + + A drag action. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `type: object { text, type }` + + An action to type in text. + + - `wait: object { type }` + + A wait action. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Computer Tool Call Output Item + +- `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + +### Beta Response Computer Tool Call Output Screenshot + +- `beta_response_computer_tool_call_output_screenshot: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + +### Beta Response Container Reference + +- `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + +### Beta Response Content + +- `beta_response_content: BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile or 3 more` + + Multi-modal input and output contents. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `Reasoning text: object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + +### Beta Response Content Part Added Event + +- `beta_response_content_part_added_event: object { content_index, item_id, output_index, 4 more }` + + Emitted when a new content part is added. + + - `content_index: number` + + The index of the content part that was added. + + - `item_id: string` + + The ID of the output item that the content part was added to. + + - `output_index: number` + + The index of the output item that the content part was added to. + + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + + The content part that was added. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `reasoning_text: object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.content_part.added"` + + The type of the event. Always `response.content_part.added`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Content Part Done Event + +- `beta_response_content_part_done_event: object { content_index, item_id, output_index, 4 more }` + + Emitted when a content part is done. + + - `content_index: number` + + The index of the content part that is done. + + - `item_id: string` + + The ID of the output item that the content part was added to. + + - `output_index: number` + + The index of the output item that the content part was added to. + + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + + The content part that is done. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `reasoning_text: object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.content_part.done"` + + The type of the event. Always `response.content_part.done`. + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Conversation Param + +- `beta_response_conversation_param: object { id }` + + The conversation that this response belongs to. + + - `id: string` + + The unique ID of the conversation. + +### Beta Response Created Event + +- `beta_response_created_event: object { response, sequence_number, type, agent }` + + An event that is emitted when a response is created. + + - `response: object { id, created_at, error, 31 more }` + + The response that was created. + + - `id: string` + + Unique identifier for this Response. + + - `created_at: number` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: object { code, message }` + + An error object returned when the model fails to generate a Response. + + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"bio_policy"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: string` + + A human-readable description of the error. + + - `incomplete_details: object { reason }` + + Details about why the response is incomplete. + + - `reason: optional "max_output_tokens" or "content_filter"` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: string or array of BetaResponseInputItem` + + A system (or developer) message inserted into the model's context. + + When using 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. + + - `union_member_0: string` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `Input item list: array of BetaResponseInputItem` + + A list of one or many input items to the model, containing + different content types. + + - `beta_easy_input_message: object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `Text input: string` + + A text input to the model. + + - `beta_response_input_message_content_list: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `message: object { content, role, agent, 2 more }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + + The content of the output message. + + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `file_citation: object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `url_citation: object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `url: string` + + The URL of the web resource. + + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + 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. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `drag: object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `type: object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `wait: object { type }` + + A wait action. + + - `actions: optional array of BetaComputerAction` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `click: object { button, type, x, 2 more }` + + A click action. + + - `double_click: object { keys, type, x, y }` + + A double click action. + + - `drag: object { path, type, keys }` + + A drag action. + + - `keypress: object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `move: object { type, x, y, keys }` + + A mouse move action. + + - `screenshot: object { type }` + + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `type: object { text, type }` + + An action to type in text. + + - `wait: object { type }` + + A wait action. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `computer_call_output: object { call_id, output, type, 4 more }` + + The output of a computer tool call. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `id: optional string` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_web_search: object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `search: object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `queries: optional array of string` + + The search queries. + + - `query: optional string` + + The search query. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `url: string` + + The URL of the source. + + - `open_page: object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `url: optional string` + + The URL opened by the model. + + - `find_in_page: object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `id: optional string` + + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `function_call_output: object { call_id, output, type, 4 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or BetaResponseFunctionCallOutputItemList` + + Text, image, or file output of the function tool call. + + - `union_member_0: string` + + A JSON string of the output of the function tool call. + + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + + An array of content outputs (text, image, file) for the function tool call. + + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `agent_message: object { author, content, recipient, 3 more }` + + A message routed between agents. + + - `author: string` + + The sending agent identity. + + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + + Plaintext, image, or encrypted content sent between agents. + + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The item type. Always `agent_message`. + + - `id: optional string` + + The unique ID of this agent message item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { action, arguments, call_id, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The action arguments as a JSON string. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. + + - `id: optional string` + + The unique ID of this multi-agent call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call_output: object { action, call_id, output, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of object { text, type, annotations }` + + Text output returned by the multi-agent action. + + - `text: string` + + The text content. + + - `type: "output_text"` + + The content type. Always `output_text`. + + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + + Citations associated with the text content. + + - `union_member_0: array of object { file_id, filename, index, type }` + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The citation type. Always `file_citation`. + + - `union_member_1: array of object { end_index, start_index, title, 2 more }` + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `title: string` + + The title of the cited resource. + + - `type: "url_citation"` + + The citation type. Always `url_citation`. + + - `url: string` + + The URL of the cited resource. + + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + + - `container_id: string` + + The ID of the container. + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `file_id: string` + + The ID of the container file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `type: "container_file_citation"` + + The citation type. Always `container_file_citation`. + + - `type: "multi_agent_call_output"` + + The item type. Always `multi_agent_call_output`. + + - `id: optional string` + + The unique ID of this multi-agent call output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `tool_search_call: object { arguments, type, id, 4 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `id: optional string` + + The unique ID of this tool search call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + + - `tools: array of BetaTool` + + The loaded tool definitions returned by the tool search output. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether strict parameter validation is enforced for this function tool. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional object { key, type, value } or object { filters, type }` + + A filter to apply. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `Compound Filter: object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of object { key, type, value } or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `Comparison Filter: object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_2: boolean` + + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` + + - `union_member_1: unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `mcp: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `MCP allowed tools: array of string` + + A string array of allowed tool names + + - `MCP tool filter: object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `MCP tool approval filter: object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `MCP tool approval setting: "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: optional string` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `union_member_0: string` + + The container ID. + + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + + - `"gpt-image-1.5"` + + - `"chatgpt-image-latest"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `beta_skill_reference: object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `beta_inline_skill: object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: object { data, media_type, type }` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `type: "inline"` + + Defines an inline skill for this request. + + - `beta_local_environment: object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `skills: optional array of BetaLocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `beta_container_reference: object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `text: object { type }` + + Unconstrained free-form text. + + - `grammar: object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + + The function/custom tools available inside this namespace. + + - `function: object { name, type, allowed_callers, 5 more }` + + - `name: string` + + - `type: "function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: optional unknown` + + - `strict: optional boolean` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `id: optional string` + + The unique ID of this tool search output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `additional_tools: object { role, tools, type, 2 more }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `tools: array of BetaTool` + + A list of additional tools made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `id: optional string` + + The ID of the compaction item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call: object { action, call_id, type, 5 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `beta_local_environment: object { type, skills }` + + - `beta_container_reference: object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call_output: object { call_id, output, type, 5 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `create_file: object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `delete_file: object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `update_file: object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `apply_patch_call_output: object { call_id, status, type, 4 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the custom tool call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `compaction_trigger: object { type, agent }` + + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `item_reference: object { id, agent, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `metadata: map[string]` + + 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. + + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) + to browse and compare available models. + + - `"gpt-5.6-sol"` + + - `"gpt-5.6-terra"` + + - `"gpt-5.6-luna"` + + - `"gpt-5.4"` + + - `"gpt-5.4-mini"` + + - `"gpt-5.4-nano"` + + - `"gpt-5.4-mini-2026-03-17"` + + - `"gpt-5.4-nano-2026-03-17"` + + - `"gpt-5.3-chat-latest"` + + - `"gpt-5.2"` + + - `"gpt-5.2-2025-12-11"` + + - `"gpt-5.2-chat-latest"` + + - `"gpt-5.2-pro"` + + - `"gpt-5.2-pro-2025-12-11"` + + - `"gpt-5.1"` + + - `"gpt-5.1-2025-11-13"` + + - `"gpt-5.1-codex"` + + - `"gpt-5.1-mini"` + + - `"gpt-5.1-chat-latest"` + + - `"gpt-5"` + + - `"gpt-5-mini"` + + - `"gpt-5-nano"` + + - `"gpt-5-2025-08-07"` + + - `"gpt-5-mini-2025-08-07"` + + - `"gpt-5-nano-2025-08-07"` + + - `"gpt-5-chat-latest"` + + - `"gpt-4.1"` + + - `"gpt-4.1-mini"` + + - `"gpt-4.1-nano"` + + - `"gpt-4.1-2025-04-14"` + + - `"gpt-4.1-mini-2025-04-14"` + + - `"gpt-4.1-nano-2025-04-14"` - - `output: array of BetaResponseOutputItem` + - `"o4-mini"` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + - `"o4-mini-2025-04-16"` - - `beta_response_output_message: object { id, content, role, 4 more }` + - `"o3"` - An output message from the model. + - `"o3-2025-04-16"` - - `id: string` + - `"o3-mini"` - The unique ID of the output message. + - `"o3-mini-2025-01-31"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"o1"` - The content of the output message. + - `"o1-2024-12-17"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"o1-preview"` - A text output from the model. + - `"o1-preview-2024-09-12"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"o1-mini"` - The annotations of the text output. + - `"o1-mini-2024-09-12"` - - `file_citation: object { file_id, filename, index, type }` + - `"gpt-4o"` - A citation to a file. + - `"gpt-4o-2024-11-20"` - - `file_id: string` + - `"gpt-4o-2024-08-06"` - The ID of the file. + - `"gpt-4o-2024-05-13"` - - `filename: string` + - `"gpt-4o-audio-preview"` - The filename of the file cited. + - `"gpt-4o-audio-preview-2024-10-01"` - - `index: number` + - `"gpt-4o-audio-preview-2024-12-17"` - The index of the file in the list of files. + - `"gpt-4o-audio-preview-2025-06-03"` - - `type: "file_citation"` + - `"gpt-4o-mini-audio-preview"` - The type of the file citation. Always `file_citation`. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `url_citation: object { end_index, start_index, title, 2 more }` + - `"gpt-4o-search-preview"` - A citation for a web resource used to generate a model response. + - `"gpt-4o-mini-search-preview"` - - `end_index: number` + - `"gpt-4o-search-preview-2025-03-11"` - The index of the last character of the URL citation in the message. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `start_index: number` + - `"chatgpt-4o-latest"` - The index of the first character of the URL citation in the message. + - `"codex-mini-latest"` - - `title: string` + - `"gpt-4o-mini"` - The title of the web resource. + - `"gpt-4o-mini-2024-07-18"` - - `type: "url_citation"` + - `"gpt-4-turbo"` - The type of the URL citation. Always `url_citation`. + - `"gpt-4-turbo-2024-04-09"` - - `url: string` + - `"gpt-4-0125-preview"` - The URL of the web resource. + - `"gpt-4-turbo-preview"` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `"gpt-4-1106-preview"` - A citation for a container file used to generate a model response. + - `"gpt-4-vision-preview"` - - `container_id: string` + - `"gpt-4"` - The ID of the container file. + - `"gpt-4-0314"` - - `end_index: number` + - `"gpt-4-0613"` - The index of the last character of the container file citation in the message. + - `"gpt-4-32k"` - - `file_id: string` + - `"gpt-4-32k-0314"` - The ID of the file. + - `"gpt-4-32k-0613"` - - `filename: string` + - `"gpt-3.5-turbo"` - The filename of the container file cited. + - `"gpt-3.5-turbo-16k"` - - `start_index: number` + - `"gpt-3.5-turbo-0301"` - The index of the first character of the container file citation in the message. + - `"gpt-3.5-turbo-0613"` - - `type: "container_file_citation"` + - `"gpt-3.5-turbo-1106"` - The type of the container file citation. Always `container_file_citation`. + - `"gpt-3.5-turbo-0125"` - - `file_path: object { file_id, index, type }` + - `"gpt-3.5-turbo-16k-0613"` - A path to a file. + - `"o1-pro"` - - `file_id: string` + - `"o1-pro-2025-03-19"` - The ID of the file. + - `"o3-pro"` - - `index: number` + - `"o3-pro-2025-06-10"` - The index of the file in the list of files. + - `"o3-deep-research"` - - `type: "file_path"` + - `"o3-deep-research-2025-06-26"` - The type of the file path. Always `file_path`. + - `"o4-mini-deep-research"` - - `text: string` + - `"o4-mini-deep-research-2025-06-26"` - The text output from the model. + - `"computer-use-preview"` - - `type: "output_text"` + - `"computer-use-preview-2025-03-11"` - The type of the output text. Always `output_text`. + - `"gpt-5-codex"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"gpt-5-pro"` - - `token: string` + - `"gpt-5-pro-2025-10-06"` - - `bytes: array of number` + - `"gpt-5.1-codex-max"` - - `logprob: number` + - `object: "response"` - - `top_logprobs: array of object { token, bytes, logprob }` + The object type of this resource - always set to `response`. - - `token: string` + - `output: array of BetaResponseOutputItem` - - `bytes: array of number` + An array of content items generated by the model. - - `logprob: number` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `beta_response_output_refusal: object { refusal, type }` + - `beta_response_output_message: object { id, content, role, 4 more }` - A refusal from the model. + An output message from the model. - - `refusal: string` + - `id: string` - The refusal explanation from the model. + The unique ID of the output message. - - `type: "refusal"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The type of the refusal. Always `refusal`. + The content of the output message. - `role: "assistant"` @@ -34581,12 +46302,6 @@ Compact a response The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: "message"` The type of the output message. Always `message`. @@ -34595,18 +46310,12 @@ Compact a response The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"commentary"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -34625,16 +46334,6 @@ Compact a response The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - - `"incomplete"` - - - `"failed"` - - `type: "file_search_call"` The type of the file search tool call. Always `file_search_call`. @@ -34643,44 +46342,10 @@ Compact a response The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` The results of the file search tool call. - - `attributes: optional map[string or number or boolean]` - - 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. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `file_id: optional string` - - The unique ID of the file. - - - `filename: optional string` - - The name of the file. - - - `score: optional number` - - The relevance score of the file - a value between 0 and 1. - - - `text: optional string` - - The text that was retrieved from the file. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` A tool call to run a function. See the @@ -34710,24 +46375,10 @@ Compact a response The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - `namespace: optional string` The namespace of the function to run. @@ -34737,12 +46388,6 @@ Compact a response The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - `id: string` @@ -34770,100 +46415,14 @@ Compact a response A text input to the model. - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or @@ -35149,74 +46708,10 @@ Compact a response 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). - - `search: object { type, queries, query, sources }` - - Action type "search" - Performs a web search query. - - - `type: "search"` - - The action type. - - - `queries: optional array of string` - - The search queries. - - - `query: optional string` - - The search query. - - - `sources: optional array of object { type, url }` - - The sources used in the search. - - - `type: "url"` - - The type of source. Always `url`. - - - `url: string` - - The URL of the source. - - - `open_page: object { type, url }` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: "open_page"` - - The action type. - - - `url: optional string` - - The URL opened by the model. - - - `find_in_page: object { pattern, type, url }` - - Action type "find_in_page": Searches for a pattern within a loaded page. - - - `pattern: string` - - The pattern or text to search for within the page. - - - `type: "find_in_page"` - - The action type. - - - `url: string` - - The URL of the page searched for the pattern. - - `status: "in_progress" or "searching" or "completed" or "failed"` The status of the web search tool call. - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - - `"failed"` - - `type: "web_search_call"` The type of the web search tool call. Always `web_search_call`. @@ -35225,10 +46720,6 @@ Compact a response The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` A tool call to a computer use tool. See the @@ -35246,253 +46737,28 @@ Compact a response The pending safety checks for the computer call. - - `id: string` - - The ID of the pending safety check. - - - `code: optional string` - - The type of the pending safety check. - - - `message: optional string` - - Details about the pending safety check. - - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: "computer_call"` The type of the computer call. Always `computer_call`. - - `"computer_call"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. - - `click: object { button, type, x, 2 more }` - - A click action. - - - `button: "left" or "right" or "wheel" or 2 more` - - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - - `"left"` - - - `"right"` - - - `"wheel"` - - - `"back"` - - - `"forward"` - - - `type: "click"` - - Specifies the event type. For a click action, this property is always `click`. - - - `x: number` - - The x-coordinate where the click occurred. - - - `y: number` - - The y-coordinate where the click occurred. - - - `keys: optional array of string` - - The keys being held while clicking. - - - `double_click: object { keys, type, x, y }` - - A double click action. - - - `keys: array of string` - - The keys being held while double-clicking. - - - `type: "double_click"` - - Specifies the event type. For a double click action, this property is always set to `double_click`. - - - `x: number` - - The x-coordinate where the double click occurred. - - - `y: number` - - The y-coordinate where the double click occurred. - - - `drag: object { path, type, keys }` - - A drag action. - - - `path: array of object { x, y }` - - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` - - - `x: number` - - The x-coordinate. - - - `y: number` - - The y-coordinate. - - - `type: "drag"` - - Specifies the event type. For a drag action, this property is always set to `drag`. - - - `keys: optional array of string` - - The keys being held while dragging the mouse. - - - `keypress: object { keys, type }` - - A collection of keypresses the model would like to perform. - - - `keys: array of string` - - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - - `type: "keypress"` - - Specifies the event type. For a keypress action, this property is always set to `keypress`. - - - `move: object { type, x, y, keys }` - - A mouse move action. - - - `type: "move"` - - Specifies the event type. For a move action, this property is always set to `move`. - - - `x: number` - - The x-coordinate to move to. - - - `y: number` - - The y-coordinate to move to. - - - `keys: optional array of string` - - The keys being held while moving the mouse. - - - `screenshot: object { type }` - - A screenshot action. - - - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - A scroll action. - - - `scroll_x: number` - - The horizontal scroll distance. - - - `scroll_y: number` - - The vertical scroll distance. - - - `type: "scroll"` - - Specifies the event type. For a scroll action, this property is always set to `scroll`. - - - `x: number` - - The x-coordinate where the scroll occurred. - - - `y: number` - - The y-coordinate where the scroll occurred. - - - `keys: optional array of string` - - The keys being held while scrolling. - - - `type: object { text, type }` - - An action to type in text. - - - `text: string` - - The text to type. - - - `type: "type"` - - Specifies the event type. For a type action, this property is always set to `type`. - - - `wait: object { type }` - - A wait action. - - `actions: optional array of BetaComputerAction` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - - `click: object { button, type, x, 2 more }` - - A click action. - - - `double_click: object { keys, type, x, y }` - - A double click action. - - - `drag: object { path, type, keys }` - - A drag action. - - - `keypress: object { keys, type }` - - A collection of keypresses the model would like to perform. - - - `move: object { type, x, y, keys }` - - A mouse move action. - - - `screenshot: object { type }` - - A screenshot action. - - - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - A scroll action. - - - `type: object { text, type }` - - An action to type in text. - - - `wait: object { type }` - - A wait action. - - `agent: optional object { agent_name }` The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - `id: string` @@ -35581,14 +46847,6 @@ Compact a response Reasoning summary content. - - `text: string` - - A summary of the reasoning output from the model so far. - - - `type: "summary_text"` - - The type of the object. Always `summary_text`. - - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -35597,22 +46855,10 @@ Compact a response The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` Reasoning text content. - - `text: string` - - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - `encrypted_content: optional string` The encrypted content of the reasoning item - populated when a response is @@ -35623,12 +46869,6 @@ Compact a response The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `program: object { id, call_id, code, 3 more }` - `id: string` @@ -35777,1035 +47017,736 @@ Compact a response Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `name: string` - - The name of the function to call. - - - `parameters: map[unknown]` - - A JSON schema object describing the parameters of the function. - - - `strict: boolean` - - Whether strict parameter validation is enforced for this function tool. - - - `type: "function"` - - The type of the function tool. Always `function`. - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this function is deferred and loaded via tool search. - - - `description: optional string` - - A description of the function. Used by the model to determine whether or not to call the function. - - - `output_schema: optional map[unknown]` - - A JSON schema object describing the JSON value encoded in string outputs for this function. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "file_search"` - - The type of the file search tool. Always `file_search`. - - - `vector_store_ids: array of string` - - The IDs of the vector stores to search. - - - `filters: optional object { key, type, value } or object { filters, type }` - - A filter to apply. - - - `Comparison Filter: object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of unknown` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `union_member_3: array of unknown` - - - `Compound Filter: object { filters, type }` - - Combine multiple filters using `and` or `or`. - - - `filters: array of object { key, type, value } or unknown` - - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - - `Comparison Filter: object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of unknown` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `union_member_3: array of unknown` - - - `union_member_1: unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - - `max_num_results: optional number` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - Ranking options for search. - - - `hybrid_search: optional object { embedding_weight, text_weight }` - - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - - `embedding_weight: number` - - The weight of the embedding in the reciprocal ranking fusion. - - - `text_weight: number` - - The weight of the text in the reciprocal ranking fusion. - - - `ranker: optional "auto" or "default-2024-11-15"` - - The ranker to use for the file search. - - - `"auto"` - - - `"default-2024-11-15"` - - - `score_threshold: optional number` - - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `beta_computer_tool: object { type }` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "computer"` - - The type of the computer tool. Always `computer`. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `display_height: number` - - The height of the computer display. - - - `display_width: number` - - The width of the computer display. - - - `environment: "windows" or "mac" or "linux" or 2 more` - - The type of computer environment to control. - - - `"windows"` - - - `"mac"` - - - `"linux"` - - - `"ubuntu"` - - - `"browser"` - - - `type: "computer_use_preview"` - - The type of the computer use tool. Always `computer_use_preview`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `type: "web_search" or "web_search_2025_08_26"` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - - `"web_search"` - - - `"web_search_2025_08_26"` - - - `filters: optional object { allowed_domains }` - - Filters for the search. - - - `allowed_domains: optional array of string` - - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - - - `search_context_size: optional "low" or "medium" or "high"` - - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` - - Free text input for the city of the user, e.g. `San Francisco`. - - - `country: optional string` - - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - - `region: optional string` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - Free text input for the region of the user, e.g. `California`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `timezone: optional string` + - `code_interpreter: object { container, type, allowed_callers }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + A tool that runs Python code to help generate a response to a prompt. - - `type: optional "approximate"` + - `programmatic_tool_calling: object { type }` - The type of location approximation. Always `approximate`. + - `image_generation: object { type, action, background, 9 more }` - - `"approximate"` + A tool that generates images using the GPT image models. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `local_shell: object { type }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + A tool that allows the model to execute shell commands in a local environment. - - `server_label: string` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - A label for this MCP server, used to identify it in tool calls. + A tool that allows the model to execute shell commands. - - `type: "mcp"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The type of the MCP tool. Always `mcp`. + 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) - - `allowed_callers: optional array of "direct" or "programmatic"` + - `beta_namespace_tool: object { description, name, tools, type }` - The tool invocation context(s). + Groups function/custom tools under a shared namespace. - - `"direct"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `"programmatic"` + Hosted or BYOT tool search configuration for deferred tools. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - List of allowed tool names or a filter object. + 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). - - `MCP allowed tools: array of string` + - `beta_apply_patch_tool: object { type, allowed_callers }` - A string array of allowed tool names + Allows the assistant to create, delete, or update files using unified diffs. - - `MCP tool filter: object { read_only, tool_names }` + - `type: "tool_search_output"` - A filter object to specify which tools are allowed. + The type of the item. Always `tool_search_output`. - - `read_only: optional boolean` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - - `tool_names: optional array of string` + - `agent_name: string` - List of allowed tool names. + The canonical name of the agent that produced this item. - - `authorization: optional string` + - `created_by: optional string` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The identifier of the actor that created the item. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `additional_tools: object { id, role, tools, 2 more }` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + - `id: string` - Currently supported `connector_id` values are: + The unique ID of the additional tools item. - - 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` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `"connector_dropbox"` + The role that provided the additional tools. - - `"connector_gmail"` + - `"unknown"` - - `"connector_googlecalendar"` + - `"user"` - - `"connector_googledrive"` + - `"assistant"` - - `"connector_microsoftteams"` + - `"system"` - - `"connector_outlookcalendar"` + - `"critic"` - - `"connector_outlookemail"` + - `"discriminator"` - - `"connector_sharepoint"` + - `"developer"` - - `defer_loading: optional boolean` + - `"tool"` - Whether this MCP tool is deferred and discovered via tool search. + - `tools: array of BetaTool` - - `headers: optional map[string]` + The additional tool definitions made available at this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `require_approval: optional object { always, never } or "always" or "never"` + 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). - Specify which of the MCP server's tools require approval. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `MCP tool approval filter: object { always, never }` + 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). - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `beta_computer_tool: object { type }` - - `always: optional object { read_only, tool_names }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A filter object to specify which tools are allowed. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `read_only: optional boolean` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - 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. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `tool_names: optional array of string` + 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). - List of allowed tool names. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `never: optional object { read_only, tool_names }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - A filter object to specify which tools are allowed. + - `code_interpreter: object { container, type, allowed_callers }` - - `read_only: optional boolean` + A tool that runs Python code to help generate a response to a prompt. - 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. + - `programmatic_tool_calling: object { type }` - - `tool_names: optional array of string` + - `image_generation: object { type, action, background, 9 more }` - List of allowed tool names. + A tool that generates images using the GPT image models. - - `MCP tool approval setting: "always" or "never"` + - `local_shell: object { type }` - 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. + A tool that allows the model to execute shell commands in a local environment. - - `"always"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"never"` + A tool that allows the model to execute shell commands. - - `server_description: optional string` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Optional description of the MCP server, used to provide more context. + 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) - - `server_url: optional string` + - `beta_namespace_tool: object { description, name, tools, type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Groups function/custom tools under a shared namespace. - - `tunnel_id: optional string` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - 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. + Hosted or BYOT tool search configuration for deferred tools. - - `code_interpreter: object { container, type, allowed_callers }` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - A tool that runs Python code to help generate a response to a prompt. + 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). - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - 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. + Allows the assistant to create, delete, or update files using unified diffs. - - `union_member_0: string` + - `type: "additional_tools"` - The container ID. + The type of the item. Always `additional_tools`. - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + - `agent: optional object { agent_name }` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The agent that produced this item. - - `type: "auto"` + - `agent_name: string` - Always `auto`. + The canonical name of the agent that produced this item. - - `file_ids: optional array of string` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - An optional list of uploaded files to make available to your code. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `id: string` - The memory limit for the code interpreter container. + The unique ID of the compaction item. - - `"1g"` + - `encrypted_content: string` - - `"4g"` + The encrypted content that was produced by compaction. - - `"16g"` + - `type: "compaction"` - - `"64g"` + The type of the item. Always `compaction`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `agent: optional object { agent_name }` - Network access policy for the container. + The agent that produced this item. - - `beta_container_network_policy_disabled: object { type }` + - `agent_name: string` - - `type: "disabled"` + The canonical name of the agent that produced this item. - Disable outbound network access. Always `disabled`. + - `created_by: optional string` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The identifier of the actor that created the item. - - `allowed_domains: array of string` + - `image_generation_call: object { id, result, status, 2 more }` - A list of allowed domains when type is `allowlist`. + An image generation request made by the model. - - `type: "allowlist"` + - `id: string` - Allow outbound network access only to specified domains. Always `allowlist`. + The unique ID of the image generation call. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `result: string` - Optional domain-scoped secrets for allowlisted domains. + The generated image encoded in base64. - - `domain: string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The domain associated with the secret. + The status of the image generation call. - - `name: string` + - `"in_progress"` - The name of the secret to inject for the domain. + - `"completed"` - - `value: string` + - `"generating"` - The secret value to inject for the domain. + - `"failed"` - - `type: "code_interpreter"` + - `type: "image_generation_call"` - The type of the code interpreter tool. Always `code_interpreter`. + The type of the image generation call. Always `image_generation_call`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that produced this item. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `programmatic_tool_calling: object { type }` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `image_generation: object { type, action, background, 9 more }` + A tool call to run code. - A tool that generates images using the GPT image models. + - `id: string` - - `type: "image_generation"` + The unique ID of the code interpreter tool call. - The type of the image generation tool. Always `image_generation`. + - `code: string` - - `action: optional "generate" or "edit" or "auto"` + The code to run, or null if not available. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `container_id: string` - - `"generate"` + The ID of the container used to run the code. - - `"edit"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"auto"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `background: optional "transparent" or "opaque" or "auto"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - 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. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `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. + - `type: "code_interpreter_call"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"transparent"` + - `agent: optional object { agent_name }` - - `"opaque"` + The agent that produced this item. - - `"auto"` + - `local_shell_call: object { id, action, call_id, 3 more }` - - `input_fidelity: optional "high" or "low"` + A tool call to run a command on the local shell. - 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`. + - `id: string` - - `"high"` + The unique ID of the local shell call. - - `"low"` + - `action: object { command, env, type, 3 more }` - - `input_image_mask: optional object { file_id, image_url }` + Execute a shell command on the server. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `command: array of string` - - `file_id: optional string` + The command to run. - File ID for the mask image. + - `env: map[string]` - - `image_url: optional string` + Environment variables to set for the command. - Base64-encoded mask image. + - `type: "exec"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The type of the local shell action. Always `exec`. - The image generation model to use. Default: `gpt-image-1`. + - `timeout_ms: optional number` - - `"gpt-image-1"` + Optional timeout in milliseconds for the command. - - `"gpt-image-1-mini"` + - `user: optional string` - - `"gpt-image-2"` + Optional user to run the command as. - - `"gpt-image-2-2026-04-21"` + - `working_directory: optional string` - - `"gpt-image-1.5"` + Optional working directory to run the command in. - - `"chatgpt-image-latest"` + - `call_id: string` - - `moderation: optional "auto" or "low"` + The unique ID of the local shell tool call generated by the model. - Moderation level for the generated image. Default: `auto`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"auto"` + The status of the local shell call. - - `"low"` + - `"in_progress"` - - `output_compression: optional number` + - `"completed"` - Compression level for the output image. Default: 100. + - `"incomplete"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `type: "local_shell_call"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The type of the local shell call. Always `local_shell_call`. - - `"png"` + - `agent: optional object { agent_name }` - - `"webp"` + The agent that produced this item. - - `"jpeg"` + - `agent_name: string` - - `partial_images: optional number` + The canonical name of the agent that produced this item. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `quality: optional "low" or "medium" or "high" or "auto"` + The output of a local shell tool call. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `id: string` - - `"low"` + The unique ID of the local shell tool call generated by the model. - - `"medium"` + - `output: string` - - `"high"` + A JSON string of the output of the local shell tool call. - - `"auto"` + - `type: "local_shell_call_output"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the local shell tool call output. Always `local_shell_call_output`. - 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`. + - `agent: optional object { agent_name }` - - `"1024x1024"` + The agent that produced this item. - - `"1024x1536"` + - `agent_name: string` - - `"1536x1024"` + The canonical name of the agent that produced this item. - - `"auto"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `local_shell: object { type }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - A tool that allows the model to execute shell commands in a local environment. + - `"in_progress"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `"completed"` - A tool that allows the model to execute shell commands. + - `"incomplete"` - - `type: "shell"` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - The type of the shell tool. Always `shell`. + A tool call that executes one or more shell commands in a managed environment. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"direct"` + - `action: object { commands, max_output_length, timeout_ms }` - - `"programmatic"` + The shell commands and limits that describe how to run the tool call. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `commands: array of string` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `max_output_length: number` - - `type: "container_auto"` + Optional maximum number of characters to return from each command. - Automatically creates a container for this request + - `timeout_ms: number` - - `file_ids: optional array of string` + Optional timeout in milliseconds for the commands. - An optional list of uploaded files to make available to your code. + - `call_id: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The unique ID of the shell tool call generated by the model. - The memory limit for the container. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `"1g"` + Represents the use of a local environment to perform shell actions. - - `"4g"` + - `beta_response_local_environment: object { type }` - - `"16g"` + Represents the use of a local environment to perform shell actions. - - `"64g"` + - `type: "local"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The environment type. Always `local`. - Network access policy for the container. + - `beta_response_container_reference: object { container_id, type }` - - `beta_container_network_policy_disabled: object { type }` + Represents a container created with /v1/containers. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `container_id: string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `type: "container_reference"` - An optional list of skills referenced by id or inline data. + The environment type. Always `container_reference`. - - `beta_skill_reference: object { skill_id, type, version }` + - `status: "in_progress" or "completed" or "incomplete"` - - `skill_id: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The ID of the referenced skill. + - `"in_progress"` - - `type: "skill_reference"` + - `"completed"` - References a skill created with the /v1/skills endpoint. + - `"incomplete"` - - `version: optional string` + - `type: "shell_call"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The type of the item. Always `shell_call`. - - `beta_inline_skill: object { description, name, source, type }` + - `agent: optional object { agent_name }` - - `description: string` + The agent that produced this item. - The description of the skill. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the skill. + - `caller: optional object { type } or object { caller_id, type }` - - `source: object { data, media_type, type }` + The execution context that produced this tool call. - Inline skill payload + - `direct: object { type }` - - `data: string` + - `program: object { caller_id, type }` - Base64-encoded skill zip bundle. + - `caller_id: string` - - `media_type: "application/zip"` + The call ID of the program item that produced this tool call. - The media type of the inline skill payload. Must be `application/zip`. + - `type: "program"` - - `type: "base64"` + - `created_by: optional string` - The type of the inline skill source. Must be `base64`. + The ID of the entity that created this tool call. - - `type: "inline"` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - Defines an inline skill for this request. + The output of a shell tool call that was emitted. - - `beta_local_environment: object { type, skills }` + - `id: string` - - `type: "local"` + The unique ID of the shell call output. Populated when this item is returned via API. - Use a local computer environment. + - `call_id: string` - - `skills: optional array of BetaLocalSkill` + The unique ID of the shell tool call generated by the model. - An optional list of skills. + - `max_output_length: number` - - `description: string` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The description of the skill. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `name: string` + An array of shell call output contents - The name of the skill. + - `outcome: object { type } or object { exit_code, type }` - - `path: string` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The path to the directory containing the skill. + - `timeout: object { type }` - - `beta_container_reference: object { container_id, type }` + Indicates that the shell call exceeded its configured time limit. - - `container_id: string` + - `exit: object { exit_code, type }` - The ID of the referenced container. + Indicates that the shell commands finished and returned an exit code. - - `type: "container_reference"` + - `exit_code: number` - References a container created with the /v1/containers endpoint + Exit code from the shell process. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `type: "exit"` - 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) + The outcome type. Always `exit`. - - `name: string` + - `stderr: string` - The name of the custom tool, used to identify it in tool calls. + The standard error output that was captured. - - `type: "custom"` + - `stdout: string` - The type of the custom tool. Always `custom`. + The standard output that was captured. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `created_by: optional string` - The tool invocation context(s). + The identifier of the actor that created the item. - - `"direct"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"programmatic"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `defer_loading: optional boolean` + - `"in_progress"` - Whether this tool should be deferred and discovered via tool search. + - `"completed"` - - `description: optional string` + - `"incomplete"` - Optional description of the custom tool, used to provide more context. + - `type: "shell_call_output"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the shell call output. Always `shell_call_output`. - The input format for the custom tool. Default is unconstrained text. + - `agent: optional object { agent_name }` - - `text: object { type }` + The agent that produced this item. - Unconstrained free-form text. + - `agent_name: string` - - `grammar: object { definition, syntax, type }` + The canonical name of the agent that produced this item. - A grammar defined by the user. + - `caller: optional object { type } or object { caller_id, type }` - - `definition: string` + The execution context that produced this tool call. - The grammar definition. + - `direct: object { type }` - - `syntax: "lark" or "regex"` + - `program: object { caller_id, type }` - The syntax of the grammar definition. One of `lark` or `regex`. + - `caller_id: string` - - `"lark"` + The call ID of the program item that produced this tool call. - - `"regex"` + - `type: "program"` - - `type: "grammar"` + - `created_by: optional string` - Grammar format. Always `grammar`. + The identifier of the actor that created the item. - - `beta_namespace_tool: object { description, name, tools, type }` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - Groups function/custom tools under a shared namespace. + A tool call that applies file diffs by creating, deleting, or updating files. - - `description: string` + - `id: string` - A description of the namespace shown to the model. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `name: string` + - `call_id: string` - The namespace name used in tool calls (for example, `crm`). + The unique ID of the apply patch tool call generated by the model. - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The function/custom tools available inside this namespace. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `function: object { name, type, allowed_callers, 5 more }` + - `create_file: object { diff, path, type }` - - `name: string` + Instruction describing how to create a file via the apply_patch tool. - - `type: "function"` + - `diff: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Diff to apply. - The tool invocation context(s). + - `path: string` - - `"direct"` + Path of the file to create. - - `"programmatic"` + - `type: "create_file"` - - `defer_loading: optional boolean` + Create a new file with the provided diff. - Whether this function should be deferred and discovered via tool search. + - `delete_file: object { path, type }` - - `description: optional string` + Instruction describing how to delete a file via the apply_patch tool. - - `output_schema: optional map[unknown]` + - `path: string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Path of the file to delete. - - `parameters: optional unknown` + - `type: "delete_file"` - - `strict: optional boolean` + Delete the specified file. - 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. + - `update_file: object { diff, path, type }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Instruction describing how to update a file via the apply_patch tool. - 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) + - `diff: string` - - `name: string` + Diff to apply. - The name of the custom tool, used to identify it in tool calls. + - `path: string` - - `type: "custom"` + Path of the file to update. - The type of the custom tool. Always `custom`. + - `type: "update_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Update an existing file with the provided diff. - The tool invocation context(s). + - `status: "in_progress" or "completed"` - - `defer_loading: optional boolean` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Whether this tool should be deferred and discovered via tool search. + - `"in_progress"` - - `description: optional string` + - `"completed"` - Optional description of the custom tool, used to provide more context. + - `type: "apply_patch_call"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the item. Always `apply_patch_call`. - The input format for the custom tool. Default is unconstrained text. + - `agent: optional object { agent_name }` - - `type: "namespace"` + The agent that produced this item. - The type of the tool. Always `namespace`. + - `agent_name: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The canonical name of the agent that produced this item. - Hosted or BYOT tool search configuration for deferred tools. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "tool_search"` + The execution context that produced this tool call. - The type of the tool. Always `tool_search`. + - `direct: object { type }` - - `description: optional string` + - `program: object { caller_id, type }` - Description shown to the model for a client-executed tool search tool. + - `caller_id: string` - - `execution: optional "server" or "client"` + The call ID of the program item that produced this tool call. - Whether tool search is executed by the server or by the client. + - `type: "program"` - - `"server"` + - `created_by: optional string` - - `"client"` + The ID of the entity that created this tool call. - - `parameters: optional unknown` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - Parameter schema for a client-executed tool search tool. + The output emitted by an apply patch tool call. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `id: string` - 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). + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `call_id: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The unique ID of the apply patch tool call generated by the model. - - `"web_search_preview"` + - `status: "completed" or "failed"` - - `"web_search_preview_2025_03_11"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `search_content_types: optional array of "text" or "image"` + - `"completed"` - - `"text"` + - `"failed"` - - `"image"` + - `type: "apply_patch_call_output"` - - `search_context_size: optional "low" or "medium" or "high"` + The type of the item. Always `apply_patch_call_output`. - 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. + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"medium"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `user_location: optional object { type, city, country, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` - The user's location. + The execution context that produced this tool call. - - `type: "approximate"` + - `direct: object { type }` - The type of location approximation. Always `approximate`. + - `program: object { caller_id, type }` - - `city: optional string` + - `caller_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + The call ID of the program item that produced this tool call. - - `country: optional string` + - `type: "program"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `created_by: optional string` - - `region: optional string` + The ID of the entity that created this tool call output. - Free text input for the region of the user, e.g. `California`. + - `output: optional string` - - `timezone: optional string` + Optional textual output returned by the apply patch tool. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `mcp_call: object { id, arguments, name, 7 more }` - - `beta_apply_patch_tool: object { type, allowed_callers }` + An invocation of a tool on an MCP server. - Allows the assistant to create, delete, or update files using unified diffs. + - `id: string` - - `type: "apply_patch"` + The unique ID of the tool call. - The type of the tool. Always `apply_patch`. + - `arguments: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + A JSON string of the arguments passed to the tool. - The tool invocation context(s). + - `name: string` - - `"direct"` + The name of the tool that was run. - - `"programmatic"` + - `server_label: string` - - `type: "tool_search_output"` + The label of the MCP server running the tool. - The type of the item. Always `tool_search_output`. + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` @@ -36815,107 +47756,104 @@ Compact a response The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `approval_request_id: optional string` - - `additional_tools: object { id, role, tools, 2 more }` + 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. - - `id: string` + - `error: optional string` - The unique ID of the additional tools item. + The error from the tool call, if any. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `output: optional string` - The role that provided the additional tools. + The output from the tool call. - - `"unknown"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"user"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"assistant"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"critic"` + - `"incomplete"` - - `"discriminator"` + - `"calling"` - - `"developer"` + - `"failed"` - - `"tool"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `tools: array of BetaTool` + A list of tools available on an MCP server. - The additional tool definitions made available at this item. + - `id: string` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The unique ID of the list. - 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). + - `server_label: string` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The label of the MCP server. - 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). + - `tools: array of object { input_schema, name, annotations, description }` - - `beta_computer_tool: object { type }` + The tools available on the server. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `input_schema: unknown` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The JSON schema describing the tool's input. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `name: string` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The name of the tool. - 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). + - `annotations: optional unknown` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + Additional annotations about the tool. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `description: optional string` - - `code_interpreter: object { container, type, allowed_callers }` + The description of the tool. - A tool that runs Python code to help generate a response to a prompt. + - `type: "mcp_list_tools"` - - `programmatic_tool_calling: object { type }` + The type of the item. Always `mcp_list_tools`. - - `image_generation: object { type, action, background, 9 more }` + - `agent: optional object { agent_name }` - A tool that generates images using the GPT image models. + The agent that produced this item. - - `local_shell: object { type }` + - `agent_name: string` - A tool that allows the model to execute shell commands in a local environment. + The canonical name of the agent that produced this item. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `error: optional string` - A tool that allows the model to execute shell commands. + Error message if the server could not list tools. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - 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) + A request for human approval of a tool invocation. - - `beta_namespace_tool: object { description, name, tools, type }` + - `id: string` - Groups function/custom tools under a shared namespace. + The unique ID of the approval request. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `arguments: string` - Hosted or BYOT tool search configuration for deferred tools. + A JSON string of arguments for the tool. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `name: string` - 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). + The name of the tool to run. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `server_label: string` - Allows the assistant to create, delete, or update files using unified diffs. + The label of the MCP server making the request. - - `type: "additional_tools"` + - `type: "mcp_approval_request"` - The type of the item. Always `additional_tools`. + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` @@ -36925,21 +47863,25 @@ Compact a response The canonical name of the agent that produced this item. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A response to an MCP approval request. - `id: string` - The unique ID of the compaction item. + The unique ID of the approval response - - `encrypted_content: string` + - `approval_request_id: string` - The encrypted content that was produced by compaction. + The ID of the approval request being answered. - - `type: "compaction"` + - `approve: boolean` - The type of the item. Always `compaction`. + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. - `agent: optional object { agent_name }` @@ -36949,717 +47891,824 @@ Compact a response The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `image_generation_call: object { id, result, status, 2 more }` + - `reason: optional string` - An image generation request made by the model. + Optional reason for the decision. - - `id: string` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - The unique ID of the image generation call. + A call to a custom tool created by the model. - - `result: string` + - `call_id: string` - The generated image encoded in base64. + An identifier used to map this custom tool call to a tool call output. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `input: string` - The status of the image generation call. + The input for the custom tool call generated by the model. - - `"in_progress"` + - `name: string` - - `"completed"` + The name of the custom tool being called. - - `"generating"` + - `type: "custom_tool_call"` - - `"failed"` + The type of the custom tool call. Always `custom_tool_call`. - - `type: "image_generation_call"` + - `id: optional string` - The type of the image generation call. Always `image_generation_call`. + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. + - `caller: optional object { type } or object { caller_id, type }` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + The execution context that produced this tool call. - A tool call to run code. + - `namespace: optional string` - - `id: string` + The namespace of the custom tool being called. - The unique ID of the code interpreter tool call. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `code: string` + The output of a custom tool call from your code, being sent back to the model. - The code to run, or null if not available. + - `id: string` - - `container_id: string` + The unique ID of the custom tool call output item. - The ID of the container used to run the code. + - `status: "in_progress" or "completed" or "incomplete"` - - `outputs: array of object { logs, type } or object { type, url }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"in_progress"` - - `logs: object { logs, type }` + - `"completed"` - The logs output from the code interpreter. + - `"incomplete"` - - `logs: string` + - `created_by: optional string` - The logs output from the code interpreter. + The identifier of the actor that created the item. - - `type: "logs"` + - `parallel_tool_calls: boolean` - The type of the output. Always `logs`. + Whether to allow the model to run tool calls in parallel. - - `image: object { type, url }` + - `temperature: number` - The image output from the code interpreter. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `type: "image"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The type of the output. Always `image`. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `url: string` + - `beta_tool_choice_options: "none" or "auto" or "required"` - The URL of the image output from the code interpreter. + Controls which (if any) tool is called by the model. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + `none` means the model will not call any tool and instead generates a message. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `"in_progress"` + `required` means the model must call one or more tools. - - `"completed"` + - `"none"` - - `"incomplete"` + - `"auto"` - - `"interpreting"` + - `"required"` - - `"failed"` + - `beta_tool_choice_allowed: object { mode, tools, type }` - - `type: "code_interpreter_call"` + Constrains the tools available to the model to a pre-defined set. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `mode: "auto" or "required"` - - `agent: optional object { agent_name }` + Constrains the tools available to the model to a pre-defined set. - The agent that produced this item. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `agent_name: string` + `required` requires the model to call one or more of the allowed tools. - The canonical name of the agent that produced this item. + - `"auto"` - - `local_shell_call: object { id, action, call_id, 3 more }` + - `"required"` - A tool call to run a command on the local shell. + - `tools: array of map[unknown]` - - `id: string` + A list of tool definitions that the model should be allowed to call. - The unique ID of the local shell call. + For the Responses API, the list of tool definitions might look like: - - `action: object { command, env, type, 3 more }` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - Execute a shell command on the server. + - `type: "allowed_tools"` - - `command: array of string` + Allowed tool configuration type. Always `allowed_tools`. - The command to run. + - `beta_tool_choice_types: object { type }` - - `env: map[string]` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - Environment variables to set for the command. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `type: "exec"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The type of the local shell action. Always `exec`. + Allowed values are: - - `timeout_ms: optional number` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - Optional timeout in milliseconds for the command. + - `"file_search"` - - `user: optional string` + - `"web_search_preview"` - Optional user to run the command as. + - `"computer"` - - `working_directory: optional string` + - `"computer_use_preview"` - Optional working directory to run the command in. + - `"computer_use"` - - `call_id: string` + - `"web_search_preview_2025_03_11"` - The unique ID of the local shell tool call generated by the model. + - `"image_generation"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"code_interpreter"` - The status of the local shell call. + - `beta_tool_choice_function: object { name, type }` - - `"in_progress"` + Use this option to force the model to call a specific function. - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the function to call. - - `type: "local_shell_call"` + - `type: "function"` - The type of the local shell call. Always `local_shell_call`. + For function calling, the type is always `function`. - - `agent: optional object { agent_name }` + - `beta_tool_choice_mcp: object { server_label, type, name }` - The agent that produced this item. + Use this option to force the model to call a specific tool on a remote MCP server. - - `agent_name: string` + - `server_label: string` - The canonical name of the agent that produced this item. + The label of the MCP server to use. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `type: "mcp"` - The output of a local shell tool call. + For MCP tools, the type is always `mcp`. - - `id: string` + - `name: optional string` - The unique ID of the local shell tool call generated by the model. + The name of the tool to call on the server. - - `output: string` + - `beta_tool_choice_custom: object { name, type }` - A JSON string of the output of the local shell tool call. + Use this option to force the model to call a specific custom tool. - - `type: "local_shell_call_output"` + - `name: string` - The type of the local shell tool call output. Always `local_shell_call_output`. + The name of the custom tool to call. - - `agent: optional object { agent_name }` + - `type: "custom"` - The agent that produced this item. + For custom tool calling, the type is always `custom`. - - `agent_name: string` + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - The canonical name of the agent that produced this item. + - `beta_tool_choice_apply_patch: object { type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + Forces the model to call the apply_patch tool when executing a tool call. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `type: "apply_patch"` - - `"in_progress"` + The tool to call. Always `apply_patch`. - - `"completed"` + - `beta_tool_choice_shell: object { type }` - - `"incomplete"` + Forces the model to call the shell tool when a tool call is required. - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `type: "shell"` - A tool call that executes one or more shell commands in a managed environment. + The tool to call. Always `shell`. - - `id: string` + - `tools: array of BetaTool` - The unique ID of the shell tool call. Populated when this item is returned via API. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `action: object { commands, max_output_length, timeout_ms }` + We support the following categories of tools: - The shell commands and limits that describe how to run the tool call. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `commands: array of string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `max_output_length: number` + 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). - Optional maximum number of characters to return from each command. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `timeout_ms: number` + 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). - Optional timeout in milliseconds for the commands. + - `beta_computer_tool: object { type }` - - `call_id: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The unique ID of the shell tool call generated by the model. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Represents the use of a local environment to perform shell actions. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `beta_response_local_environment: object { type }` + 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). - Represents the use of a local environment to perform shell actions. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `type: "local"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The environment type. Always `local`. + - `code_interpreter: object { container, type, allowed_callers }` - - `beta_response_container_reference: object { container_id, type }` + A tool that runs Python code to help generate a response to a prompt. - Represents a container created with /v1/containers. + - `programmatic_tool_calling: object { type }` - - `container_id: string` + - `image_generation: object { type, action, background, 9 more }` - - `type: "container_reference"` + A tool that generates images using the GPT image models. - The environment type. Always `container_reference`. + - `local_shell: object { type }` - - `status: "in_progress" or "completed" or "incomplete"` + A tool that allows the model to execute shell commands in a local environment. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"in_progress"` + A tool that allows the model to execute shell commands. - - `"completed"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"incomplete"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: "shell_call"` + - `beta_namespace_tool: object { description, name, tools, type }` - The type of the item. Always `shell_call`. + Groups function/custom tools under a shared namespace. - - `agent: optional object { agent_name }` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The agent that produced this item. + Hosted or BYOT tool search configuration for deferred tools. - - `agent_name: string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The canonical name of the agent that produced this item. + 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). - - `caller: optional object { type } or object { caller_id, type }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The execution context that produced this tool call. + Allows the assistant to create, delete, or update files using unified diffs. - - `direct: object { type }` + - `top_p: number` - - `program: object { caller_id, type }` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `caller_id: string` + We generally recommend altering this or `temperature` but not both. - The call ID of the program item that produced this tool call. + - `background: optional boolean` - - `type: "program"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `created_by: optional string` + - `completed_at: optional number` - The ID of the entity that created this tool call. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `conversation: optional object { id }` - The output of a shell tool call that was emitted. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - `id: string` - The unique ID of the shell call output. Populated when this item is returned via API. + The unique ID of the conversation that this response was associated with. - - `call_id: string` + - `max_output_tokens: optional number` - The unique ID of the shell tool call generated by the model. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `max_output_length: number` + - `max_tool_calls: optional number` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `moderation: optional object { input, output }` - An array of shell call output contents + Moderation results for the response input and output, if moderated completions were requested. - - `outcome: object { type } or object { exit_code, type }` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + Moderation for the response input. - - `timeout: object { type }` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - Indicates that the shell call exceeded its configured time limit. + A moderation result produced for the response input or output. - - `exit: object { exit_code, type }` + - `categories: map[boolean]` - Indicates that the shell commands finished and returned an exit code. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `exit_code: number` + - `category_applied_input_types: map[array of "text" or "image"]` - Exit code from the shell process. + Which modalities of input are reflected by the score for each category. - - `type: "exit"` + - `"text"` - The outcome type. Always `exit`. + - `"image"` - - `stderr: string` + - `category_scores: map[number]` - The standard error output that was captured. + A dictionary of moderation categories to scores. - - `stdout: string` + - `flagged: boolean` - The standard output that was captured. + A boolean indicating whether the content was flagged by any category. - - `created_by: optional string` + - `model: string` - The identifier of the actor that created the item. + The moderation model that produced this result. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "moderation_result"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The object type, which was always `moderation_result` for successful moderation results. - - `"in_progress"` + - `error: object { code, message, type }` - - `"completed"` + An error produced while attempting moderation for the response input or output. - - `"incomplete"` + - `code: string` - - `type: "shell_call_output"` + The error code. - The type of the shell call output. Always `shell_call_output`. + - `message: string` - - `agent: optional object { agent_name }` + The error message. - The agent that produced this item. + - `type: "error"` - - `agent_name: string` + The object type, which was always `error` for moderation failures. - The canonical name of the agent that produced this item. + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `caller: optional object { type } or object { caller_id, type }` + Moderation for the response output. - The execution context that produced this tool call. + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `direct: object { type }` + A moderation result produced for the response input or output. - - `program: object { caller_id, type }` + - `categories: map[boolean]` - - `caller_id: string` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The call ID of the program item that produced this tool call. + - `category_applied_input_types: map[array of "text" or "image"]` - - `type: "program"` + Which modalities of input are reflected by the score for each category. - - `created_by: optional string` + - `"text"` - The identifier of the actor that created the item. + - `"image"` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `category_scores: map[number]` - A tool call that applies file diffs by creating, deleting, or updating files. + A dictionary of moderation categories to scores. - - `id: string` + - `flagged: boolean` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + A boolean indicating whether the content was flagged by any category. - - `call_id: string` + - `model: string` - The unique ID of the apply patch tool call generated by the model. + The moderation model that produced this result. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `type: "moderation_result"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The object type, which was always `moderation_result` for successful moderation results. - - `create_file: object { diff, path, type }` + - `error: object { code, message, type }` - Instruction describing how to create a file via the apply_patch tool. + An error produced while attempting moderation for the response input or output. - - `diff: string` + - `code: string` - Diff to apply. + The error code. - - `path: string` + - `message: string` - Path of the file to create. + The error message. - - `type: "create_file"` + - `type: "error"` - Create a new file with the provided diff. + The object type, which was always `error` for moderation failures. - - `delete_file: object { path, type }` + - `previous_response_id: optional string` - Instruction describing how to delete a file via the apply_patch tool. + 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`. - - `path: string` + - `prompt: optional object { id, variables, version }` - Path of the file to delete. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `type: "delete_file"` + - `id: string` - Delete the specified file. + The unique identifier of the prompt template to use. - - `update_file: object { diff, path, type }` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - Instruction describing how to update a file via the apply_patch tool. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `diff: string` + - `union_member_0: string` - Diff to apply. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `path: string` + A text input to the model. - Path of the file to update. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `type: "update_file"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Update an existing file with the provided diff. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `status: "in_progress" or "completed"` + A file input to the model. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `version: optional string` - - `"in_progress"` + Optional version of the prompt template. - - `"completed"` + - `prompt_cache_key: optional string` - - `type: "apply_patch_call"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The type of the item. Always `apply_patch_call`. + - `prompt_cache_options: optional object { mode, ttl }` - - `agent: optional object { agent_name }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The agent that produced this item. + - `mode: "implicit" or "explicit"` - - `agent_name: string` + Whether implicit prompt-cache breakpoints were enabled. - The canonical name of the agent that produced this item. + - `"implicit"` - - `caller: optional object { type } or object { caller_id, type }` + - `"explicit"` - The execution context that produced this tool call. + - `ttl: "30m"` - - `direct: object { type }` + The minimum lifetime applied to each cache breakpoint. - - `program: object { caller_id, type }` + - `"30m"` - - `caller_id: string` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The call ID of the program item that produced this tool call. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `type: "program"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `created_by: optional string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The ID of the entity that created this tool call. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `"in_memory"` - The output emitted by an apply patch tool call. + - `"24h"` - - `id: string` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + **gpt-5 and o-series models only** - - `call_id: string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The unique ID of the apply patch tool call generated by the model. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `status: "completed" or "failed"` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"auto"` - - `"completed"` + - `"current_turn"` - - `"failed"` + - `"all_turns"` - - `type: "apply_patch_call_output"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - The type of the item. Always `apply_patch_call_output`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `agent: optional object { agent_name }` + - `"none"` - The agent that produced this item. + - `"minimal"` - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `caller: optional object { type } or object { caller_id, type }` + - `"high"` - The execution context that produced this tool call. + - `"xhigh"` - - `direct: object { type }` + - `"max"` - - `program: object { caller_id, type }` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `caller_id: string` + **Deprecated:** use `summary` instead. - The call ID of the program item that produced this tool call. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `type: "program"` + - `"auto"` - - `created_by: optional string` + - `"concise"` - The ID of the entity that created this tool call output. + - `"detailed"` - - `output: optional string` + - `mode: optional string or "standard" or "pro"` - Optional textual output returned by the apply patch tool. + Controls the reasoning execution mode for the request. - - `mcp_call: object { id, arguments, name, 7 more }` + When returned on a response, this is the effective execution mode. - An invocation of a tool on an MCP server. + - `"standard"` - - `id: string` + - `"pro"` - The unique ID of the tool call. + - `summary: optional "auto" or "concise" or "detailed"` - - `arguments: string` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - A JSON string of the arguments passed to the tool. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `name: string` + - `"auto"` - The name of the tool that was run. + - `"concise"` - - `server_label: string` + - `"detailed"` - The label of the MCP server running the tool. + - `safety_identifier: optional string` - - `type: "mcp_call"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The type of the item. Always `mcp_call`. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `agent: optional object { agent_name }` + Specifies the processing type used for serving the request. - The agent that produced this item. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `agent_name: string` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The canonical name of the agent that produced this item. + - `"auto"` - - `approval_request_id: optional string` + - `"default"` - 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. + - `"flex"` - - `error: optional string` + - `"scale"` - The error from the tool call, if any. + - `"priority"` - - `output: optional string` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - The output from the tool call. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"completed"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"failed"` - `"in_progress"` - - `"completed"` + - `"cancelled"` + + - `"queued"` - `"incomplete"` - - `"calling"` + - `text: optional object { format, verbosity }` - - `"failed"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - A list of tools available on an MCP server. + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - `id: string` + An object specifying the format that the model must output. - The unique ID of the list. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `server_label: string` + The default format is `{ "type": "text" }` with no additional options. - The label of the MCP server. + **Not recommended for gpt-4o and newer models:** - - `tools: array of object { input_schema, name, annotations, description }` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - The tools available on the server. + - `text: object { type }` - - `input_schema: unknown` + Default response format. Used to generate text responses. - The JSON schema describing the tool's input. + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `name: string` - The name of the tool. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `annotations: optional unknown` + - `schema: map[unknown]` - Additional annotations about the tool. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. - `description: optional string` - The description of the tool. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "mcp_list_tools"` + - `strict: optional boolean` - The type of the item. Always `mcp_list_tools`. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `agent: optional object { agent_name }` + - `json_object: object { type }` - The agent that produced this item. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `agent_name: string` + - `verbosity: optional "low" or "medium" or "high"` - The canonical name of the agent that produced this item. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `error: optional string` + - `"low"` - Error message if the server could not list tools. + - `"medium"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `"high"` - A request for human approval of a tool invocation. + - `top_logprobs: optional number` - - `id: string` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The unique ID of the approval request. + - `truncation: optional "auto" or "disabled"` - - `arguments: string` + The truncation strategy to use for the model response. - A JSON string of arguments for the tool. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `name: string` + - `"auto"` - The name of the tool to run. + - `"disabled"` - - `server_label: string` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - The label of the MCP server making the request. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `type: "mcp_approval_request"` + - `input_tokens: number` - The type of the item. Always `mcp_approval_request`. + The number of input tokens. - - `agent: optional object { agent_name }` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The agent that produced this item. + A detailed breakdown of the input tokens. - - `agent_name: string` + - `cache_write_tokens: number` - The canonical name of the agent that produced this item. + The number of input tokens that were written to the cache. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `cached_tokens: number` - A response to an MCP approval request. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `id: string` + - `output_tokens: number` - The unique ID of the approval response + The number of output tokens. - - `approval_request_id: string` + - `output_tokens_details: object { reasoning_tokens }` - The ID of the approval request being answered. + A detailed breakdown of the output tokens. - - `approve: boolean` + - `reasoning_tokens: number` - Whether the request was approved. + The number of reasoning tokens. - - `type: "mcp_approval_response"` + - `total_tokens: number` - The type of the item. Always `mcp_approval_response`. + The total number of tokens used. + + - `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `sequence_number: number` + + The sequence number for this event. + + - `type: "response.created"` + + The type of the event. Always `response.created`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `reason: optional string` - - Optional reason for the decision. +### Beta Response Custom Tool Call - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` +- `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` A call to a custom tool created by the model. @@ -37709,332 +48758,266 @@ Compact a response The namespace of the custom tool being called. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` +### Beta Response Custom Tool Call Input Delta Event - The output of a custom tool call from your code, being sent back to the model. +- `beta_response_custom_tool_call_input_delta_event: object { delta, item_id, output_index, 3 more }` - - `id: string` + Event representing a delta (partial update) to the input of a custom tool call. - The unique ID of the custom tool call output item. + - `delta: string` - - `status: "in_progress" or "completed" or "incomplete"` + The incremental input data (delta) for the custom tool call. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `item_id: string` - - `"in_progress"` + Unique identifier for the API item associated with this event. - - `"completed"` + - `output_index: number` - - `"incomplete"` + The index of the output this delta applies to. - - `created_by: optional string` + - `sequence_number: number` - The identifier of the actor that created the item. + The sequence number of this event. - - `usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `type: "response.custom_tool_call_input.delta"` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + The event type identifier. - - `input_tokens: number` + - `agent: optional object { agent_name }` - The number of input tokens. + The agent that owns this multi-agent streaming event. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `agent_name: string` - A detailed breakdown of the input tokens. + The canonical name of the agent that produced this item. - - `cache_write_tokens: number` +### Beta Response Custom Tool Call Input Done Event - The number of input tokens that were written to the cache. +- `beta_response_custom_tool_call_input_done_event: object { input, item_id, output_index, 3 more }` - - `cached_tokens: number` + Event indicating that input for a custom tool call is complete. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `input: string` - - `output_tokens: number` + The complete input data for the custom tool call. - The number of output tokens. + - `item_id: string` - - `output_tokens_details: object { reasoning_tokens }` + Unique identifier for the API item associated with this event. - A detailed breakdown of the output tokens. + - `output_index: number` - - `reasoning_tokens: number` + The index of the output this event applies to. - The number of reasoning tokens. + - `sequence_number: number` - - `total_tokens: number` + The sequence number of this event. - The total number of tokens used. + - `type: "response.custom_tool_call_input.done"` -### Example + The event type identifier. -```cli -openai beta:responses compact \ - --api-key 'My API Key' \ - --model gpt-5.6-sol -``` + - `agent: optional object { agent_name }` -#### Response + The agent that owns this multi-agent streaming event. -```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 - } -} -``` + - `agent_name: string` -## Domain Types + The canonical name of the agent that produced this item. -### Beta Apply Patch Tool +### Beta Response Custom Tool Call Item -- `beta_apply_patch_tool: object { type, allowed_callers }` +- `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` - Allows the assistant to create, delete, or update files using unified diffs. + A call to a custom tool created by the model. - - `type: "apply_patch"` + - `id: string` - The type of the tool. Always `apply_patch`. + The unique ID of the custom tool call item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: "in_progress" or "completed" or "incomplete"` - The tool invocation context(s). + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"completed"` -### Beta Compacted Response + - `"incomplete"` -- `beta_compacted_response: object { id, created_at, object, 2 more }` + - `created_by: optional string` - - `id: string` + The identifier of the actor that created the item. - The unique identifier for the compacted response. +### Beta Response Custom Tool Call Output - - `created_at: number` +- `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - Unix timestamp (in seconds) when the compacted conversation was created. + The output of a custom tool call from your code, being sent back to the model. - - `object: "response.compaction"` + - `call_id: string` - The object type. Always `response.compaction`. + The call ID, used to map this custom tool call output to a custom tool call. - - `output: array of BetaResponseOutputItem` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `string output: string` - An output message from the model. + A string of the output of the custom tool call. - - `id: string` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The unique ID of the output message. + Text, image, or file output of the custom tool call. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The content of the output message. + A text input to the model. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `text: string` - A text output from the model. + The text input to the model. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `type: "input_text"` - The annotations of the text output. + The type of the input item. Always `input_text`. - - `file_citation: object { file_id, filename, index, type }` + - `prompt_cache_breakpoint: optional object { mode }` - A citation to a file. + 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. - - `file_id: string` + - `mode: "explicit"` - The ID of the file. + The breakpoint mode. Always `explicit`. - - `filename: string` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The filename of the file cited. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `index: number` + - `detail: "low" or "high" or "auto" or "original"` - The index of the file in the list of files. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "file_citation"` + - `"low"` - The type of the file citation. Always `file_citation`. + - `"high"` - - `url_citation: object { end_index, start_index, title, 2 more }` + - `"auto"` - A citation for a web resource used to generate a model response. + - `"original"` - - `end_index: number` + - `type: "input_image"` - The index of the last character of the URL citation in the message. + The type of the input item. Always `input_image`. - - `start_index: number` + - `file_id: optional string` - The index of the first character of the URL citation in the message. + The ID of the file to be sent to the model. - - `title: string` + - `image_url: optional string` - The title of the web resource. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: "url_citation"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the URL citation. Always `url_citation`. + 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. - - `url: string` + - `mode: "explicit"` - The URL of the web resource. + The breakpoint mode. Always `explicit`. - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - A citation for a container file used to generate a model response. + A file input to the model. - - `container_id: string` + - `type: "input_file"` - The ID of the container file. + The type of the input item. Always `input_file`. - - `end_index: number` + - `detail: optional "auto" or "low" or "high"` - The index of the last character of the container file citation in the message. + 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`. - - `file_id: string` + - `"auto"` - The ID of the file. + - `"low"` - - `filename: string` + - `"high"` - The filename of the container file cited. + - `file_data: optional string` - - `start_index: number` + The content of the file to be sent to the model. - The index of the first character of the container file citation in the message. + - `file_id: optional string` - - `type: "container_file_citation"` + The ID of the file to be sent to the model. - The type of the container file citation. Always `container_file_citation`. + - `file_url: optional string` - - `file_path: object { file_id, index, type }` + The URL of the file to be sent to the model. - A path to a file. + - `filename: optional string` - - `file_id: string` + The name of the file to be sent to the model. - The ID of the file. + - `prompt_cache_breakpoint: optional object { mode }` - - `index: number` + 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. - The index of the file in the list of files. + - `mode: "explicit"` - - `type: "file_path"` + The breakpoint mode. Always `explicit`. - The type of the file path. Always `file_path`. + - `type: "custom_tool_call_output"` - - `text: string` + The type of the custom tool call output. Always `custom_tool_call_output`. - The text output from the model. + - `id: optional string` - - `type: "output_text"` + The unique ID of the custom tool call output in the OpenAI platform. - The type of the output text. Always `output_text`. + - `agent: optional object { agent_name }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The agent that produced this item. - - `token: string` + - `agent_name: string` - - `bytes: array of number` + The canonical name of the agent that produced this item. - - `logprob: number` + - `caller: optional object { type } or object { caller_id, type }` - - `top_logprobs: array of object { token, bytes, logprob }` + The execution context that produced this tool call. - - `token: string` + - `direct: object { type }` - - `bytes: array of number` + - `program: object { caller_id, type }` - - `logprob: number` + - `caller_id: string` - - `beta_response_output_refusal: object { refusal, type }` + The call ID of the program item that produced this tool call. - A refusal from the model. + - `type: "program"` - - `refusal: string` + The caller type. Always `program`. - The refusal explanation from the model. +### Beta Response Custom Tool Call Output Item - - `type: "refusal"` +- `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - The type of the refusal. Always `refusal`. + The output of a custom tool call from your code, being sent back to the model. - - `role: "assistant"` + - `id: string` - The role of the output message. Always `assistant`. + The unique ID of the custom tool call output item. - `status: "in_progress" or "completed" or "incomplete"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -38042,184 +49025,215 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "message"` + - `created_by: optional string` - The type of the output message. Always `message`. + The identifier of the actor that created the item. - - `agent: optional object { agent_name }` +### Beta Response Error - The agent that produced this item. +- `beta_response_error: object { code, message }` - - `agent_name: string` + An error object returned when the model fails to generate a Response. - The canonical name of the agent that produced this item. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `phase: optional "commentary"` + The error code for the response. - 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. + - `"server_error"` - - `"commentary"` + - `"rate_limit_exceeded"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `"invalid_prompt"` - 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. + - `"bio_policy"` - - `id: string` + - `"vector_store_timeout"` - The unique ID of the file search tool call. + - `"invalid_image"` - - `queries: array of string` + - `"invalid_image_format"` - The queries used to search for files. + - `"invalid_base64_image"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"invalid_image_url"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"image_too_large"` - - `"in_progress"` + - `"image_too_small"` - - `"searching"` + - `"image_parse_error"` - - `"completed"` + - `"image_content_policy_violation"` - - `"incomplete"` + - `"invalid_image_mode"` - - `"failed"` + - `"image_file_too_large"` - - `type: "file_search_call"` + - `"unsupported_image_media_type"` - The type of the file search tool call. Always `file_search_call`. + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: string` + + A human-readable description of the error. + +### Beta Response Error Event + +- `beta_response_error_event: object { code, message, param, 3 more }` + + Emitted when an error occurs. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `param: string` + + The error parameter. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "error"` + + The type of the event. Always `error`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. +### Beta Response Failed Event - - `attributes: optional map[string or number or boolean]` +- `beta_response_failed_event: object { response, sequence_number, type, agent }` - 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. + An event that is emitted when a response fails. - - `union_member_0: string` + - `response: object { id, created_at, error, 31 more }` - - `union_member_1: number` + The response that failed. - - `union_member_2: boolean` + - `id: string` - - `file_id: optional string` + Unique identifier for this Response. - The unique ID of the file. + - `created_at: number` - - `filename: optional string` + Unix timestamp (in seconds) of when this Response was created. - The name of the file. + - `error: object { code, message }` - - `score: optional number` + An error object returned when the model fails to generate a Response. - The relevance score of the file - a value between 0 and 1. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `text: optional string` + The error code for the response. - The text that was retrieved from the file. + - `"server_error"` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `"rate_limit_exceeded"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"invalid_prompt"` - - `arguments: string` + - `"bio_policy"` - A JSON string of the arguments to pass to the function. + - `"vector_store_timeout"` - - `call_id: string` + - `"invalid_image"` - The unique ID of the function tool call generated by the model. + - `"invalid_image_format"` - - `name: string` + - `"invalid_base64_image"` - The name of the function to run. + - `"invalid_image_url"` - - `type: "function_call"` + - `"image_too_large"` - The type of the function tool call. Always `function_call`. + - `"image_too_small"` - - `id: optional string` + - `"image_parse_error"` - The unique ID of the function tool call. + - `"image_content_policy_violation"` - - `agent: optional object { agent_name }` + - `"invalid_image_mode"` - The agent that produced this item. + - `"image_file_too_large"` - - `agent_name: string` + - `"unsupported_image_media_type"` - The canonical name of the agent that produced this item. + - `"empty_image_file"` - - `caller: optional object { type } or object { caller_id, type }` + - `"failed_to_download_image"` - The execution context that produced this tool call. + - `"image_file_not_found"` - - `direct: object { type }` + - `message: string` - - `program: object { caller_id, type }` + A human-readable description of the error. - - `caller_id: string` + - `incomplete_details: object { reason }` - The call ID of the program item that produced this tool call. + Details about why the response is incomplete. - - `type: "program"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `namespace: optional string` + The reason why the response is incomplete. - The namespace of the function to run. + - `"max_output_tokens"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"content_filter"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `instructions: string or array of BetaResponseInputItem` - - `"in_progress"` + A system (or developer) message inserted into the model's context. - - `"completed"` + When using 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. - - `"incomplete"` + - `union_member_0: string` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + A text input to the model, equivalent to a text input with the + `developer` role. - - `id: string` + - `Input item list: array of BetaResponseInputItem` - The unique ID of the function call tool output. + A list of one or many input items to the model, containing + different content types. - - `call_id: string` + - `beta_easy_input_message: object { content, role, phase, type }` - The unique ID of the function tool call generated by the model. + 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. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `content: string or BetaResponseInputMessageContentList` - The output from the function call generated by your code. - Can be a string or an list of output content. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `string output: string` + - `Text input: string` - A string of the output of the function call. + A text input to the model. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - Text, image, or file output of the function call. + A list of one or many input items to the model, containing different content + types. - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` @@ -38319,268 +49333,255 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: "function_call_output"` - - The type of the function tool call output. Always `function_call_output`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` + - `role: "user" or "assistant" or "system" or "developer"` - The execution context that produced this tool call. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `direct: object { type }` + - `"user"` - - `program: object { caller_id, type }` + - `"assistant"` - - `caller_id: string` + - `"system"` - The call ID of the program item that produced this tool call. + - `"developer"` - - `type: "program"` + - `phase: optional "commentary" or "final_answer"` - The caller type. Always `program`. + 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. - - `created_by: optional string` + - `"commentary"` - The identifier of the actor that created the item. + - `"final_answer"` - - `agent_message: object { id, author, content, 3 more }` + - `type: optional "message"` - - `id: string` + The type of the message input. Always `message`. - The unique ID of the agent message. + - `"message"` - - `author: string` + - `message: object { content, role, agent, 2 more }` - The sending agent identity. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `content: array of BetaResponseInputContent` - Encrypted content sent between agents. + A list of one or many input items to the model, containing different content + types. - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - A text output from the model. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `text: object { text, type }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - A text content. + A file input to the model. - - `text: string` + - `role: "user" or "system" or "developer"` - - `type: "text"` + The role of the message input. One of `user`, `system`, or `developer`. - - `summary_text: object { text, type }` + - `"user"` - A summary text from the model. + - `"system"` - - `text: string` + - `"developer"` - A summary of the reasoning output from the model so far. + - `agent: optional object { agent_name }` - - `type: "summary_text"` + The agent that produced this item. - The type of the object. Always `summary_text`. + - `agent_name: string` - - `reasoning_text: object { text, type }` + The canonical name of the agent that produced this item. - Reasoning text from the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `text: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The reasoning text from the model. + - `"in_progress"` - - `type: "reasoning_text"` + - `"completed"` - The type of the reasoning text. Always `reasoning_text`. + - `"incomplete"` - - `beta_response_output_refusal: object { refusal, type }` + - `type: optional "message"` - A refusal from the model. + The type of the message input. Always set to `message`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"message"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `beta_response_output_message: object { id, content, role, 4 more }` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + An output message from the model. - A screenshot of a computer. + - `id: string` - - `detail: "low" or "high" or "auto" or "original"` + The unique ID of the output message. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"low"` + The content of the output message. - - `"high"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `"auto"` + A text output from the model. - - `"original"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `file_id: string` + The annotations of the text output. - The identifier of an uploaded file that contains the screenshot. + - `file_citation: object { file_id, filename, index, type }` - - `image_url: string` + A citation to a file. - The URL of the screenshot image. + - `file_id: string` - - `type: "computer_screenshot"` + The ID of the file. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `filename: string` - - `prompt_cache_breakpoint: optional object { mode }` + The filename of the file cited. - 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. + - `index: number` - - `mode: "explicit"` + The index of the file in the list of files. - The breakpoint mode. Always `explicit`. + - `type: "file_citation"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The type of the file citation. Always `file_citation`. - A file input to the model. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `encrypted_content: object { encrypted_content, type }` + A citation for a web resource used to generate a model response. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `end_index: number` - - `encrypted_content: string` + The index of the last character of the URL citation in the message. - Opaque encrypted content. + - `start_index: number` - - `type: "encrypted_content"` + The index of the first character of the URL citation in the message. - The type of the input item. Always `encrypted_content`. + - `title: string` - - `recipient: string` + The title of the web resource. - The destination agent identity. + - `type: "url_citation"` - - `type: "agent_message"` + The type of the URL citation. Always `url_citation`. - The type of the item. Always `agent_message`. + - `url: string` - - `agent: optional object { agent_name }` + The URL of the web resource. - The agent that produced this item. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `agent_name: string` + A citation for a container file used to generate a model response. - The canonical name of the agent that produced this item. + - `container_id: string` - - `multi_agent_call: object { id, action, arguments, 3 more }` + The ID of the container file. - - `id: string` + - `end_index: number` - The unique ID of the multi-agent call item. + The index of the last character of the container file citation in the message. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `file_id: string` - The multi-agent action to execute. + The ID of the file. - - `"spawn_agent"` + - `filename: string` - - `"interrupt_agent"` + The filename of the container file cited. - - `"list_agents"` + - `start_index: number` - - `"send_message"` + The index of the first character of the container file citation in the message. - - `"followup_task"` + - `type: "container_file_citation"` - - `"wait_agent"` + The type of the container file citation. Always `container_file_citation`. - - `arguments: string` + - `file_path: object { file_id, index, type }` - The JSON string of arguments generated for the action. + A path to a file. - - `call_id: string` + - `file_id: string` - The unique ID linking this call to its output. + The ID of the file. - - `type: "multi_agent_call"` + - `index: number` - The type of the multi-agent call. Always `multi_agent_call`. + The index of the file in the list of files. - - `agent: optional object { agent_name }` + - `type: "file_path"` - The agent that produced this item. + The type of the file path. Always `file_path`. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + The text output from the model. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `type: "output_text"` - - `id: string` + The type of the output text. Always `output_text`. - The unique ID of the multi-agent call output item. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `token: string` - The multi-agent action that produced this result. + - `bytes: array of number` - - `"spawn_agent"` + - `logprob: number` - - `"interrupt_agent"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `"list_agents"` + - `token: string` - - `"send_message"` + - `bytes: array of number` - - `"followup_task"` + - `logprob: number` - - `"wait_agent"` + - `beta_response_output_refusal: object { refusal, type }` - - `call_id: string` + A refusal from the model. - The unique ID of the multi-agent call. + - `refusal: string` - - `output: array of BetaResponseOutputText` + The refusal explanation from the model. - Text output returned by the multi-agent action. + - `type: "refusal"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The type of the refusal. Always `refusal`. - The annotations of the text output. + - `role: "assistant"` - - `text: string` + The role of the output message. Always `assistant`. - The text output from the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "output_text"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The type of the output text. Always `output_text`. + - `"in_progress"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"completed"` - - `type: "multi_agent_call_output"` + - `"incomplete"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `type: "message"` + + The type of the output message. Always `message`. - `agent: optional object { agent_name }` @@ -38590,99 +49591,89 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_function_web_search: object { id, action, status, 2 more }` - - The results of a web search tool call. See the - [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - - `id: string` - - The unique ID of the web search tool call. - - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - - - `search: object { type, queries, query, sources }` - - Action type "search" - Performs a web search query. - - - `type: "search"` + - `phase: optional "commentary" or "final_answer"` - The action type. + 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. - - `queries: optional array of string` + - `"commentary"` - The search queries. + - `"final_answer"` - - `query: optional string` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The search query. + 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. - - `sources: optional array of object { type, url }` + - `id: string` - The sources used in the search. + The unique ID of the file search tool call. - - `type: "url"` + - `queries: array of string` - The type of source. Always `url`. + The queries used to search for files. - - `url: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The URL of the source. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `open_page: object { type, url }` + - `"in_progress"` - Action type "open_page" - Opens a specific URL from search results. + - `"searching"` - - `type: "open_page"` + - `"completed"` - The action type. + - `"incomplete"` - - `url: optional string` + - `"failed"` - The URL opened by the model. + - `type: "file_search_call"` - - `find_in_page: object { pattern, type, url }` + The type of the file search tool call. Always `file_search_call`. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `agent: optional object { agent_name }` - - `pattern: string` + The agent that produced this item. - The pattern or text to search for within the page. + - `agent_name: string` - - `type: "find_in_page"` + The canonical name of the agent that produced this item. - The action type. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `url: string` + The results of the file search tool call. - The URL of the page searched for the pattern. + - `attributes: optional map[string or number or boolean]` - - `status: "in_progress" or "searching" or "completed" or "failed"` + 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. - The status of the web search tool call. + - `union_member_0: string` - - `"in_progress"` + - `union_member_1: number` - - `"searching"` + - `union_member_2: boolean` - - `"completed"` + - `file_id: optional string` - - `"failed"` + The unique ID of the file. - - `type: "web_search_call"` + - `filename: optional string` - The type of the web search tool call. Always `web_search_call`. + The name of the file. - - `agent: optional object { agent_name }` + - `score: optional number` - The agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `agent_name: string` + - `text: optional string` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` @@ -38948,11 +49939,9 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - - `id: string` + - `computer_call_output: object { call_id, output, type, 4 more }` - The unique ID of the computer call tool output. + The output of a computer tool call. - `call_id: string` @@ -38960,3847 +49949,3237 @@ openai beta:responses compact \ - `output: object { type, file_id, image_url }` - A computer screenshot image used with the computer use tool. - - - `type: "computer_screenshot"` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `file_id: optional string` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: optional string` - - The URL of the screenshot image. - - - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `"completed"` - - - `"incomplete"` - - - `"failed"` - - - `"in_progress"` - - - `type: "computer_call_output"` - - The type of the computer tool call output. Always `computer_call_output`. - - - `acknowledged_safety_checks: optional array of object { id, code, message }` - - The safety checks reported by the API that have been acknowledged by the - developer. - - - `id: string` - - The ID of the pending safety check. - - - `code: optional string` - - The type of the pending safety check. - - - `message: optional string` - - Details about the pending safety check. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). - - - `id: string` - - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - Reasoning summary content. - - - `text: string` - - A summary of the reasoning output from the model so far. - - - `type: "summary_text"` - - The type of the object. Always `summary_text`. - - - `type: "reasoning"` - - The type of the object. Always `reasoning`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `content: optional array of object { text, type }` - - Reasoning text content. - - - `text: string` - - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - - `encrypted_content: optional string` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `program: object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of the program item. - - - `call_id: string` - - The stable call ID of the program item. - - - `code: string` - - The JavaScript source executed by programmatic tool calling. - - - `fingerprint: string` - - Opaque program replay fingerprint that must be round-tripped. - - - `type: "program"` - - The type of the item. Always `program`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `program_output: object { id, call_id, result, 3 more }` - - - `id: string` - - The unique ID of the program output item. - - - `call_id: string` - - The call ID of the program item. - - - `result: string` - - The result produced by the program item. - - - `status: "completed" or "incomplete"` - - The terminal status of the program output item. - - - `"completed"` - - - `"incomplete"` - - - `type: "program_output"` - - The type of the item. Always `program_output`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - - `id: string` - - The unique ID of the tool search call item. - - - `arguments: unknown` - - Arguments used for the tool search call. - - - `call_id: string` - - The unique ID of the tool search call generated by the model. - - - `execution: "server" or "client"` - - Whether tool search was executed by the server or by the client. - - - `"server"` - - - `"client"` - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the tool search call item that was recorded. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: "tool_search_call"` - - The type of the item. Always `tool_search_call`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - - `id: string` - - The unique ID of the tool search output item. - - - `call_id: string` - - The unique ID of the tool search call generated by the model. - - - `execution: "server" or "client"` - - Whether tool search was executed by the server or by the client. - - - `"server"` - - - `"client"` - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the tool search output item that was recorded. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `tools: array of BetaTool` - - The loaded tool definitions returned by tool search. - - - `beta_function_tool: object { name, parameters, strict, 5 more }` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `name: string` - - The name of the function to call. - - - `parameters: map[unknown]` - - A JSON schema object describing the parameters of the function. - - - `strict: boolean` - - Whether strict parameter validation is enforced for this function tool. - - - `type: "function"` - - The type of the function tool. Always `function`. - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this function is deferred and loaded via tool search. - - - `description: optional string` - - A description of the function. Used by the model to determine whether or not to call the function. - - - `output_schema: optional map[unknown]` - - A JSON schema object describing the JSON value encoded in string outputs for this function. - - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `type: "file_search"` - - The type of the file search tool. Always `file_search`. - - - `vector_store_ids: array of string` - - The IDs of the vector stores to search. - - - `filters: optional object { key, type, value } or object { filters, type }` - - A filter to apply. - - - `Comparison Filter: object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of unknown` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `union_member_3: array of unknown` - - - `Compound Filter: object { filters, type }` - - Combine multiple filters using `and` or `or`. - - - `filters: array of object { key, type, value } or unknown` - - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - - `Comparison Filter: object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of unknown` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `union_member_3: array of unknown` - - - `union_member_1: unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - - `max_num_results: optional number` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - Ranking options for search. - - - `hybrid_search: optional object { embedding_weight, text_weight }` - - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - - `embedding_weight: number` - - The weight of the embedding in the reciprocal ranking fusion. - - - `text_weight: number` - - The weight of the text in the reciprocal ranking fusion. - - - `ranker: optional "auto" or "default-2024-11-15"` - - The ranker to use for the file search. - - - `"auto"` - - - `"default-2024-11-15"` - - - `score_threshold: optional number` - - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - - `beta_computer_tool: object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `type: "computer"` - - The type of the computer tool. Always `computer`. - - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `display_height: number` - - The height of the computer display. - - - `display_width: number` - - The width of the computer display. - - - `environment: "windows" or "mac" or "linux" or 2 more` - - The type of computer environment to control. - - - `"windows"` - - - `"mac"` - - - `"linux"` - - - `"ubuntu"` - - - `"browser"` - - - `type: "computer_use_preview"` - - The type of the computer use tool. Always `computer_use_preview`. - - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `type: "web_search" or "web_search_2025_08_26"` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - - `"web_search"` - - - `"web_search_2025_08_26"` - - - `filters: optional object { allowed_domains }` - - Filters for the search. - - - `allowed_domains: optional array of string` - - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - - - `search_context_size: optional "low" or "medium" or "high"` - - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` - - Free text input for the city of the user, e.g. `San Francisco`. - - - `country: optional string` - - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - - `region: optional string` - - Free text input for the region of the user, e.g. `California`. - - - `timezone: optional string` - - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - - `type: optional "approximate"` - - The type of location approximation. Always `approximate`. - - - `"approximate"` - - - `mcp: object { server_label, type, allowed_callers, 9 more }` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - - `server_label: string` - - A label for this MCP server, used to identify it in tool calls. - - - `type: "mcp"` - - The type of the MCP tool. Always `mcp`. - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `allowed_tools: optional array of string or object { read_only, tool_names }` - - List of allowed tool names or a filter object. - - - `MCP allowed tools: array of string` - - A string array of allowed tool names - - - `MCP tool filter: object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` + A computer screenshot image used with the computer use tool. - 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. + - `type: "computer_screenshot"` - - `tool_names: optional array of string` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - List of allowed tool names. + - `file_id: optional string` - - `authorization: optional string` + The identifier of an uploaded file that contains the screenshot. - 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. + - `image_url: optional string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The URL of the screenshot image. - 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). + - `type: "computer_call_output"` - Currently supported `connector_id` values are: + The type of the computer tool call output. Always `computer_call_output`. - - 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` + - `id: optional string` - - `"connector_dropbox"` + The ID of the computer tool call output. - - `"connector_gmail"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"connector_googlecalendar"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"connector_googledrive"` + - `id: string` - - `"connector_microsoftteams"` + The ID of the pending safety check. - - `"connector_outlookcalendar"` + - `code: optional string` - - `"connector_outlookemail"` + The type of the pending safety check. - - `"connector_sharepoint"` + - `message: optional string` - - `defer_loading: optional boolean` + Details about the pending safety check. - Whether this MCP tool is deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `headers: optional map[string]` + The agent that produced this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `agent_name: string` - - `require_approval: optional object { always, never } or "always" or "never"` + The canonical name of the agent that produced this item. - Specify which of the MCP server's tools require approval. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `MCP tool approval filter: object { always, never }` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"in_progress"` - - `always: optional object { read_only, tool_names }` + - `"completed"` - A filter object to specify which tools are allowed. + - `"incomplete"` - - `read_only: optional boolean` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - 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. + 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. - - `tool_names: optional array of string` + - `id: string` - List of allowed tool names. + The unique ID of the web search tool call. - - `never: optional object { read_only, tool_names }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - A filter object to specify which tools are allowed. + 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). - - `read_only: optional boolean` + - `search: object { type, queries, query, sources }` - 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. + Action type "search" - Performs a web search query. - - `tool_names: optional array of string` + - `type: "search"` - List of allowed tool names. + The action type. - - `MCP tool approval setting: "always" or "never"` + - `queries: optional array of string` - 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. + The search queries. - - `"always"` + - `query: optional string` - - `"never"` + The search query. - - `server_description: optional string` + - `sources: optional array of object { type, url }` - Optional description of the MCP server, used to provide more context. + The sources used in the search. - - `server_url: optional string` + - `type: "url"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The type of source. Always `url`. - - `tunnel_id: optional string` + - `url: string` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The URL of the source. - - `code_interpreter: object { container, type, allowed_callers }` + - `open_page: object { type, url }` - A tool that runs Python code to help generate a response to a prompt. + Action type "open_page" - Opens a specific URL from search results. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `type: "open_page"` - 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. + The action type. - - `union_member_0: string` + - `url: optional string` - The container ID. + The URL opened by the model. - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + - `find_in_page: object { pattern, type, url }` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `type: "auto"` + - `pattern: string` - Always `auto`. + The pattern or text to search for within the page. - - `file_ids: optional array of string` + - `type: "find_in_page"` - An optional list of uploaded files to make available to your code. + The action type. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `url: string` - The memory limit for the code interpreter container. + The URL of the page searched for the pattern. - - `"1g"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"4g"` + The status of the web search tool call. - - `"16g"` + - `"in_progress"` - - `"64g"` + - `"searching"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"completed"` - Network access policy for the container. + - `"failed"` - - `beta_container_network_policy_disabled: object { type }` + - `type: "web_search_call"` - - `type: "disabled"` + The type of the web search tool call. Always `web_search_call`. - Disable outbound network access. Always `disabled`. + - `agent: optional object { agent_name }` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The agent that produced this item. - - `allowed_domains: array of string` + - `agent_name: string` - A list of allowed domains when type is `allowlist`. + The canonical name of the agent that produced this item. - - `type: "allowlist"` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - Allow outbound network access only to specified domains. Always `allowlist`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `arguments: string` - Optional domain-scoped secrets for allowlisted domains. + A JSON string of the arguments to pass to the function. - - `domain: string` + - `call_id: string` - The domain associated with the secret. + The unique ID of the function tool call generated by the model. - `name: string` - The name of the secret to inject for the domain. - - - `value: string` + The name of the function to run. - The secret value to inject for the domain. + - `type: "function_call"` - - `type: "code_interpreter"` + The type of the function tool call. Always `function_call`. - The type of the code interpreter tool. Always `code_interpreter`. + - `id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the function tool call. - The tool invocation context(s). + - `agent: optional object { agent_name }` - - `"direct"` + The agent that produced this item. - - `"programmatic"` + - `agent_name: string` - - `programmatic_tool_calling: object { type }` + The canonical name of the agent that produced this item. - - `image_generation: object { type, action, background, 9 more }` + - `caller: optional object { type } or object { caller_id, type }` - A tool that generates images using the GPT image models. + The execution context that produced this tool call. - - `type: "image_generation"` + - `direct: object { type }` - The type of the image generation tool. Always `image_generation`. + - `program: object { caller_id, type }` - - `action: optional "generate" or "edit" or "auto"` + - `caller_id: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `"generate"` + - `type: "program"` - - `"edit"` + - `namespace: optional string` - - `"auto"` + The namespace of the function to run. - - `background: optional "transparent" or "opaque" or "auto"` + - `status: optional "in_progress" or "completed" or "incomplete"` - 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. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `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. + - `"in_progress"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `"completed"` - - `"transparent"` + - `"incomplete"` - - `"opaque"` + - `function_call_output: object { call_id, output, type, 4 more }` - - `"auto"` + The output of a function tool call. - - `input_fidelity: optional "high" or "low"` + - `call_id: string` - 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`. + The unique ID of the function tool call generated by the model. - - `"high"` + - `output: string or BetaResponseFunctionCallOutputItemList` - - `"low"` + Text, image, or file output of the function tool call. - - `input_image_mask: optional object { file_id, image_url }` + - `union_member_0: string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A JSON string of the output of the function tool call. - - `file_id: optional string` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - File ID for the mask image. + An array of content outputs (text, image, file) for the function tool call. - - `image_url: optional string` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - Base64-encoded mask image. + A text input to the model. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `text: string` - The image generation model to use. Default: `gpt-image-1`. + The text input to the model. - - `"gpt-image-1"` + - `type: "input_text"` - - `"gpt-image-1-mini"` + The type of the input item. Always `input_text`. - - `"gpt-image-2"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"gpt-image-2-2026-04-21"` + 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. - - `"gpt-image-1.5"` + - `mode: "explicit"` - - `"chatgpt-image-latest"` + The breakpoint mode. Always `explicit`. - - `moderation: optional "auto" or "low"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - Moderation level for the generated image. Default: `auto`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"auto"` + - `type: "input_image"` - - `"low"` + The type of the input item. Always `input_image`. - - `output_compression: optional number` + - `detail: optional "low" or "high" or "auto" or "original"` - Compression level for the output image. Default: 100. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `output_format: optional "png" or "webp" or "jpeg"` + - `"low"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"high"` - - `"png"` + - `"auto"` - - `"webp"` + - `"original"` - - `"jpeg"` + - `file_id: optional string` - - `partial_images: optional number` + The ID of the file to be sent to the model. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `image_url: optional string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"low"` + 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. - - `"medium"` + - `mode: "explicit"` - - `"high"` + The breakpoint mode. Always `explicit`. - - `"auto"` + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + A file input to the model. - 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`. + - `type: "input_file"` - - `"1024x1024"` + The type of the input item. Always `input_file`. - - `"1024x1536"` + - `detail: optional "auto" or "low" or "high"` - - `"1536x1024"` + 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"` - - `local_shell: object { type }` - - A tool that allows the model to execute shell commands in a local environment. + - `"low"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `"high"` - A tool that allows the model to execute shell commands. + - `file_data: optional string` - - `type: "shell"` + The base64-encoded data of the file to be sent to the model. - The type of the shell tool. Always `shell`. + - `file_id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The ID of the file to be sent to the model. - The tool invocation context(s). + - `file_url: optional string` - - `"direct"` + The URL of the file to be sent to the model. - - `"programmatic"` + - `filename: optional string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The name of the file to be sent to the model. - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "container_auto"` + 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. - Automatically creates a container for this request + - `mode: "explicit"` - - `file_ids: optional array of string` + The breakpoint mode. Always `explicit`. - An optional list of uploaded files to make available to your code. + - `type: "function_call_output"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The type of the function tool call output. Always `function_call_output`. - The memory limit for the container. + - `id: optional string` - - `"1g"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `"4g"` + - `agent: optional object { agent_name }` - - `"16g"` + The agent that produced this item. - - `"64g"` + - `agent_name: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The canonical name of the agent that produced this item. - Network access policy for the container. + - `caller: optional object { type } or object { caller_id, type }` - - `beta_container_network_policy_disabled: object { type }` + The execution context that produced this tool call. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `direct: object { type }` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `program: object { caller_id, type }` - An optional list of skills referenced by id or inline data. + - `caller_id: string` - - `beta_skill_reference: object { skill_id, type, version }` + The call ID of the program item that produced this tool call. - - `skill_id: string` + - `type: "program"` - The ID of the referenced skill. + The caller type. Always `program`. - - `type: "skill_reference"` + - `status: optional "in_progress" or "completed" or "incomplete"` - References a skill created with the /v1/skills endpoint. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `version: optional string` + - `"in_progress"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"completed"` - - `beta_inline_skill: object { description, name, source, type }` + - `"incomplete"` - - `description: string` + - `agent_message: object { author, content, recipient, 3 more }` - The description of the skill. + A message routed between agents. - - `name: string` + - `author: string` - The name of the skill. + The sending agent identity. - - `source: object { data, media_type, type }` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - Inline skill payload + Plaintext, image, or encrypted content sent between agents. - - `data: string` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - Base64-encoded skill zip bundle. + A text input to the model. - - `media_type: "application/zip"` + - `text: string` - The media type of the inline skill payload. Must be `application/zip`. + The text input to the model. - - `type: "base64"` + - `type: "input_text"` - The type of the inline skill source. Must be `base64`. + The type of the input item. Always `input_text`. - - `type: "inline"` + - `prompt_cache_breakpoint: optional object { mode }` - Defines an inline skill for this request. + 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. - - `beta_local_environment: object { type, skills }` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `type: "local"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - Use a local computer environment. + - `type: "input_image"` - - `skills: optional array of BetaLocalSkill` + The type of the input item. Always `input_image`. - An optional list of skills. + - `detail: optional "low" or "high" or "auto" or "original"` - - `description: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The description of the skill. + - `file_id: optional string` - - `name: string` + The ID of the file to be sent to the model. - The name of the skill. + - `image_url: optional string` - - `path: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The path to the directory containing the skill. + - `prompt_cache_breakpoint: optional object { mode }` - - `beta_container_reference: object { container_id, type }` + 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. - - `container_id: string` + - `encrypted_content: object { encrypted_content, type }` - The ID of the referenced container. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: "container_reference"` + - `encrypted_content: string` - References a container created with the /v1/containers endpoint + Opaque encrypted content. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `type: "encrypted_content"` - 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) + The type of the input item. Always `encrypted_content`. - - `name: string` + - `recipient: string` - The name of the custom tool, used to identify it in tool calls. + The destination agent identity. - - `type: "custom"` + - `type: "agent_message"` - The type of the custom tool. Always `custom`. + The item type. Always `agent_message`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: optional string` - The tool invocation context(s). + The unique ID of this agent message item. - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that produced this item. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this tool should be deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - Optional description of the custom tool, used to provide more context. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `format: optional object { type } or object { definition, syntax, type }` + The multi-agent action that was executed. - The input format for the custom tool. Default is unconstrained text. + - `"spawn_agent"` - - `text: object { type }` + - `"interrupt_agent"` - Unconstrained free-form text. + - `"list_agents"` - - `grammar: object { definition, syntax, type }` + - `"send_message"` - A grammar defined by the user. + - `"followup_task"` - - `definition: string` + - `"wait_agent"` - The grammar definition. + - `arguments: string` - - `syntax: "lark" or "regex"` + The action arguments as a JSON string. - The syntax of the grammar definition. One of `lark` or `regex`. + - `call_id: string` - - `"lark"` + The unique ID linking this call to its output. - - `"regex"` + - `type: "multi_agent_call"` - - `type: "grammar"` + The item type. Always `multi_agent_call`. - Grammar format. Always `grammar`. + - `id: optional string` - - `beta_namespace_tool: object { description, name, tools, type }` + The unique ID of this multi-agent call. - Groups function/custom tools under a shared namespace. + - `agent: optional object { agent_name }` - - `description: string` + The agent that produced this item. - A description of the namespace shown to the model. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The function/custom tools available inside this namespace. + The multi-agent action that produced this result. - - `function: object { name, type, allowed_callers, 5 more }` + - `"spawn_agent"` - - `name: string` + - `"interrupt_agent"` - - `type: "function"` + - `"list_agents"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"send_message"` - The tool invocation context(s). + - `"followup_task"` - - `"direct"` + - `"wait_agent"` - - `"programmatic"` + - `call_id: string` - - `defer_loading: optional boolean` + The unique ID of the multi-agent call. - Whether this function should be deferred and discovered via tool search. + - `output: array of object { text, type, annotations }` - - `description: optional string` + Text output returned by the multi-agent action. - - `output_schema: optional map[unknown]` + - `text: string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The text content. - - `parameters: optional unknown` + - `type: "output_text"` - - `strict: optional boolean` + The content type. Always `output_text`. - 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. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Citations associated with the text content. - 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) + - `union_member_0: array of object { file_id, filename, index, type }` - - `name: string` + - `file_id: string` - The name of the custom tool, used to identify it in tool calls. + The ID of the file. - - `type: "custom"` + - `filename: string` - The type of the custom tool. Always `custom`. + The filename of the file cited. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `index: number` - The tool invocation context(s). + The index of the file in the list of files. - - `defer_loading: optional boolean` + - `type: "file_citation"` - Whether this tool should be deferred and discovered via tool search. + The citation type. Always `file_citation`. - - `description: optional string` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - Optional description of the custom tool, used to provide more context. + - `end_index: number` - - `format: optional object { type } or object { definition, syntax, type }` + The index of the last character of the citation in the message. - The input format for the custom tool. Default is unconstrained text. + - `start_index: number` - - `type: "namespace"` + The index of the first character of the citation in the message. - The type of the tool. Always `namespace`. + - `title: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The title of the cited resource. - Hosted or BYOT tool search configuration for deferred tools. + - `type: "url_citation"` - - `type: "tool_search"` + The citation type. Always `url_citation`. - The type of the tool. Always `tool_search`. + - `url: string` - - `description: optional string` + The URL of the cited resource. - Description shown to the model for a client-executed tool search tool. + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `execution: optional "server" or "client"` + - `container_id: string` - Whether tool search is executed by the server or by the client. + The ID of the container. - - `"server"` + - `end_index: number` - - `"client"` + The index of the last character of the citation in the message. - - `parameters: optional unknown` + - `file_id: string` - Parameter schema for a client-executed tool search tool. + The ID of the container file. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `filename: string` - 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). + The filename of the container file cited. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `start_index: number` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The index of the first character of the citation in the message. - - `"web_search_preview"` + - `type: "container_file_citation"` - - `"web_search_preview_2025_03_11"` + The citation type. Always `container_file_citation`. - - `search_content_types: optional array of "text" or "image"` + - `type: "multi_agent_call_output"` - - `"text"` + The item type. Always `multi_agent_call_output`. - - `"image"` + - `id: optional string` - - `search_context_size: optional "low" or "medium" or "high"` + The unique ID of this multi-agent call output. - 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. + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"medium"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `user_location: optional object { type, city, country, 2 more }` + - `tool_search_call: object { arguments, type, id, 4 more }` - The user's location. + - `arguments: unknown` - - `type: "approximate"` + The arguments supplied to the tool search call. - The type of location approximation. Always `approximate`. + - `type: "tool_search_call"` - - `city: optional string` + The item type. Always `tool_search_call`. - Free text input for the city of the user, e.g. `San Francisco`. + - `id: optional string` - - `country: optional string` + The unique ID of this tool search call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `agent: optional object { agent_name }` - - `region: optional string` + The agent that produced this item. - Free text input for the region of the user, e.g. `California`. + - `agent_name: string` - - `timezone: optional string` + The canonical name of the agent that produced this item. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `call_id: optional string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The unique ID of the tool search call generated by the model. - Allows the assistant to create, delete, or update files using unified diffs. + - `execution: optional "server" or "client"` - - `type: "apply_patch"` + Whether tool search was executed by the server or by the client. - The type of the tool. Always `apply_patch`. + - `"server"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"client"` - The tool invocation context(s). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"direct"` + The status of the tool search call. - - `"programmatic"` + - `"in_progress"` - - `type: "tool_search_output"` + - `"completed"` - The type of the item. Always `tool_search_output`. + - `"incomplete"` - - `agent: optional object { agent_name }` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - The agent that produced this item. + - `tools: array of BetaTool` - - `agent_name: string` + The loaded tool definitions returned by the tool search output. - The canonical name of the agent that produced this item. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `created_by: optional string` + 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). - The identifier of the actor that created the item. + - `name: string` - - `additional_tools: object { id, role, tools, 2 more }` + The name of the function to call. - - `id: string` + - `parameters: map[unknown]` - The unique ID of the additional tools item. + A JSON schema object describing the parameters of the function. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `strict: boolean` - The role that provided the additional tools. + Whether strict parameter validation is enforced for this function tool. - - `"unknown"` + - `type: "function"` - - `"user"` + The type of the function tool. Always `function`. - - `"assistant"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"system"` + The tool invocation context(s). - - `"critic"` + - `"direct"` - - `"discriminator"` + - `"programmatic"` - - `"developer"` + - `defer_loading: optional boolean` - - `"tool"` + Whether this function is deferred and loaded via tool search. - - `tools: array of BetaTool` + - `description: optional string` - The additional tool definitions made available at this item. + A description of the function. Used by the model to determine whether or not to call the function. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `output_schema: optional map[unknown]` - 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). + A JSON schema object describing the JSON value encoded in string outputs for this function. - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` 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). - - `beta_computer_tool: object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "file_search"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The type of the file search tool. Always `file_search`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `vector_store_ids: array of string` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The IDs of the vector stores to search. - 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). + - `filters: optional object { key, type, value } or object { filters, type }` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + A filter to apply. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `Comparison Filter: object { key, type, value }` - - `code_interpreter: object { container, type, allowed_callers }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A tool that runs Python code to help generate a response to a prompt. + - `key: string` - - `programmatic_tool_calling: object { type }` + The key to compare against the value. - - `image_generation: object { type, action, background, 9 more }` + - `type: "eq" or "ne" or "gt" or 5 more` - A tool that generates images using the GPT image models. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `local_shell: object { type }` + - `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 - A tool that allows the model to execute shell commands in a local environment. + - `"eq"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `"ne"` - A tool that allows the model to execute shell commands. + - `"gt"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `"gte"` - 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) + - `"lt"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `"lte"` - Groups function/custom tools under a shared namespace. + - `"in"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `"nin"` - Hosted or BYOT tool search configuration for deferred tools. + - `value: string or number or boolean or array of string or number` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The value to compare against the attribute key; supports string, number, or boolean types. - 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). + - `union_member_0: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `union_member_1: number` - Allows the assistant to create, delete, or update files using unified diffs. + - `union_member_2: boolean` - - `type: "additional_tools"` + - `union_member_3: array of string or number` - The type of the item. Always `additional_tools`. + - `union_member_0: string` - - `agent: optional object { agent_name }` + - `union_member_1: number` - The agent that produced this item. + - `Compound Filter: object { filters, type }` - - `agent_name: string` + Combine multiple filters using `and` or `or`. - The canonical name of the agent that produced this item. + - `filters: array of object { key, type, value } or unknown` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `Comparison Filter: object { key, type, value }` - - `id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique ID of the compaction item. + - `key: string` - - `encrypted_content: string` + The key to compare against the value. - The encrypted content that was produced by compaction. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "compaction"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The type of the item. Always `compaction`. + - `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 - - `agent: optional object { agent_name }` + - `"eq"` - The agent that produced this item. + - `"ne"` - - `agent_name: string` + - `"gt"` - The canonical name of the agent that produced this item. + - `"gte"` - - `created_by: optional string` + - `"lt"` - The identifier of the actor that created the item. + - `"lte"` - - `image_generation_call: object { id, result, status, 2 more }` + - `"in"` - An image generation request made by the model. + - `"nin"` - - `id: string` + - `value: string or number or boolean or array of string or number` - The unique ID of the image generation call. + The value to compare against the attribute key; supports string, number, or boolean types. - - `result: string` + - `union_member_0: string` - The generated image encoded in base64. + - `union_member_1: number` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `union_member_2: boolean` - The status of the image generation call. + - `union_member_3: array of string or number` - - `"in_progress"` + - `union_member_0: string` - - `"completed"` + - `union_member_1: number` - - `"generating"` + - `union_member_1: unknown` - - `"failed"` + - `type: "and" or "or"` - - `type: "image_generation_call"` + Type of operation: `and` or `or`. - The type of the image generation call. Always `image_generation_call`. + - `"and"` - - `agent: optional object { agent_name }` + - `"or"` - The agent that produced this item. + - `max_num_results: optional number` - - `agent_name: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The canonical name of the agent that produced this item. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + Ranking options for search. - A tool call to run code. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `id: string` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The unique ID of the code interpreter tool call. + - `embedding_weight: number` - - `code: string` + The weight of the embedding in the reciprocal ranking fusion. - The code to run, or null if not available. + - `text_weight: number` - - `container_id: string` + The weight of the text in the reciprocal ranking fusion. - The ID of the container used to run the code. + - `ranker: optional "auto" or "default-2024-11-15"` - - `outputs: array of object { logs, type } or object { type, url }` + The ranker to use for the file search. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"auto"` - - `logs: object { logs, type }` + - `"default-2024-11-15"` - The logs output from the code interpreter. + - `score_threshold: optional number` - - `logs: string` + 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. - The logs output from the code interpreter. + - `beta_computer_tool: object { type }` - - `type: "logs"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the output. Always `logs`. + - `type: "computer"` - - `image: object { type, url }` + The type of the computer tool. Always `computer`. - The image output from the code interpreter. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `type: "image"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the output. Always `image`. + - `display_height: number` - - `url: string` + The height of the computer display. - The URL of the image output from the code interpreter. + - `display_width: number` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The width of the computer display. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"in_progress"` + The type of computer environment to control. - - `"completed"` + - `"windows"` - - `"incomplete"` + - `"mac"` - - `"interpreting"` + - `"linux"` - - `"failed"` + - `"ubuntu"` - - `type: "code_interpreter_call"` + - `"browser"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `type: "computer_use_preview"` - - `agent: optional object { agent_name }` + The type of the computer use tool. Always `computer_use_preview`. - The agent that produced this item. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `type: "web_search" or "web_search_2025_08_26"` - - `local_shell_call: object { id, action, call_id, 3 more }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - A tool call to run a command on the local shell. + - `"web_search"` - - `id: string` + - `"web_search_2025_08_26"` - The unique ID of the local shell call. + - `filters: optional object { allowed_domains }` - - `action: object { command, env, type, 3 more }` + Filters for the search. - Execute a shell command on the server. + - `allowed_domains: optional array of string` - - `command: array of string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The command to run. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `env: map[string]` + - `search_context_size: optional "low" or "medium" or "high"` - Environment variables to set for the command. + 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. - - `type: "exec"` + - `"low"` - The type of the local shell action. Always `exec`. + - `"medium"` - - `timeout_ms: optional number` + - `"high"` - Optional timeout in milliseconds for the command. + - `user_location: optional object { city, country, region, 2 more }` - - `user: optional string` + The approximate location of the user. - Optional user to run the command as. + - `city: optional string` - - `working_directory: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - Optional working directory to run the command in. + - `country: optional string` - - `call_id: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The unique ID of the local shell tool call generated by the model. + - `region: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + Free text input for the region of the user, e.g. `California`. - The status of the local shell call. + - `timezone: optional string` - - `"in_progress"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"completed"` + - `type: optional "approximate"` - - `"incomplete"` + The type of location approximation. Always `approximate`. - - `type: "local_shell_call"` + - `"approximate"` - The type of the local shell call. Always `local_shell_call`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `agent: optional object { agent_name }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The agent that produced this item. + - `server_label: string` - - `agent_name: string` + A label for this MCP server, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: "mcp"` - - `local_shell_call_output: object { id, output, type, 2 more }` + The type of the MCP tool. Always `mcp`. - The output of a local shell tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of the local shell tool call generated by the model. + - `"direct"` - - `output: string` + - `"programmatic"` - A JSON string of the output of the local shell tool call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "local_shell_call_output"` + List of allowed tool names or a filter object. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `MCP allowed tools: array of string` - - `agent: optional object { agent_name }` + A string array of allowed tool names - The agent that produced this item. + - `MCP tool filter: object { read_only, tool_names }` - - `agent_name: string` + A filter object to specify which tools are allowed. - The canonical name of the agent that produced this item. + - `read_only: optional boolean` - - `status: optional "in_progress" or "completed" or "incomplete"` + 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. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `tool_names: optional array of string` - - `"in_progress"` + List of allowed tool names. - - `"completed"` + - `authorization: optional string` - - `"incomplete"` + 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. - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - A tool call that executes one or more shell commands in a managed environment. + 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). - - `id: string` + Currently supported `connector_id` values are: - The unique ID of the shell tool call. Populated when this item is returned via API. + - 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` - - `action: object { commands, max_output_length, timeout_ms }` + - `"connector_dropbox"` - The shell commands and limits that describe how to run the tool call. + - `"connector_gmail"` - - `commands: array of string` + - `"connector_googlecalendar"` - - `max_output_length: number` + - `"connector_googledrive"` - Optional maximum number of characters to return from each command. + - `"connector_microsoftteams"` - - `timeout_ms: number` + - `"connector_outlookcalendar"` - Optional timeout in milliseconds for the commands. + - `"connector_outlookemail"` - - `call_id: string` + - `"connector_sharepoint"` - The unique ID of the shell tool call generated by the model. + - `defer_loading: optional boolean` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + Whether this MCP tool is deferred and discovered via tool search. - Represents the use of a local environment to perform shell actions. + - `headers: optional map[string]` - - `beta_response_local_environment: object { type }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Represents the use of a local environment to perform shell actions. + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "local"` + Specify which of the MCP server's tools require approval. - The environment type. Always `local`. + - `MCP tool approval filter: object { always, never }` - - `beta_response_container_reference: object { container_id, type }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Represents a container created with /v1/containers. + - `always: optional object { read_only, tool_names }` - - `container_id: string` + A filter object to specify which tools are allowed. - - `type: "container_reference"` + - `read_only: optional boolean` - The environment type. Always `container_reference`. + 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. - - `status: "in_progress" or "completed" or "incomplete"` + - `tool_names: optional array of string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + List of allowed tool names. - - `"in_progress"` + - `never: optional object { read_only, tool_names }` - - `"completed"` + A filter object to specify which tools are allowed. - - `"incomplete"` + - `read_only: optional boolean` - - `type: "shell_call"` + 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. - The type of the item. Always `shell_call`. + - `tool_names: optional array of string` - - `agent: optional object { agent_name }` + List of allowed tool names. - The agent that produced this item. + - `MCP tool approval setting: "always" or "never"` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `"always"` - - `caller: optional object { type } or object { caller_id, type }` + - `"never"` - The execution context that produced this tool call. + - `server_description: optional string` - - `direct: object { type }` + Optional description of the MCP server, used to provide more context. - - `program: object { caller_id, type }` + - `server_url: optional string` - - `caller_id: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The call ID of the program item that produced this tool call. + - `tunnel_id: optional string` - - `type: "program"` + 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. - - `created_by: optional string` + - `code_interpreter: object { container, type, allowed_callers }` - The ID of the entity that created this tool call. + A tool that runs Python code to help generate a response to a prompt. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The output of a shell tool call that was emitted. + 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. - - `id: string` + - `union_member_0: string` - The unique ID of the shell call output. Populated when this item is returned via API. + The container ID. - - `call_id: string` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - The unique ID of the shell tool call generated by the model. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `max_output_length: number` + - `type: "auto"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + Always `auto`. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `file_ids: optional array of string` - An array of shell call output contents + An optional list of uploaded files to make available to your code. - - `outcome: object { type } or object { exit_code, type }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The memory limit for the code interpreter container. - - `timeout: object { type }` + - `"1g"` - Indicates that the shell call exceeded its configured time limit. + - `"4g"` - - `exit: object { exit_code, type }` + - `"16g"` - Indicates that the shell commands finished and returned an exit code. + - `"64g"` - - `exit_code: number` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Exit code from the shell process. + Network access policy for the container. - - `type: "exit"` + - `beta_container_network_policy_disabled: object { type }` - The outcome type. Always `exit`. + - `type: "disabled"` - - `stderr: string` + Disable outbound network access. Always `disabled`. - The standard error output that was captured. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `stdout: string` + - `allowed_domains: array of string` - The standard output that was captured. + A list of allowed domains when type is `allowlist`. - - `created_by: optional string` + - `type: "allowlist"` - The identifier of the actor that created the item. + Allow outbound network access only to specified domains. Always `allowlist`. - - `status: "in_progress" or "completed" or "incomplete"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Optional domain-scoped secrets for allowlisted domains. - - `"in_progress"` + - `domain: string` - - `"completed"` + The domain associated with the secret. - - `"incomplete"` + - `name: string` - - `type: "shell_call_output"` + The name of the secret to inject for the domain. - The type of the shell call output. Always `shell_call_output`. + - `value: string` - - `agent: optional object { agent_name }` + The secret value to inject for the domain. - The agent that produced this item. + - `type: "code_interpreter"` - - `agent_name: string` + The type of the code interpreter tool. Always `code_interpreter`. - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `caller: optional object { type } or object { caller_id, type }` + The tool invocation context(s). - The execution context that produced this tool call. + - `"direct"` - - `direct: object { type }` + - `"programmatic"` - - `program: object { caller_id, type }` + - `programmatic_tool_calling: object { type }` - - `caller_id: string` + - `image_generation: object { type, action, background, 9 more }` - The call ID of the program item that produced this tool call. + A tool that generates images using the GPT image models. - - `type: "program"` + - `type: "image_generation"` - - `created_by: optional string` + The type of the image generation tool. Always `image_generation`. - The identifier of the actor that created the item. + - `action: optional "generate" or "edit" or "auto"` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + Whether to generate a new image or edit an existing image. Default: `auto`. - A tool call that applies file diffs by creating, deleting, or updating files. + - `"generate"` - - `id: string` + - `"edit"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"auto"` - - `call_id: string` + - `background: optional "transparent" or "opaque" or "auto"` - The unique ID of the apply patch tool call generated by the model. + 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. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + `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. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `create_file: object { diff, path, type }` + - `"transparent"` - Instruction describing how to create a file via the apply_patch tool. + - `"opaque"` - - `diff: string` + - `"auto"` - Diff to apply. + - `input_fidelity: optional "high" or "low"` - - `path: string` + 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`. - Path of the file to create. + - `"high"` - - `type: "create_file"` + - `"low"` - Create a new file with the provided diff. + - `input_image_mask: optional object { file_id, image_url }` - - `delete_file: object { path, type }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Instruction describing how to delete a file via the apply_patch tool. + - `file_id: optional string` - - `path: string` + File ID for the mask image. - Path of the file to delete. + - `image_url: optional string` - - `type: "delete_file"` + Base64-encoded mask image. - Delete the specified file. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `update_file: object { diff, path, type }` + The image generation model to use. Default: `gpt-image-1`. - Instruction describing how to update a file via the apply_patch tool. + - `"gpt-image-1"` - - `diff: string` + - `"gpt-image-1-mini"` - Diff to apply. + - `"gpt-image-2"` - - `path: string` + - `"gpt-image-2-2026-04-21"` - Path of the file to update. + - `"gpt-image-1.5"` - - `type: "update_file"` + - `"chatgpt-image-latest"` - Update an existing file with the provided diff. + - `moderation: optional "auto" or "low"` - - `status: "in_progress" or "completed"` + Moderation level for the generated image. Default: `auto`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"auto"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `output_compression: optional number` - - `type: "apply_patch_call"` + Compression level for the output image. Default: 100. - The type of the item. Always `apply_patch_call`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `agent: optional object { agent_name }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The agent that produced this item. + - `"png"` - - `agent_name: string` + - `"webp"` - The canonical name of the agent that produced this item. + - `"jpeg"` - - `caller: optional object { type } or object { caller_id, type }` + - `partial_images: optional number` - The execution context that produced this tool call. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `direct: object { type }` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `program: object { caller_id, type }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `caller_id: string` + - `"low"` - The call ID of the program item that produced this tool call. + - `"medium"` - - `type: "program"` + - `"high"` - - `created_by: optional string` + - `"auto"` - The ID of the entity that created this tool call. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + 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`. - The output emitted by an apply patch tool call. + - `"1024x1024"` - - `id: string` + - `"1024x1536"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"1536x1024"` - - `call_id: string` + - `"auto"` - The unique ID of the apply patch tool call generated by the model. + - `local_shell: object { type }` - - `status: "completed" or "failed"` + A tool that allows the model to execute shell commands in a local environment. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"completed"` + A tool that allows the model to execute shell commands. - - `"failed"` + - `type: "shell"` - - `type: "apply_patch_call_output"` + The type of the shell tool. Always `shell`. - The type of the item. Always `apply_patch_call_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `caller: optional object { type } or object { caller_id, type }` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - The execution context that produced this tool call. + - `type: "container_auto"` - - `direct: object { type }` + Automatically creates a container for this request - - `program: object { caller_id, type }` + - `file_ids: optional array of string` - - `caller_id: string` + An optional list of uploaded files to make available to your code. - The call ID of the program item that produced this tool call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "program"` + The memory limit for the container. - - `created_by: optional string` + - `"1g"` - The ID of the entity that created this tool call output. + - `"4g"` - - `output: optional string` + - `"16g"` - Optional textual output returned by the apply patch tool. + - `"64g"` - - `mcp_call: object { id, arguments, name, 7 more }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - An invocation of a tool on an MCP server. + Network access policy for the container. - - `id: string` + - `beta_container_network_policy_disabled: object { type }` - The unique ID of the tool call. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `arguments: string` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - A JSON string of the arguments passed to the tool. + An optional list of skills referenced by id or inline data. - - `name: string` + - `beta_skill_reference: object { skill_id, type, version }` - The name of the tool that was run. + - `skill_id: string` - - `server_label: string` + The ID of the referenced skill. - The label of the MCP server running the tool. + - `type: "skill_reference"` - - `type: "mcp_call"` + References a skill created with the /v1/skills endpoint. - The type of the item. Always `mcp_call`. + - `version: optional string` - - `agent: optional object { agent_name }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The agent that produced this item. + - `beta_inline_skill: object { description, name, source, type }` - - `agent_name: string` + - `description: string` - The canonical name of the agent that produced this item. + The description of the skill. - - `approval_request_id: optional string` + - `name: string` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The name of the skill. - - `error: optional string` + - `source: object { data, media_type, type }` - The error from the tool call, if any. + Inline skill payload - - `output: optional string` + - `data: string` - The output from the tool call. + Base64-encoded skill zip bundle. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `media_type: "application/zip"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The media type of the inline skill payload. Must be `application/zip`. - - `"in_progress"` + - `type: "base64"` - - `"completed"` + The type of the inline skill source. Must be `base64`. - - `"incomplete"` + - `type: "inline"` - - `"calling"` + Defines an inline skill for this request. - - `"failed"` + - `beta_local_environment: object { type, skills }` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `type: "local"` - A list of tools available on an MCP server. + Use a local computer environment. - - `id: string` + - `skills: optional array of BetaLocalSkill` - The unique ID of the list. + An optional list of skills. - - `server_label: string` + - `description: string` - The label of the MCP server. + The description of the skill. - - `tools: array of object { input_schema, name, annotations, description }` + - `name: string` - The tools available on the server. + The name of the skill. - - `input_schema: unknown` + - `path: string` - The JSON schema describing the tool's input. + The path to the directory containing the skill. - - `name: string` + - `beta_container_reference: object { container_id, type }` - The name of the tool. + - `container_id: string` - - `annotations: optional unknown` + The ID of the referenced container. - Additional annotations about the tool. + - `type: "container_reference"` - - `description: optional string` + References a container created with the /v1/containers endpoint - The description of the tool. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `type: "mcp_list_tools"` + 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) - The type of the item. Always `mcp_list_tools`. + - `name: string` - - `agent: optional object { agent_name }` + The name of the custom tool, used to identify it in tool calls. - The agent that produced this item. + - `type: "custom"` - - `agent_name: string` + The type of the custom tool. Always `custom`. - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `error: optional string` + The tool invocation context(s). - Error message if the server could not list tools. + - `"direct"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `"programmatic"` - A request for human approval of a tool invocation. + - `defer_loading: optional boolean` - - `id: string` + Whether this tool should be deferred and discovered via tool search. - The unique ID of the approval request. + - `description: optional string` - - `arguments: string` + Optional description of the custom tool, used to provide more context. - A JSON string of arguments for the tool. + - `format: optional object { type } or object { definition, syntax, type }` - - `name: string` + The input format for the custom tool. Default is unconstrained text. - The name of the tool to run. + - `text: object { type }` - - `server_label: string` + Unconstrained free-form text. - The label of the MCP server making the request. + - `grammar: object { definition, syntax, type }` - - `type: "mcp_approval_request"` + A grammar defined by the user. - The type of the item. Always `mcp_approval_request`. + - `definition: string` - - `agent: optional object { agent_name }` + The grammar definition. - The agent that produced this item. + - `syntax: "lark" or "regex"` - - `agent_name: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The canonical name of the agent that produced this item. + - `"lark"` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `"regex"` - A response to an MCP approval request. + - `type: "grammar"` - - `id: string` + Grammar format. Always `grammar`. - The unique ID of the approval response + - `beta_namespace_tool: object { description, name, tools, type }` - - `approval_request_id: string` + Groups function/custom tools under a shared namespace. - The ID of the approval request being answered. + - `description: string` - - `approve: boolean` + A description of the namespace shown to the model. - Whether the request was approved. + - `name: string` - - `type: "mcp_approval_response"` + The namespace name used in tool calls (for example, `crm`). - The type of the item. Always `mcp_approval_response`. + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `agent: optional object { agent_name }` + The function/custom tools available inside this namespace. - The agent that produced this item. + - `function: object { name, type, allowed_callers, 5 more }` - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + - `type: "function"` - - `reason: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Optional reason for the decision. + The tool invocation context(s). - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `"direct"` - A call to a custom tool created by the model. + - `"programmatic"` - - `call_id: string` + - `defer_loading: optional boolean` - An identifier used to map this custom tool call to a tool call output. + Whether this function should be deferred and discovered via tool search. - - `input: string` + - `description: optional string` - The input for the custom tool call generated by the model. + - `output_schema: optional map[unknown]` - - `name: string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The name of the custom tool being called. + - `parameters: optional unknown` - - `type: "custom_tool_call"` + - `strict: optional boolean` - The type of the custom tool call. Always `custom_tool_call`. + 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. - - `id: optional string` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The unique ID of the custom tool call in the OpenAI platform. + 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) - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The name of the custom tool, used to identify it in tool calls. - - `agent_name: string` + - `type: "custom"` - The canonical name of the agent that produced this item. + The type of the custom tool. Always `custom`. - - `caller: optional object { type } or object { caller_id, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The execution context that produced this tool call. + The tool invocation context(s). - - `direct: object { type }` + - `defer_loading: optional boolean` - - `program: object { caller_id, type }` + Whether this tool should be deferred and discovered via tool search. - - `caller_id: string` + - `description: optional string` - The call ID of the program item that produced this tool call. + Optional description of the custom tool, used to provide more context. - - `type: "program"` + - `format: optional object { type } or object { definition, syntax, type }` - - `namespace: optional string` + The input format for the custom tool. Default is unconstrained text. - The namespace of the custom tool being called. + - `type: "namespace"` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The type of the tool. Always `namespace`. - The output of a custom tool call from your code, being sent back to the model. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `id: string` + Hosted or BYOT tool search configuration for deferred tools. - The unique ID of the custom tool call output item. + - `type: "tool_search"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the tool. Always `tool_search`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `description: optional string` - - `"in_progress"` + Description shown to the model for a client-executed tool search tool. - - `"completed"` + - `execution: optional "server" or "client"` - - `"incomplete"` + Whether tool search is executed by the server or by the client. - - `created_by: optional string` + - `"server"` - The identifier of the actor that created the item. + - `"client"` - - `usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `parameters: optional unknown` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + Parameter schema for a client-executed tool search tool. - - `input_tokens: number` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The number of input tokens. + 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). - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - A detailed breakdown of the input tokens. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `cache_write_tokens: number` + - `"web_search_preview"` - The number of input tokens that were written to the cache. + - `"web_search_preview_2025_03_11"` - - `cached_tokens: number` + - `search_content_types: optional array of "text" or "image"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `"text"` - - `output_tokens: number` + - `"image"` - The number of output tokens. + - `search_context_size: optional "low" or "medium" or "high"` - - `output_tokens_details: object { reasoning_tokens }` + 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. - A detailed breakdown of the output tokens. + - `"low"` - - `reasoning_tokens: number` + - `"medium"` - The number of reasoning tokens. + - `"high"` - - `total_tokens: number` + - `user_location: optional object { type, city, country, 2 more }` - The total number of tokens used. + The user's location. -### Beta Computer Action + - `type: "approximate"` -- `beta_computer_action: object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + The type of location approximation. Always `approximate`. - A click action. + - `city: optional string` - - `click: object { button, type, x, 2 more }` + Free text input for the city of the user, e.g. `San Francisco`. - A click action. + - `country: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `region: optional string` - - `"left"` + Free text input for the region of the user, e.g. `California`. - - `"right"` + - `timezone: optional string` - - `"wheel"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"back"` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `"forward"` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "click"` + - `type: "apply_patch"` - Specifies the event type. For a click action, this property is always `click`. + The type of the tool. Always `apply_patch`. - - `x: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The x-coordinate where the click occurred. + The tool invocation context(s). - - `y: number` + - `"direct"` - The y-coordinate where the click occurred. + - `"programmatic"` - - `keys: optional array of string` + - `type: "tool_search_output"` - The keys being held while clicking. + The item type. Always `tool_search_output`. - - `double_click: object { keys, type, x, y }` + - `id: optional string` - A double click action. + The unique ID of this tool search output. - - `keys: array of string` + - `agent: optional object { agent_name }` - The keys being held while double-clicking. + The agent that produced this item. - - `type: "double_click"` + - `agent_name: string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The canonical name of the agent that produced this item. - - `x: number` + - `call_id: optional string` - The x-coordinate where the double click occurred. + The unique ID of the tool search call generated by the model. - - `y: number` + - `execution: optional "server" or "client"` - The y-coordinate where the double click occurred. + Whether tool search was executed by the server or by the client. - - `drag: object { path, type, keys }` + - `"server"` - A drag action. + - `"client"` - - `path: array of object { x, y }` + - `status: optional "in_progress" or "completed" or "incomplete"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The status of the tool search output. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"in_progress"` - - `x: number` + - `"completed"` - The x-coordinate. + - `"incomplete"` - - `y: number` + - `additional_tools: object { role, tools, type, 2 more }` - The y-coordinate. + - `role: "developer"` - - `type: "drag"` + The role that provided the additional tools. Only `developer` is supported. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `tools: array of BetaTool` - - `keys: optional array of string` + A list of additional tools made available at this item. - The keys being held while dragging the mouse. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `keypress: object { keys, type }` + 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). - A collection of keypresses the model would like to perform. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `keys: array of string` + 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). - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `beta_computer_tool: object { type }` - - `type: "keypress"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `move: object { type, x, y, keys }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A mouse move action. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `type: "move"` + 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). - Specifies the event type. For a move action, this property is always set to `move`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `x: number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The x-coordinate to move to. + - `code_interpreter: object { container, type, allowed_callers }` - - `y: number` + A tool that runs Python code to help generate a response to a prompt. - The y-coordinate to move to. + - `programmatic_tool_calling: object { type }` - - `keys: optional array of string` + - `image_generation: object { type, action, background, 9 more }` - The keys being held while moving the mouse. + A tool that generates images using the GPT image models. - - `screenshot: object { type }` + - `local_shell: object { type }` - A screenshot action. + A tool that allows the model to execute shell commands in a local environment. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - A scroll action. + A tool that allows the model to execute shell commands. - - `scroll_x: number` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The horizontal scroll distance. + 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) - - `scroll_y: number` + - `beta_namespace_tool: object { description, name, tools, type }` - The vertical scroll distance. + Groups function/custom tools under a shared namespace. - - `type: "scroll"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Hosted or BYOT tool search configuration for deferred tools. - - `x: number` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The x-coordinate where the scroll occurred. + 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). - - `y: number` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The y-coordinate where the scroll occurred. + Allows the assistant to create, delete, or update files using unified diffs. - - `keys: optional array of string` + - `type: "additional_tools"` - The keys being held while scrolling. + The item type. Always `additional_tools`. - - `type: object { text, type }` + - `id: optional string` - An action to type in text. + The unique ID of this additional tools item. - - `text: string` + - `agent: optional object { agent_name }` - The text to type. + The agent that produced this item. - - `type: "type"` + - `agent_name: string` - Specifies the event type. For a type action, this property is always set to `type`. + The canonical name of the agent that produced this item. - - `wait: object { type }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - A wait action. + 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). -### Beta Computer Action List + - `id: string` -- `beta_computer_action_list: array of BetaComputerAction` + The unique identifier of the reasoning content. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `summary: array of object { text, type }` - - `click: object { button, type, x, 2 more }` + Reasoning summary content. - A click action. + - `text: string` - - `button: "left" or "right" or "wheel" or 2 more` + A summary of the reasoning output from the model so far. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `type: "summary_text"` - - `"left"` + The type of the object. Always `summary_text`. - - `"right"` + - `type: "reasoning"` - - `"wheel"` + The type of the object. Always `reasoning`. - - `"back"` + - `agent: optional object { agent_name }` - - `"forward"` + The agent that produced this item. - - `type: "click"` + - `agent_name: string` - Specifies the event type. For a click action, this property is always `click`. + The canonical name of the agent that produced this item. - - `x: number` + - `content: optional array of object { text, type }` - The x-coordinate where the click occurred. + Reasoning text content. - - `y: number` + - `text: string` - The y-coordinate where the click occurred. + The reasoning text from the model. - - `keys: optional array of string` + - `type: "reasoning_text"` - The keys being held while clicking. + The type of the reasoning text. Always `reasoning_text`. - - `double_click: object { keys, type, x, y }` + - `encrypted_content: optional string` - A double click action. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `keys: array of string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The keys being held while double-clicking. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "double_click"` + - `"in_progress"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"completed"` - - `x: number` + - `"incomplete"` - The x-coordinate where the double click occurred. + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - - `y: number` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The y-coordinate where the double click occurred. + - `encrypted_content: string` - - `drag: object { path, type, keys }` + The encrypted content of the compaction summary. - A drag action. + - `type: "compaction"` - - `path: array of object { x, y }` + The type of the item. Always `compaction`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `id: optional string` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The ID of the compaction item. - - `x: number` + - `agent: optional object { agent_name }` - The x-coordinate. + The agent that produced this item. - - `y: number` + - `agent_name: string` - The y-coordinate. + The canonical name of the agent that produced this item. - - `type: "drag"` + - `image_generation_call: object { id, result, status, 2 more }` - Specifies the event type. For a drag action, this property is always set to `drag`. + An image generation request made by the model. - - `keys: optional array of string` + - `id: string` - The keys being held while dragging the mouse. + The unique ID of the image generation call. - - `keypress: object { keys, type }` + - `result: string` - A collection of keypresses the model would like to perform. + The generated image encoded in base64. - - `keys: array of string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The status of the image generation call. - - `type: "keypress"` + - `"in_progress"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"completed"` - - `move: object { type, x, y, keys }` + - `"generating"` - A mouse move action. + - `"failed"` - - `type: "move"` + - `type: "image_generation_call"` - Specifies the event type. For a move action, this property is always set to `move`. + The type of the image generation call. Always `image_generation_call`. - - `x: number` + - `agent: optional object { agent_name }` - The x-coordinate to move to. + The agent that produced this item. - - `y: number` + - `agent_name: string` - The y-coordinate to move to. + The canonical name of the agent that produced this item. - - `keys: optional array of string` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - The keys being held while moving the mouse. + A tool call to run code. - - `screenshot: object { type }` + - `id: string` - A screenshot action. + The unique ID of the code interpreter tool call. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `code: string` - A scroll action. + The code to run, or null if not available. - - `scroll_x: number` + - `container_id: string` - The horizontal scroll distance. + The ID of the container used to run the code. - - `scroll_y: number` + - `outputs: array of object { logs, type } or object { type, url }` - The vertical scroll distance. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `type: "scroll"` + - `logs: object { logs, type }` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The logs output from the code interpreter. - - `x: number` + - `logs: string` - The x-coordinate where the scroll occurred. + The logs output from the code interpreter. - - `y: number` + - `type: "logs"` - The y-coordinate where the scroll occurred. + The type of the output. Always `logs`. - - `keys: optional array of string` + - `image: object { type, url }` - The keys being held while scrolling. + The image output from the code interpreter. - - `type: object { text, type }` + - `type: "image"` - An action to type in text. + The type of the output. Always `image`. - - `text: string` + - `url: string` - The text to type. + The URL of the image output from the code interpreter. - - `type: "type"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Specifies the event type. For a type action, this property is always set to `type`. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `wait: object { type }` + - `"in_progress"` - A wait action. + - `"completed"` -### Beta Computer Tool + - `"incomplete"` -- `beta_computer_tool: object { type }` + - `"interpreting"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"failed"` - - `type: "computer"` + - `type: "code_interpreter_call"` - The type of the computer tool. Always `computer`. + The type of the code interpreter tool call. Always `code_interpreter_call`. -### Beta Computer Use Preview Tool + - `agent: optional object { agent_name }` -- `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: string` - - `display_height: number` + The canonical name of the agent that produced this item. - The height of the computer display. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `display_width: number` + A tool call to run a command on the local shell. - The width of the computer display. + - `id: string` - - `environment: "windows" or "mac" or "linux" or 2 more` + The unique ID of the local shell call. - The type of computer environment to control. + - `action: object { command, env, type, 3 more }` - - `"windows"` + Execute a shell command on the server. - - `"mac"` + - `command: array of string` - - `"linux"` + The command to run. - - `"ubuntu"` + - `env: map[string]` - - `"browser"` + Environment variables to set for the command. - - `type: "computer_use_preview"` + - `type: "exec"` - The type of the computer use tool. Always `computer_use_preview`. + The type of the local shell action. Always `exec`. -### Beta Container Auto + - `timeout_ms: optional number` -- `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + Optional timeout in milliseconds for the command. - - `type: "container_auto"` + - `user: optional string` - Automatically creates a container for this request + Optional user to run the command as. - - `file_ids: optional array of string` + - `working_directory: optional string` - An optional list of uploaded files to make available to your code. + Optional working directory to run the command in. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `call_id: string` - The memory limit for the container. + The unique ID of the local shell tool call generated by the model. - - `"1g"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"4g"` + The status of the local shell call. - - `"16g"` + - `"in_progress"` - - `"64g"` + - `"completed"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"incomplete"` - Network access policy for the container. + - `type: "local_shell_call"` - - `beta_container_network_policy_disabled: object { type }` + The type of the local shell call. Always `local_shell_call`. - - `type: "disabled"` + - `agent: optional object { agent_name }` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `agent_name: string` - - `allowed_domains: array of string` + The canonical name of the agent that produced this item. - A list of allowed domains when type is `allowlist`. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `type: "allowlist"` + The output of a local shell tool call. - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The unique ID of the local shell tool call generated by the model. - Optional domain-scoped secrets for allowlisted domains. + - `output: string` - - `domain: string` + A JSON string of the output of the local shell tool call. - The domain associated with the secret. + - `type: "local_shell_call_output"` - - `name: string` + The type of the local shell tool call output. Always `local_shell_call_output`. - The name of the secret to inject for the domain. + - `agent: optional object { agent_name }` - - `value: string` + The agent that produced this item. - The secret value to inject for the domain. + - `agent_name: string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The canonical name of the agent that produced this item. - An optional list of skills referenced by id or inline data. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `beta_skill_reference: object { skill_id, type, version }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `skill_id: string` + - `"in_progress"` - The ID of the referenced skill. + - `"completed"` - - `type: "skill_reference"` + - `"incomplete"` - References a skill created with the /v1/skills endpoint. + - `shell_call: object { action, call_id, type, 5 more }` - - `version: optional string` + A tool representing a request to execute one or more shell commands. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `action: object { commands, max_output_length, timeout_ms }` - - `beta_inline_skill: object { description, name, source, type }` + The shell commands and limits that describe how to run the tool call. - - `description: string` + - `commands: array of string` - The description of the skill. + Ordered shell commands for the execution environment to run. - - `name: string` + - `max_output_length: optional number` - The name of the skill. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `source: object { data, media_type, type }` + - `timeout_ms: optional number` - Inline skill payload + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `data: string` + - `call_id: string` - Base64-encoded skill zip bundle. + The unique ID of the shell tool call generated by the model. - - `media_type: "application/zip"` + - `type: "shell_call"` - The media type of the inline skill payload. Must be `application/zip`. + The type of the item. Always `shell_call`. - - `type: "base64"` + - `id: optional string` - The type of the inline skill source. Must be `base64`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: "inline"` + - `agent: optional object { agent_name }` - Defines an inline skill for this request. + The agent that produced this item. -### Beta Container Network Policy Allowlist + - `agent_name: string` -- `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The canonical name of the agent that produced this item. - - `allowed_domains: array of string` + - `caller: optional object { type } or object { caller_id, type }` - A list of allowed domains when type is `allowlist`. + The execution context that produced this tool call. - - `type: "allowlist"` + - `direct: object { type }` - Allow outbound network access only to specified domains. Always `allowlist`. + - `program: object { caller_id, type }` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `caller_id: string` - Optional domain-scoped secrets for allowlisted domains. + The call ID of the program item that produced this tool call. - - `domain: string` + - `type: "program"` - The domain associated with the secret. + The caller type. Always `program`. - - `name: string` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - The name of the secret to inject for the domain. + The environment to execute the shell commands in. - - `value: string` + - `beta_local_environment: object { type, skills }` - The secret value to inject for the domain. + - `beta_container_reference: object { container_id, type }` -### Beta Container Network Policy Disabled + - `status: optional "in_progress" or "completed" or "incomplete"` -- `beta_container_network_policy_disabled: object { type }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `type: "disabled"` + - `"in_progress"` - Disable outbound network access. Always `disabled`. + - `"completed"` -### Beta Container Network Policy Domain Secret + - `"incomplete"` -- `beta_container_network_policy_domain_secret: object { domain, name, value }` + - `shell_call_output: object { call_id, output, type, 5 more }` - - `domain: string` + The streamed output items emitted by a shell tool call. - The domain associated with the secret. + - `call_id: string` - - `name: string` + The unique ID of the shell tool call generated by the model. - The name of the secret to inject for the domain. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `value: string` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The secret value to inject for the domain. + - `outcome: object { type } or object { exit_code, type }` -### Beta Container Reference + The exit or timeout outcome associated with this shell call. -- `beta_container_reference: object { container_id, type }` + - `timeout: object { type }` - - `container_id: string` + Indicates that the shell call exceeded its configured time limit. - The ID of the referenced container. + - `exit: object { exit_code, type }` - - `type: "container_reference"` + Indicates that the shell commands finished and returned an exit code. - References a container created with the /v1/containers endpoint + - `exit_code: number` -### Beta Custom Tool + The exit code returned by the shell process. -- `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `type: "exit"` - 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) + The outcome type. Always `exit`. - - `name: string` + - `stderr: string` - The name of the custom tool, used to identify it in tool calls. + Captured stderr output for the shell call. - - `type: "custom"` + - `stdout: string` - The type of the custom tool. Always `custom`. + Captured stdout output for the shell call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "shell_call_output"` - The tool invocation context(s). + The type of the item. Always `shell_call_output`. - - `"direct"` + - `id: optional string` - - `"programmatic"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `defer_loading: optional boolean` + - `agent: optional object { agent_name }` - Whether this tool should be deferred and discovered via tool search. + The agent that produced this item. - - `description: optional string` + - `agent_name: string` - Optional description of the custom tool, used to provide more context. + The canonical name of the agent that produced this item. - - `format: optional object { type } or object { definition, syntax, type }` + - `caller: optional object { type } or object { caller_id, type }` - The input format for the custom tool. Default is unconstrained text. + The execution context that produced this tool call. - - `text: object { type }` + - `direct: object { type }` - Unconstrained free-form text. + - `program: object { caller_id, type }` - - `grammar: object { definition, syntax, type }` + - `caller_id: string` - A grammar defined by the user. + The call ID of the program item that produced this tool call. - - `definition: string` + - `type: "program"` - The grammar definition. + The caller type. Always `program`. - - `syntax: "lark" or "regex"` + - `max_output_length: optional number` - The syntax of the grammar definition. One of `lark` or `regex`. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"lark"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"regex"` + The status of the shell call output. - - `type: "grammar"` + - `"in_progress"` - Grammar format. Always `grammar`. + - `"completed"` -### Beta Easy Input Message + - `"incomplete"` -- `beta_easy_input_message: object { content, role, phase, type }` + - `apply_patch_call: object { call_id, operation, status, 4 more }` - 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. + A tool call representing a request to create, delete, or update files using diff patches. - - `content: string or BetaResponseInputMessageContentList` + - `call_id: string` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The unique ID of the apply patch tool call generated by the model. - - `Text input: string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - A text input to the model. + The specific create, delete, or update instruction for the apply_patch tool call. - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `create_file: object { diff, path, type }` - A list of one or many input items to the model, containing different content - types. + Instruction for creating a new file via the apply_patch tool. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `diff: string` - A text input to the model. + Unified diff content to apply when creating the file. - - `text: string` + - `path: string` - The text input to the model. + Path of the file to create relative to the workspace root. - - `type: "input_text"` + - `type: "create_file"` - The type of the input item. Always `input_text`. + The operation type. Always `create_file`. - - `prompt_cache_breakpoint: optional object { mode }` + - `delete_file: object { path, type }` - 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. + Instruction for deleting an existing file via the apply_patch tool. - - `mode: "explicit"` + - `path: string` - The breakpoint mode. Always `explicit`. + Path of the file to delete relative to the workspace root. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `type: "delete_file"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The operation type. Always `delete_file`. - - `detail: "low" or "high" or "auto" or "original"` + - `update_file: object { diff, path, type }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Instruction for updating an existing file via the apply_patch tool. - - `"low"` + - `diff: string` - - `"high"` + Unified diff content to apply to the existing file. - - `"auto"` + - `path: string` - - `"original"` + Path of the file to update relative to the workspace root. - - `type: "input_image"` + - `type: "update_file"` - The type of the input item. Always `input_image`. + The operation type. Always `update_file`. - - `file_id: optional string` + - `status: "in_progress" or "completed"` - The ID of the file to be sent to the model. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `image_url: optional string` + - `"in_progress"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"completed"` - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "apply_patch_call"` - 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. + The type of the item. Always `apply_patch_call`. - - `mode: "explicit"` + - `id: optional string` - The breakpoint mode. Always `explicit`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `agent: optional object { agent_name }` - A file input to the model. + The agent that produced this item. - - `type: "input_file"` + - `agent_name: string` - The type of the input item. Always `input_file`. + The canonical name of the agent that produced this item. - - `detail: optional "auto" or "low" or "high"` + - `caller: optional object { type } or object { caller_id, type }` - 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`. + The execution context that produced this tool call. - - `"auto"` + - `direct: object { type }` - - `"low"` + - `program: object { caller_id, type }` - - `"high"` + - `caller_id: string` - - `file_data: optional string` + The call ID of the program item that produced this tool call. - The content of the file to be sent to the model. + - `type: "program"` - - `file_id: optional string` + The caller type. Always `program`. - The ID of the file to be sent to the model. + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - - `file_url: optional string` + The streamed output emitted by an apply patch tool call. - The URL of the file to be sent to the model. + - `call_id: string` - - `filename: optional string` + The unique ID of the apply patch tool call generated by the model. - The name of the file to be sent to the model. + - `status: "completed" or "failed"` - - `prompt_cache_breakpoint: optional object { mode }` + The status of the apply patch tool call output. One of `completed` or `failed`. - 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. + - `"completed"` - - `mode: "explicit"` + - `"failed"` - The breakpoint mode. Always `explicit`. + - `type: "apply_patch_call_output"` - - `role: "user" or "assistant" or "system" or "developer"` + The type of the item. Always `apply_patch_call_output`. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `id: optional string` - - `"user"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"assistant"` + - `agent: optional object { agent_name }` - - `"system"` + The agent that produced this item. - - `"developer"` + - `agent_name: string` - - `phase: optional "commentary"` + The canonical name of the agent that produced this item. - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `"commentary"` + The execution context that produced this tool call. - - `type: optional "message"` + - `direct: object { type }` - The type of the message input. Always `message`. + - `program: object { caller_id, type }` - - `"message"` + - `caller_id: string` -### Beta File Search Tool + The call ID of the program item that produced this tool call. -- `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `type: "program"` - 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). + The caller type. Always `program`. - - `type: "file_search"` + - `output: optional string` - The type of the file search tool. Always `file_search`. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `vector_store_ids: array of string` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The IDs of the vector stores to search. + A list of tools available on an MCP server. - - `filters: optional object { key, type, value } or object { filters, type }` + - `id: string` - A filter to apply. + The unique ID of the list. - - `Comparison Filter: object { key, type, value }` + - `server_label: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The label of the MCP server. - - `key: string` + - `tools: array of object { input_schema, name, annotations, description }` - The key to compare against the value. + The tools available on the server. - - `type: "eq" or "ne" or "gt" or 5 more` + - `input_schema: unknown` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The JSON schema describing the tool's input. - - `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 + - `name: string` - - `"eq"` + The name of the tool. - - `"ne"` + - `annotations: optional unknown` - - `"gt"` + Additional annotations about the tool. - - `"gte"` + - `description: optional string` - - `"lt"` + The description of the tool. - - `"lte"` + - `type: "mcp_list_tools"` - - `"in"` + The type of the item. Always `mcp_list_tools`. - - `"nin"` + - `agent: optional object { agent_name }` - - `value: string or number or boolean or array of unknown` + The agent that produced this item. - The value to compare against the attribute key; supports string, number, or boolean types. + - `agent_name: string` - - `union_member_0: string` + The canonical name of the agent that produced this item. - - `union_member_1: number` + - `error: optional string` - - `union_member_2: boolean` + Error message if the server could not list tools. - - `union_member_3: array of unknown` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `Compound Filter: object { filters, type }` + A request for human approval of a tool invocation. - Combine multiple filters using `and` or `or`. + - `id: string` - - `filters: array of object { key, type, value } or unknown` + The unique ID of the approval request. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `arguments: string` - - `Comparison Filter: object { key, type, value }` + A JSON string of arguments for the tool. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `name: string` - - `key: string` + The name of the tool to run. - The key to compare against the value. + - `server_label: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The label of the MCP server making the request. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: "mcp_approval_request"` - - `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 + The type of the item. Always `mcp_approval_request`. - - `"eq"` + - `agent: optional object { agent_name }` - - `"ne"` + The agent that produced this item. - - `"gt"` + - `agent_name: string` - - `"gte"` + The canonical name of the agent that produced this item. - - `"lt"` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - - `"lte"` + A response to an MCP approval request. - - `"in"` + - `approval_request_id: string` - - `"nin"` + The ID of the approval request being answered. - - `value: string or number or boolean or array of unknown` + - `approve: boolean` - The value to compare against the attribute key; supports string, number, or boolean types. + Whether the request was approved. - - `union_member_0: string` + - `type: "mcp_approval_response"` - - `union_member_1: number` + The type of the item. Always `mcp_approval_response`. - - `union_member_2: boolean` + - `id: optional string` - - `union_member_3: array of unknown` + The unique ID of the approval response - - `union_member_1: unknown` + - `agent: optional object { agent_name }` - - `type: "and" or "or"` + The agent that produced this item. - Type of operation: `and` or `or`. + - `agent_name: string` - - `"and"` + The canonical name of the agent that produced this item. - - `"or"` + - `reason: optional string` - - `max_num_results: optional number` + Optional reason for the decision. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `mcp_call: object { id, arguments, name, 7 more }` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + An invocation of a tool on an MCP server. - Ranking options for search. + - `id: string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The unique ID of the tool call. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `arguments: string` - - `embedding_weight: number` + A JSON string of the arguments passed to the tool. - The weight of the embedding in the reciprocal ranking fusion. + - `name: string` - - `text_weight: number` + The name of the tool that was run. - The weight of the text in the reciprocal ranking fusion. + - `server_label: string` - - `ranker: optional "auto" or "default-2024-11-15"` + The label of the MCP server running the tool. - The ranker to use for the file search. + - `type: "mcp_call"` - - `"auto"` + The type of the item. Always `mcp_call`. - - `"default-2024-11-15"` + - `agent: optional object { agent_name }` - - `score_threshold: optional number` + The agent that produced this item. - 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. + - `agent_name: string` -### Beta Function Shell Tool + The canonical name of the agent that produced this item. -- `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `approval_request_id: optional string` - A tool that allows the model to execute shell commands. + 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. - - `type: "shell"` + - `error: optional string` - The type of the shell tool. Always `shell`. + The error from the tool call, if any. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output: optional string` - The tool invocation context(s). + The output from the tool call. - - `"direct"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"programmatic"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"in_progress"` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `"completed"` - - `type: "container_auto"` + - `"incomplete"` - Automatically creates a container for this request + - `"calling"` - - `file_ids: optional array of string` + - `"failed"` - An optional list of uploaded files to make available to your code. + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The output of a custom tool call from your code, being sent back to the model. - The memory limit for the container. + - `call_id: string` - - `"1g"` + The call ID, used to map this custom tool call output to a custom tool call. - - `"4g"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"16g"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"64g"` + - `string output: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A string of the output of the custom tool call. - Network access policy for the container. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `beta_container_network_policy_disabled: object { type }` + Text, image, or file output of the custom tool call. - - `type: "disabled"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - Disable outbound network access. Always `disabled`. + A text input to the model. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `text: string` - - `allowed_domains: array of string` + The text input to the model. - A list of allowed domains when type is `allowlist`. + - `type: "input_text"` - - `type: "allowlist"` + The type of the input item. Always `input_text`. - Allow outbound network access only to specified domains. Always `allowlist`. + - `prompt_cache_breakpoint: optional object { mode }` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + 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. - Optional domain-scoped secrets for allowlisted domains. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `domain: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The domain associated with the secret. + - `detail: "low" or "high" or "auto" or "original"` - - `name: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The name of the secret to inject for the domain. + - `type: "input_image"` - - `value: string` + The type of the input item. Always `input_image`. - The secret value to inject for the domain. + - `file_id: optional string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The ID of the file to be sent to the model. - An optional list of skills referenced by id or inline data. + - `image_url: optional string` - - `beta_skill_reference: object { skill_id, type, version }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `skill_id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the referenced skill. + 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. - - `type: "skill_reference"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - References a skill created with the /v1/skills endpoint. + A file input to the model. - - `version: optional string` + - `type: "input_file"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The type of the input item. Always `input_file`. - - `beta_inline_skill: object { description, name, source, type }` + - `detail: optional "auto" or "low" or "high"` - - `description: string` + 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`. - The description of the skill. + - `file_data: optional string` - - `name: string` + The content of the file to be sent to the model. - The name of the skill. + - `file_id: optional string` - - `source: object { data, media_type, type }` + The ID of the file to be sent to the model. - Inline skill payload + - `file_url: optional string` - - `data: string` + The URL of the file to be sent to the model. - Base64-encoded skill zip bundle. + - `filename: optional string` - - `media_type: "application/zip"` + The name of the file to be sent to the model. - The media type of the inline skill payload. Must be `application/zip`. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "base64"` + 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. - The type of the inline skill source. Must be `base64`. + - `type: "custom_tool_call_output"` - - `type: "inline"` + The type of the custom tool call output. Always `custom_tool_call_output`. - Defines an inline skill for this request. + - `id: optional string` - - `beta_local_environment: object { type, skills }` + The unique ID of the custom tool call output in the OpenAI platform. - - `type: "local"` + - `agent: optional object { agent_name }` - Use a local computer environment. + The agent that produced this item. - - `skills: optional array of BetaLocalSkill` + - `agent_name: string` - An optional list of skills. + The canonical name of the agent that produced this item. - - `description: string` + - `caller: optional object { type } or object { caller_id, type }` - The description of the skill. + The execution context that produced this tool call. - - `name: string` + - `direct: object { type }` - The name of the skill. + - `program: object { caller_id, type }` - - `path: string` + - `caller_id: string` - The path to the directory containing the skill. + The call ID of the program item that produced this tool call. - - `beta_container_reference: object { container_id, type }` + - `type: "program"` - - `container_id: string` + The caller type. Always `program`. - The ID of the referenced container. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `type: "container_reference"` + A call to a custom tool created by the model. - References a container created with the /v1/containers endpoint + - `call_id: string` -### Beta Function Tool + An identifier used to map this custom tool call to a tool call output. -- `beta_function_tool: object { name, parameters, strict, 5 more }` + - `input: string` - 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). + The input for the custom tool call generated by the model. - `name: string` - The name of the function to call. + The name of the custom tool being called. - - `parameters: map[unknown]` + - `type: "custom_tool_call"` - A JSON schema object describing the parameters of the function. + The type of the custom tool call. Always `custom_tool_call`. - - `strict: boolean` + - `id: optional string` - Whether strict parameter validation is enforced for this function tool. + The unique ID of the custom tool call in the OpenAI platform. - - `type: "function"` + - `agent: optional object { agent_name }` - The type of the function tool. Always `function`. + The agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent_name: string` - The tool invocation context(s). + The canonical name of the agent that produced this item. - - `"direct"` + - `caller: optional object { type } or object { caller_id, type }` - - `"programmatic"` + The execution context that produced this tool call. - - `defer_loading: optional boolean` + - `direct: object { type }` - Whether this function is deferred and loaded via tool search. + - `program: object { caller_id, type }` - - `description: optional string` + - `caller_id: string` - A description of the function. Used by the model to determine whether or not to call the function. + The call ID of the program item that produced this tool call. - - `output_schema: optional map[unknown]` + - `type: "program"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `namespace: optional string` -### Beta Inline Skill + The namespace of the custom tool being called. -- `beta_inline_skill: object { description, name, source, type }` + - `compaction_trigger: object { type, agent }` - - `description: string` + Compacts the current context. Must be the final input item. - The description of the skill. + - `type: "compaction_trigger"` - - `name: string` + The type of the item. Always `compaction_trigger`. - The name of the skill. + - `agent: optional object { agent_name }` - - `source: object { data, media_type, type }` + The agent that produced this item. - Inline skill payload + - `agent_name: string` - - `data: string` + The canonical name of the agent that produced this item. - Base64-encoded skill zip bundle. + - `item_reference: object { id, agent, type }` - - `media_type: "application/zip"` + An internal identifier for an item to reference. - The media type of the inline skill payload. Must be `application/zip`. + - `id: string` - - `type: "base64"` + The ID of the item to reference. - The type of the inline skill source. Must be `base64`. + - `agent: optional object { agent_name }` - - `type: "inline"` + The agent that produced this item. - Defines an inline skill for this request. + - `agent_name: string` -### Beta Inline Skill Source + The canonical name of the agent that produced this item. -- `beta_inline_skill_source: object { data, media_type, type }` + - `type: optional "item_reference"` - Inline skill payload + The type of item to reference. Always `item_reference`. - - `data: string` + - `"item_reference"` - Base64-encoded skill zip bundle. + - `program: object { id, call_id, code, 3 more }` - - `media_type: "application/zip"` + - `id: string` - The media type of the inline skill payload. Must be `application/zip`. + The unique ID of this program item. - - `type: "base64"` + - `call_id: string` - The type of the inline skill source. Must be `base64`. + The stable call ID of the program item. -### Beta Local Environment + - `code: string` -- `beta_local_environment: object { type, skills }` + The JavaScript source executed by programmatic tool calling. - - `type: "local"` + - `fingerprint: string` - Use a local computer environment. + Opaque program replay fingerprint that must be round-tripped. - - `skills: optional array of BetaLocalSkill` + - `type: "program"` - An optional list of skills. + The item type. Always `program`. - - `description: string` + - `agent: optional object { agent_name }` - The description of the skill. + The agent that produced this item. - - `name: string` + - `agent_name: string` - The name of the skill. + The canonical name of the agent that produced this item. - - `path: string` + - `program_output: object { id, call_id, result, 3 more }` - The path to the directory containing the skill. + - `id: string` -### Beta Local Skill + The unique ID of this program output item. -- `beta_local_skill: object { description, name, path }` + - `call_id: string` - - `description: string` + The call ID of the program item. - The description of the skill. + - `result: string` - - `name: string` + The result produced by the program item. - The name of the skill. + - `status: "completed" or "incomplete"` - - `path: string` + The terminal status of the program output. - The path to the directory containing the skill. + - `"completed"` -### Beta Namespace Tool + - `"incomplete"` -- `beta_namespace_tool: object { description, name, tools, type }` + - `type: "program_output"` - Groups function/custom tools under a shared namespace. + The item type. Always `program_output`. - - `description: string` + - `agent: optional object { agent_name }` - A description of the namespace shown to the model. + The agent that produced this item. - - `name: string` + - `agent_name: string` - The namespace name used in tool calls (for example, `crm`). + The canonical name of the agent that produced this item. - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `metadata: map[string]` - The function/custom tools available inside this namespace. + 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. - - `function: object { name, type, allowed_callers, 5 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `name: string` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `type: "function"` + Model ID used to generate the response, like `gpt-4o` 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. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-5.6-sol"` - The tool invocation context(s). + - `"gpt-5.6-terra"` - - `"direct"` + - `"gpt-5.6-luna"` - - `"programmatic"` + - `"gpt-5.4"` - - `defer_loading: optional boolean` + - `"gpt-5.4-mini"` - Whether this function should be deferred and discovered via tool search. + - `"gpt-5.4-nano"` - - `description: optional string` + - `"gpt-5.4-mini-2026-03-17"` - - `output_schema: optional map[unknown]` + - `"gpt-5.4-nano-2026-03-17"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"gpt-5.3-chat-latest"` - - `parameters: optional unknown` + - `"gpt-5.2"` - - `strict: optional boolean` + - `"gpt-5.2-2025-12-11"` - 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. + - `"gpt-5.2-chat-latest"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `"gpt-5.2-pro"` - 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) + - `"gpt-5.2-pro-2025-12-11"` - - `name: string` + - `"gpt-5.1"` - The name of the custom tool, used to identify it in tool calls. + - `"gpt-5.1-2025-11-13"` - - `type: "custom"` + - `"gpt-5.1-codex"` - The type of the custom tool. Always `custom`. + - `"gpt-5.1-mini"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-5.1-chat-latest"` - The tool invocation context(s). + - `"gpt-5"` - - `"direct"` + - `"gpt-5-mini"` - - `"programmatic"` + - `"gpt-5-nano"` - - `defer_loading: optional boolean` + - `"gpt-5-2025-08-07"` - Whether this tool should be deferred and discovered via tool search. + - `"gpt-5-mini-2025-08-07"` - - `description: optional string` + - `"gpt-5-nano-2025-08-07"` - Optional description of the custom tool, used to provide more context. + - `"gpt-5-chat-latest"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"gpt-4.1"` - The input format for the custom tool. Default is unconstrained text. + - `"gpt-4.1-mini"` - - `text: object { type }` + - `"gpt-4.1-nano"` - Unconstrained free-form text. + - `"gpt-4.1-2025-04-14"` - - `grammar: object { definition, syntax, type }` + - `"gpt-4.1-mini-2025-04-14"` - A grammar defined by the user. + - `"gpt-4.1-nano-2025-04-14"` - - `definition: string` + - `"o4-mini"` - The grammar definition. + - `"o4-mini-2025-04-16"` - - `syntax: "lark" or "regex"` + - `"o3"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"o3-2025-04-16"` - - `"lark"` + - `"o3-mini"` - - `"regex"` + - `"o3-mini-2025-01-31"` - - `type: "grammar"` + - `"o1"` - Grammar format. Always `grammar`. + - `"o1-2024-12-17"` - - `type: "namespace"` + - `"o1-preview"` - The type of the tool. Always `namespace`. + - `"o1-preview-2024-09-12"` -### Beta Response + - `"o1-mini"` -- `beta_response: object { id, created_at, error, 31 more }` + - `"o1-mini-2024-09-12"` - - `id: string` + - `"gpt-4o"` - Unique identifier for this Response. + - `"gpt-4o-2024-11-20"` - - `created_at: number` + - `"gpt-4o-2024-08-06"` - Unix timestamp (in seconds) of when this Response was created. + - `"gpt-4o-2024-05-13"` - - `error: object { code, message }` + - `"gpt-4o-audio-preview"` - An error object returned when the model fails to generate a Response. + - `"gpt-4o-audio-preview-2024-10-01"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `"gpt-4o-audio-preview-2024-12-17"` - The error code for the response. + - `"gpt-4o-audio-preview-2025-06-03"` - - `"server_error"` + - `"gpt-4o-mini-audio-preview"` - - `"rate_limit_exceeded"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` + + - `"gpt-4o-search-preview"` + + - `"gpt-4o-mini-search-preview"` - - `"invalid_prompt"` + - `"gpt-4o-search-preview-2025-03-11"` - - `"bio_policy"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"vector_store_timeout"` + - `"chatgpt-4o-latest"` - - `"invalid_image"` + - `"codex-mini-latest"` - - `"invalid_image_format"` + - `"gpt-4o-mini"` - - `"invalid_base64_image"` + - `"gpt-4o-mini-2024-07-18"` - - `"invalid_image_url"` + - `"gpt-4-turbo"` - - `"image_too_large"` + - `"gpt-4-turbo-2024-04-09"` - - `"image_too_small"` + - `"gpt-4-0125-preview"` - - `"image_parse_error"` + - `"gpt-4-turbo-preview"` - - `"image_content_policy_violation"` + - `"gpt-4-1106-preview"` - - `"invalid_image_mode"` + - `"gpt-4-vision-preview"` - - `"image_file_too_large"` + - `"gpt-4"` - - `"unsupported_image_media_type"` + - `"gpt-4-0314"` - - `"empty_image_file"` + - `"gpt-4-0613"` - - `"failed_to_download_image"` + - `"gpt-4-32k"` - - `"image_file_not_found"` + - `"gpt-4-32k-0314"` - - `message: string` + - `"gpt-4-32k-0613"` - A human-readable description of the error. + - `"gpt-3.5-turbo"` - - `incomplete_details: object { reason }` + - `"gpt-3.5-turbo-16k"` - Details about why the response is incomplete. + - `"gpt-3.5-turbo-0301"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `"gpt-3.5-turbo-0613"` - The reason why the response is incomplete. + - `"gpt-3.5-turbo-1106"` - - `"max_output_tokens"` + - `"gpt-3.5-turbo-0125"` - - `"content_filter"` + - `"gpt-3.5-turbo-16k-0613"` - - `instructions: string or array of BetaResponseInputItem` + - `"o1-pro"` - A system (or developer) message inserted into the model's context. + - `"o1-pro-2025-03-19"` - When using 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. + - `"o3-pro"` - - `union_member_0: string` + - `"o3-pro-2025-06-10"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `"o3-deep-research"` - - `Input item list: array of BetaResponseInputItem` + - `"o3-deep-research-2025-06-26"` - A list of one or many input items to the model, containing - different content types. + - `"o4-mini-deep-research"` - - `beta_easy_input_message: object { content, role, phase, type }` + - `"o4-mini-deep-research-2025-06-26"` - 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. + - `"computer-use-preview"` - - `content: string or BetaResponseInputMessageContentList` + - `"computer-use-preview-2025-03-11"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"gpt-5-codex"` - - `Text input: string` + - `"gpt-5-pro"` - A text input to the model. + - `"gpt-5-pro-2025-10-06"` - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `"gpt-5.1-codex-max"` - A list of one or many input items to the model, containing different content - types. + - `object: "response"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The object type of this resource - always set to `response`. - A text input to the model. + - `output: array of BetaResponseOutputItem` - - `text: string` + An array of content items generated by the model. - The text input to the model. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `type: "input_text"` + - `beta_response_output_message: object { id, content, role, 4 more }` - The type of the input item. Always `input_text`. + An output message from the model. - - `prompt_cache_breakpoint: optional object { mode }` + - `id: string` - 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. + The unique ID of the output message. - - `mode: "explicit"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The breakpoint mode. Always `explicit`. + The content of the output message. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `role: "assistant"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The role of the output message. Always `assistant`. - - `detail: "low" or "high" or "auto" or "original"` + - `status: "in_progress" or "completed" or "incomplete"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"low"` + - `type: "message"` - - `"high"` + The type of the output message. Always `message`. - - `"auto"` + - `agent: optional object { agent_name }` - - `"original"` + The agent that produced this item. - - `type: "input_image"` + - `phase: optional "commentary" or "final_answer"` - The type of the input item. Always `input_image`. + 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. - - `file_id: optional string` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The ID of the file to be sent to the model. + 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. - - `image_url: optional string` + - `id: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The unique ID of the file search tool call. - - `prompt_cache_breakpoint: optional object { mode }` + - `queries: array of string` - 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. + The queries used to search for files. - - `mode: "explicit"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The breakpoint mode. Always `explicit`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `type: "file_search_call"` - A file input to the model. + The type of the file search tool call. Always `file_search_call`. - - `type: "input_file"` + - `agent: optional object { agent_name }` - The type of the input item. Always `input_file`. + The agent that produced this item. - - `detail: optional "auto" or "low" or "high"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - 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`. + The results of the file search tool call. - - `"auto"` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `"low"` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `"high"` + - `arguments: string` - - `file_data: optional string` + A JSON string of the arguments to pass to the function. - The content of the file to be sent to the model. + - `call_id: string` - - `file_id: optional string` + The unique ID of the function tool call generated by the model. - The ID of the file to be sent to the model. + - `name: string` - - `file_url: optional string` + The name of the function to run. - The URL of the file to be sent to the model. + - `type: "function_call"` - - `filename: optional string` + The type of the function tool call. Always `function_call`. - The name of the file to be sent to the model. + - `id: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique ID of the function tool call. - 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. + - `agent: optional object { agent_name }` - - `mode: "explicit"` + The agent that produced this item. - The breakpoint mode. Always `explicit`. + - `caller: optional object { type } or object { caller_id, type }` - - `role: "user" or "assistant" or "system" or "developer"` + The execution context that produced this tool call. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `namespace: optional string` - - `"user"` + The namespace of the function to run. - - `"assistant"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"system"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"developer"` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `phase: optional "commentary"` + - `id: string` - 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. + The unique ID of the function call tool output. - - `"commentary"` + - `call_id: string` - - `type: optional "message"` + The unique ID of the function tool call generated by the model. - The type of the message input. Always `message`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"message"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `message: object { content, role, agent, 2 more }` + - `string output: string` - 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. + A string of the output of the function call. - - `content: array of BetaResponseInputContent` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A list of one or many input items to the model, containing different content - types. + Text, image, or file output of the function call. - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` @@ -42814,15 +53193,20 @@ openai beta:responses compact \ A file input to the model. - - `role: "user" or "system" or "developer"` + - `status: "in_progress" or "completed" or "incomplete"` - The role of the message input. One of `user`, `system`, or `developer`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"user"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"developer"` + - `"incomplete"` + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` @@ -42832,185 +53216,189 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `caller: optional object { type } or object { caller_id, type }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The execution context that produced this tool call. - - `"in_progress"` + - `direct: object { type }` - - `"completed"` + - `program: object { caller_id, type }` - - `"incomplete"` + - `caller_id: string` - - `type: optional "message"` + The call ID of the program item that produced this tool call. - The type of the message input. Always set to `message`. + - `type: "program"` - - `"message"` + The caller type. Always `program`. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `created_by: optional string` - An output message from the model. + The identifier of the actor that created the item. + + - `agent_message: object { id, author, content, 3 more }` - `id: string` - The unique ID of the output message. + The unique ID of the agent message. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `author: string` - The content of the output message. + The sending agent identity. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - A text output from the model. + Encrypted content sent between agents. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The annotations of the text output. + A text input to the model. - - `file_citation: object { file_id, filename, index, type }` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - A citation to a file. + A text output from the model. - - `file_id: string` + - `text: object { text, type }` - The ID of the file. + A text content. - - `filename: string` + - `text: string` - The filename of the file cited. + - `type: "text"` - - `index: number` + - `summary_text: object { text, type }` - The index of the file in the list of files. + A summary text from the model. - - `type: "file_citation"` + - `text: string` - The type of the file citation. Always `file_citation`. + A summary of the reasoning output from the model so far. - - `url_citation: object { end_index, start_index, title, 2 more }` + - `type: "summary_text"` - A citation for a web resource used to generate a model response. + The type of the object. Always `summary_text`. - - `end_index: number` + - `reasoning_text: object { text, type }` - The index of the last character of the URL citation in the message. + Reasoning text from the model. - - `start_index: number` + - `text: string` - The index of the first character of the URL citation in the message. + The reasoning text from the model. - - `title: string` + - `type: "reasoning_text"` - The title of the web resource. + The type of the reasoning text. Always `reasoning_text`. - - `type: "url_citation"` + - `beta_response_output_refusal: object { refusal, type }` - The type of the URL citation. Always `url_citation`. + A refusal from the model. - - `url: string` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The URL of the web resource. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - A citation for a container file used to generate a model response. + A screenshot of a computer. - - `container_id: string` + - `detail: "low" or "high" or "auto" or "original"` - The ID of the container file. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `end_index: number` + - `"low"` - The index of the last character of the container file citation in the message. + - `"high"` + + - `"auto"` + + - `"original"` - `file_id: string` - The ID of the file. + The identifier of an uploaded file that contains the screenshot. - - `filename: string` + - `image_url: string` - The filename of the container file cited. + The URL of the screenshot image. - - `start_index: number` + - `type: "computer_screenshot"` - The index of the first character of the container file citation in the message. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `type: "container_file_citation"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the container file citation. Always `container_file_citation`. + 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. - - `file_path: object { file_id, index, type }` + - `mode: "explicit"` - A path to a file. + The breakpoint mode. Always `explicit`. - - `file_id: string` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The ID of the file. + A file input to the model. - - `index: number` + - `encrypted_content: object { encrypted_content, type }` - The index of the file in the list of files. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: "file_path"` + - `encrypted_content: string` - The type of the file path. Always `file_path`. + Opaque encrypted content. - - `text: string` + - `type: "encrypted_content"` - The text output from the model. + The type of the input item. Always `encrypted_content`. - - `type: "output_text"` + - `recipient: string` - The type of the output text. Always `output_text`. + The destination agent identity. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "agent_message"` - - `token: string` + The type of the item. Always `agent_message`. - - `bytes: array of number` + - `agent: optional object { agent_name }` - - `logprob: number` + The agent that produced this item. - - `top_logprobs: array of object { token, bytes, logprob }` + - `agent_name: string` - - `token: string` + The canonical name of the agent that produced this item. - - `bytes: array of number` + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `logprob: number` + - `id: string` - - `beta_response_output_refusal: object { refusal, type }` + The unique ID of the multi-agent call item. - A refusal from the model. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `refusal: string` + The multi-agent action to execute. - The refusal explanation from the model. + - `"spawn_agent"` - - `type: "refusal"` + - `"interrupt_agent"` - The type of the refusal. Always `refusal`. + - `"list_agents"` - - `role: "assistant"` + - `"send_message"` - The role of the output message. Always `assistant`. + - `"followup_task"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"wait_agent"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `arguments: string` - - `"in_progress"` + The JSON string of arguments generated for the action. - - `"completed"` + - `call_id: string` - - `"incomplete"` + The unique ID linking this call to its output. - - `type: "message"` + - `type: "multi_agent_call"` - The type of the output message. Always `message`. + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` @@ -43020,45 +53408,53 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - 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. + - `id: string` - - `"commentary"` + The unique ID of the multi-agent call output item. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - 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. + The multi-agent action that produced this result. - - `id: string` + - `"spawn_agent"` - The unique ID of the file search tool call. + - `"interrupt_agent"` - - `queries: array of string` + - `"list_agents"` - The queries used to search for files. + - `"send_message"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"followup_task"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"wait_agent"` - - `"in_progress"` + - `call_id: string` - - `"searching"` + The unique ID of the multi-agent call. - - `"completed"` + - `output: array of BetaResponseOutputText` - - `"incomplete"` + Text output returned by the multi-agent action. - - `"failed"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `type: "file_search_call"` + The annotations of the text output. - The type of the file search tool call. Always `file_search_call`. + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `type: "multi_agent_call_output"` + + The type of the multi-agent result. Always `multi_agent_call_output`. - `agent: optional object { agent_name }` @@ -43068,39 +53464,31 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. - - - `attributes: optional map[string or number or boolean]` - - 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. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `union_member_0: string` + 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. - - `union_member_1: number` + - `id: string` - - `union_member_2: boolean` + The unique ID of the web search tool call. - - `file_id: optional string` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The unique ID of the file. + 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). - - `filename: optional string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The name of the file. + The status of the web search tool call. - - `score: optional number` + - `type: "web_search_call"` - The relevance score of the file - a value between 0 and 1. + The type of the web search tool call. Always `web_search_call`. - - `text: optional string` + - `agent: optional object { agent_name }` - The text that was retrieved from the file. + The agent that produced this item. - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` @@ -43119,629 +53507,608 @@ openai beta:responses compact \ The pending safety checks for the computer call. - - `id: string` - - The ID of the pending safety check. - - - `code: optional string` - - The type of the pending safety check. - - - `message: optional string` - - Details about the pending safety check. - - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: "computer_call"` The type of the computer call. Always `computer_call`. - - `"computer_call"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. - - `click: object { button, type, x, 2 more }` - - A click action. - - - `button: "left" or "right" or "wheel" or 2 more` + - `actions: optional array of BetaComputerAction` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"left"` + - `agent: optional object { agent_name }` - - `"right"` + The agent that produced this item. - - `"wheel"` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - `"back"` + - `id: string` - - `"forward"` + The unique ID of the computer call tool output. - - `type: "click"` + - `call_id: string` - Specifies the event type. For a click action, this property is always `click`. + The ID of the computer tool call that produced the output. - - `x: number` + - `output: object { type, file_id, image_url }` - The x-coordinate where the click occurred. + A computer screenshot image used with the computer use tool. - - `y: number` + - `type: "computer_screenshot"` - The y-coordinate where the click occurred. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `keys: optional array of string` + - `file_id: optional string` - The keys being held while clicking. + The identifier of an uploaded file that contains the screenshot. - - `double_click: object { keys, type, x, y }` + - `image_url: optional string` - A double click action. + The URL of the screenshot image. - - `keys: array of string` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The keys being held while double-clicking. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `type: "double_click"` + - `"completed"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"incomplete"` - - `x: number` + - `"failed"` - The x-coordinate where the double click occurred. + - `"in_progress"` - - `y: number` + - `type: "computer_call_output"` - The y-coordinate where the double click occurred. + The type of the computer tool call output. Always `computer_call_output`. - - `drag: object { path, type, keys }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - A drag action. + The safety checks reported by the API that have been acknowledged by the + developer. - - `path: array of object { x, y }` + - `id: string` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The ID of the pending safety check. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `code: optional string` - - `x: number` + The type of the pending safety check. - The x-coordinate. + - `message: optional string` - - `y: number` + Details about the pending safety check. - The y-coordinate. + - `agent: optional object { agent_name }` - - `type: "drag"` + The agent that produced this item. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `agent_name: string` - - `keys: optional array of string` + The canonical name of the agent that produced this item. - The keys being held while dragging the mouse. + - `created_by: optional string` - - `keypress: object { keys, type }` + The identifier of the actor that created the item. - A collection of keypresses the model would like to perform. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `keys: array of string` + 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). - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `id: string` - - `type: "keypress"` + The unique identifier of the reasoning content. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `summary: array of object { text, type }` - - `move: object { type, x, y, keys }` + Reasoning summary content. - A mouse move action. + - `type: "reasoning"` - - `type: "move"` + The type of the object. Always `reasoning`. - Specifies the event type. For a move action, this property is always set to `move`. + - `agent: optional object { agent_name }` - - `x: number` + The agent that produced this item. - The x-coordinate to move to. + - `content: optional array of object { text, type }` - - `y: number` + Reasoning text content. - The y-coordinate to move to. + - `encrypted_content: optional string` - - `keys: optional array of string` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The keys being held while moving the mouse. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `screenshot: object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A screenshot action. + - `program: object { id, call_id, code, 3 more }` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `id: string` - A scroll action. + The unique ID of the program item. - - `scroll_x: number` + - `call_id: string` - The horizontal scroll distance. + The stable call ID of the program item. - - `scroll_y: number` + - `code: string` - The vertical scroll distance. + The JavaScript source executed by programmatic tool calling. - - `type: "scroll"` + - `fingerprint: string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Opaque program replay fingerprint that must be round-tripped. - - `x: number` + - `type: "program"` - The x-coordinate where the scroll occurred. + The type of the item. Always `program`. - - `y: number` + - `agent: optional object { agent_name }` - The y-coordinate where the scroll occurred. + The agent that produced this item. - - `keys: optional array of string` + - `agent_name: string` - The keys being held while scrolling. + The canonical name of the agent that produced this item. - - `type: object { text, type }` + - `program_output: object { id, call_id, result, 3 more }` - An action to type in text. + - `id: string` - - `text: string` + The unique ID of the program output item. - The text to type. + - `call_id: string` - - `type: "type"` + The call ID of the program item. - Specifies the event type. For a type action, this property is always set to `type`. + - `result: string` - - `wait: object { type }` + The result produced by the program item. - A wait action. + - `status: "completed" or "incomplete"` - - `actions: optional array of BetaComputerAction` + The terminal status of the program output item. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"completed"` - - `click: object { button, type, x, 2 more }` + - `"incomplete"` - A click action. + - `type: "program_output"` - - `double_click: object { keys, type, x, y }` + The type of the item. Always `program_output`. - A double click action. + - `agent: optional object { agent_name }` - - `drag: object { path, type, keys }` + The agent that produced this item. - A drag action. + - `agent_name: string` - - `keypress: object { keys, type }` + The canonical name of the agent that produced this item. - A collection of keypresses the model would like to perform. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `move: object { type, x, y, keys }` + - `id: string` - A mouse move action. + The unique ID of the tool search call item. - - `screenshot: object { type }` + - `arguments: unknown` - A screenshot action. + Arguments used for the tool search call. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `call_id: string` - A scroll action. + The unique ID of the tool search call generated by the model. - - `type: object { text, type }` + - `execution: "server" or "client"` - An action to type in text. + Whether tool search was executed by the server or by the client. - - `wait: object { type }` + - `"server"` - A wait action. + - `"client"` - - `agent: optional object { agent_name }` + - `status: "in_progress" or "completed" or "incomplete"` - The agent that produced this item. + The status of the tool search call item that was recorded. - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"completed"` - - `computer_call_output: object { call_id, output, type, 4 more }` + - `"incomplete"` - The output of a computer tool call. + - `type: "tool_search_call"` - - `call_id: string` + The type of the item. Always `tool_search_call`. - The ID of the computer tool call that produced the output. + - `agent: optional object { agent_name }` - - `output: object { type, file_id, image_url }` + The agent that produced this item. - A computer screenshot image used with the computer use tool. + - `agent_name: string` - - `type: "computer_screenshot"` + The canonical name of the agent that produced this item. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `created_by: optional string` - - `file_id: optional string` + The identifier of the actor that created the item. - The identifier of an uploaded file that contains the screenshot. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `image_url: optional string` + - `id: string` - The URL of the screenshot image. + The unique ID of the tool search output item. - - `type: "computer_call_output"` + - `call_id: string` - The type of the computer tool call output. Always `computer_call_output`. + The unique ID of the tool search call generated by the model. - - `id: optional string` + - `execution: "server" or "client"` - The ID of the computer tool call output. + Whether tool search was executed by the server or by the client. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"server"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"client"` - - `id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The ID of the pending safety check. + The status of the tool search output item that was recorded. - - `code: optional string` + - `"in_progress"` - The type of the pending safety check. + - `"completed"` - - `message: optional string` + - `"incomplete"` - Details about the pending safety check. + - `tools: array of BetaTool` - - `agent: optional object { agent_name }` + The loaded tool definitions returned by tool search. - The agent that produced this item. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + 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). - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `beta_computer_tool: object { type }` - - `"in_progress"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"completed"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `"incomplete"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - 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. + 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). - - `id: string` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The unique ID of the web search tool call. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `code_interpreter: object { container, type, allowed_callers }` - 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). + A tool that runs Python code to help generate a response to a prompt. - - `search: object { type, queries, query, sources }` + - `programmatic_tool_calling: object { type }` - Action type "search" - Performs a web search query. + - `image_generation: object { type, action, background, 9 more }` - - `type: "search"` + A tool that generates images using the GPT image models. - The action type. + - `local_shell: object { type }` - - `queries: optional array of string` + A tool that allows the model to execute shell commands in a local environment. - The search queries. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `query: optional string` + A tool that allows the model to execute shell commands. - The search query. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `sources: optional array of object { type, url }` + 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) - The sources used in the search. + - `beta_namespace_tool: object { description, name, tools, type }` - - `type: "url"` + Groups function/custom tools under a shared namespace. - The type of source. Always `url`. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `url: string` + Hosted or BYOT tool search configuration for deferred tools. - The URL of the source. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `open_page: object { type, url }` + 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). - Action type "open_page" - Opens a specific URL from search results. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `type: "open_page"` + Allows the assistant to create, delete, or update files using unified diffs. - The action type. + - `type: "tool_search_output"` - - `url: optional string` + The type of the item. Always `tool_search_output`. - The URL opened by the model. + - `agent: optional object { agent_name }` - - `find_in_page: object { pattern, type, url }` + The agent that produced this item. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `agent_name: string` - - `pattern: string` + The canonical name of the agent that produced this item. - The pattern or text to search for within the page. + - `created_by: optional string` - - `type: "find_in_page"` + The identifier of the actor that created the item. - The action type. + - `additional_tools: object { id, role, tools, 2 more }` - - `url: string` + - `id: string` - The URL of the page searched for the pattern. + The unique ID of the additional tools item. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The status of the web search tool call. + The role that provided the additional tools. - - `"in_progress"` + - `"unknown"` - - `"searching"` + - `"user"` - - `"completed"` + - `"assistant"` - - `"failed"` + - `"system"` - - `type: "web_search_call"` + - `"critic"` - The type of the web search tool call. Always `web_search_call`. + - `"discriminator"` - - `agent: optional object { agent_name }` + - `"developer"` - The agent that produced this item. + - `"tool"` - - `agent_name: string` + - `tools: array of BetaTool` - The canonical name of the agent that produced this item. + The additional tool definitions made available at this item. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + 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). - - `arguments: string` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - A JSON string of the arguments to pass to the function. + 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). - - `call_id: string` + - `beta_computer_tool: object { type }` - The unique ID of the function tool call generated by the model. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `name: string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The name of the function to run. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "function_call"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the function tool call. Always `function_call`. + 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). - - `id: optional string` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The unique ID of the function tool call. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `agent: optional object { agent_name }` + - `code_interpreter: object { container, type, allowed_callers }` - The agent that produced this item. + A tool that runs Python code to help generate a response to a prompt. - - `agent_name: string` + - `programmatic_tool_calling: object { type }` - The canonical name of the agent that produced this item. + - `image_generation: object { type, action, background, 9 more }` - - `caller: optional object { type } or object { caller_id, type }` + A tool that generates images using the GPT image models. - The execution context that produced this tool call. + - `local_shell: object { type }` - - `direct: object { type }` + A tool that allows the model to execute shell commands in a local environment. - - `program: object { caller_id, type }` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `caller_id: string` + A tool that allows the model to execute shell commands. - The call ID of the program item that produced this tool call. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `type: "program"` + 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) - - `namespace: optional string` + - `beta_namespace_tool: object { description, name, tools, type }` - The namespace of the function to run. + Groups function/custom tools under a shared namespace. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Hosted or BYOT tool search configuration for deferred tools. - - `"in_progress"` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"completed"` + 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). - - `"incomplete"` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `function_call_output: object { call_id, output, type, 4 more }` + Allows the assistant to create, delete, or update files using unified diffs. - The output of a function tool call. + - `type: "additional_tools"` - - `call_id: string` + The type of the item. Always `additional_tools`. - The unique ID of the function tool call generated by the model. + - `agent: optional object { agent_name }` - - `output: string or BetaResponseFunctionCallOutputItemList` + The agent that produced this item. - Text, image, or file output of the function tool call. + - `agent_name: string` - - `union_member_0: string` + The canonical name of the agent that produced this item. - A JSON string of the output of the function tool call. + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - An array of content outputs (text, image, file) for the function tool call. + - `id: string` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + The unique ID of the compaction item. - A text input to the model. + - `encrypted_content: string` - - `text: string` + The encrypted content that was produced by compaction. - The text input to the model. + - `type: "compaction"` - - `type: "input_text"` + The type of the item. Always `compaction`. - The type of the input item. Always `input_text`. + - `agent: optional object { agent_name }` - - `prompt_cache_breakpoint: optional object { mode }` + The agent that produced this item. - 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. + - `agent_name: string` - - `mode: "explicit"` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. + - `created_by: optional string` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + The identifier of the actor that created the item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `image_generation_call: object { id, result, status, 2 more }` - - `type: "input_image"` + An image generation request made by the model. - The type of the input item. Always `input_image`. + - `id: string` - - `detail: optional "low" or "high" or "auto" or "original"` + The unique ID of the image generation call. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `result: string` - - `"low"` + The generated image encoded in base64. - - `"high"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"auto"` + The status of the image generation call. - - `"original"` + - `"in_progress"` - - `file_id: optional string` + - `"completed"` - The ID of the file to be sent to the model. + - `"generating"` - - `image_url: optional string` + - `"failed"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: "image_generation_call"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of the image generation call. Always `image_generation_call`. - 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. + - `agent: optional object { agent_name }` - - `mode: "explicit"` + The agent that produced this item. - The breakpoint mode. Always `explicit`. + - `agent_name: string` - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + The canonical name of the agent that produced this item. - A file input to the model. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `type: "input_file"` + A tool call to run code. - The type of the input item. Always `input_file`. + - `id: string` - - `detail: optional "auto" or "low" or "high"` + The unique ID of the code interpreter tool call. - 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`. + - `code: string` - - `"auto"` + The code to run, or null if not available. - - `"low"` + - `container_id: string` - - `"high"` + The ID of the container used to run the code. - - `file_data: optional string` + - `outputs: array of object { logs, type } or object { type, url }` - The base64-encoded data of the file to be sent to the model. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `file_id: optional string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The ID of the file to be sent to the model. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `file_url: optional string` + - `type: "code_interpreter_call"` - The URL of the file to be sent to the model. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `filename: optional string` + - `agent: optional object { agent_name }` - The name of the file to be sent to the model. + The agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `local_shell_call: object { id, action, call_id, 3 more }` - 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. + A tool call to run a command on the local shell. - - `mode: "explicit"` + - `id: string` - The breakpoint mode. Always `explicit`. + The unique ID of the local shell call. - - `type: "function_call_output"` + - `action: object { command, env, type, 3 more }` - The type of the function tool call output. Always `function_call_output`. + Execute a shell command on the server. - - `id: optional string` + - `command: array of string` - The unique ID of the function tool call output. Populated when this item is returned via API. + The command to run. - - `agent: optional object { agent_name }` + - `env: map[string]` - The agent that produced this item. + Environment variables to set for the command. - - `agent_name: string` + - `type: "exec"` - The canonical name of the agent that produced this item. + The type of the local shell action. Always `exec`. - - `caller: optional object { type } or object { caller_id, type }` + - `timeout_ms: optional number` - The execution context that produced this tool call. + Optional timeout in milliseconds for the command. - - `direct: object { type }` + - `user: optional string` - - `program: object { caller_id, type }` + Optional user to run the command as. - - `caller_id: string` + - `working_directory: optional string` - The call ID of the program item that produced this tool call. + Optional working directory to run the command in. - - `type: "program"` + - `call_id: string` - The caller type. Always `program`. + The unique ID of the local shell tool call generated by the model. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the local shell call. - `"in_progress"` @@ -43749,123 +54116,113 @@ openai beta:responses compact \ - `"incomplete"` - - `agent_message: object { author, content, recipient, 3 more }` - - A message routed between agents. - - - `author: string` - - The sending agent identity. - - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - Plaintext, image, or encrypted content sent between agents. + - `type: "local_shell_call"` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + The type of the local shell call. Always `local_shell_call`. - A text input to the model. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The text input to the model. + - `agent_name: string` - - `type: "input_text"` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_text`. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `prompt_cache_breakpoint: optional object { mode }` + The output of a local shell tool call. - 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. + - `id: string` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + The unique ID of the local shell tool call generated by the model. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `output: string` - - `type: "input_image"` + A JSON string of the output of the local shell tool call. - The type of the input item. Always `input_image`. + - `type: "local_shell_call_output"` - - `detail: optional "low" or "high" or "auto" or "original"` + The type of the local shell tool call output. Always `local_shell_call_output`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `agent: optional object { agent_name }` - - `file_id: optional string` + The agent that produced this item. - The ID of the file to be sent to the model. + - `agent_name: string` - - `image_url: optional string` + The canonical name of the agent that produced this item. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `prompt_cache_breakpoint: optional object { mode }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - 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. + - `"in_progress"` - - `encrypted_content: object { encrypted_content, type }` + - `"completed"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"incomplete"` - - `encrypted_content: string` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - Opaque encrypted content. + A tool call that executes one or more shell commands in a managed environment. - - `type: "encrypted_content"` + - `id: string` - The type of the input item. Always `encrypted_content`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `recipient: string` + - `action: object { commands, max_output_length, timeout_ms }` - The destination agent identity. + The shell commands and limits that describe how to run the tool call. - - `type: "agent_message"` + - `commands: array of string` - The item type. Always `agent_message`. + - `max_output_length: number` - - `id: optional string` + Optional maximum number of characters to return from each command. - The unique ID of this agent message item. + - `timeout_ms: number` - - `agent: optional object { agent_name }` + Optional timeout in milliseconds for the commands. - The agent that produced this item. + - `call_id: string` - - `agent_name: string` + The unique ID of the shell tool call generated by the model. - The canonical name of the agent that produced this item. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `multi_agent_call: object { action, arguments, call_id, 3 more }` + Represents the use of a local environment to perform shell actions. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `beta_response_local_environment: object { type }` - The multi-agent action that was executed. + Represents the use of a local environment to perform shell actions. - - `"spawn_agent"` + - `type: "local"` - - `"interrupt_agent"` + The environment type. Always `local`. - - `"list_agents"` + - `beta_response_container_reference: object { container_id, type }` - - `"send_message"` + Represents a container created with /v1/containers. - - `"followup_task"` + - `container_id: string` - - `"wait_agent"` + - `type: "container_reference"` - - `arguments: string` + The environment type. Always `container_reference`. - The action arguments as a JSON string. + - `status: "in_progress" or "completed" or "incomplete"` - - `call_id: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The unique ID linking this call to its output. + - `"in_progress"` - - `type: "multi_agent_call"` + - `"completed"` - The item type. Always `multi_agent_call`. + - `"incomplete"` - - `id: optional string` + - `type: "shell_call"` - The unique ID of this multi-agent call. + The type of the item. Always `shell_call`. - `agent: optional object { agent_name }` @@ -43875,716 +54232,708 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The execution context that produced this tool call. - The multi-agent action that produced this result. + - `direct: object { type }` - - `"spawn_agent"` + - `program: object { caller_id, type }` - - `"interrupt_agent"` + - `caller_id: string` - - `"list_agents"` + The call ID of the program item that produced this tool call. - - `"send_message"` + - `type: "program"` - - `"followup_task"` + - `created_by: optional string` - - `"wait_agent"` + The ID of the entity that created this tool call. - - `call_id: string` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - The unique ID of the multi-agent call. + The output of a shell tool call that was emitted. - - `output: array of object { text, type, annotations }` + - `id: string` - Text output returned by the multi-agent action. + The unique ID of the shell call output. Populated when this item is returned via API. - - `text: string` + - `call_id: string` - The text content. + The unique ID of the shell tool call generated by the model. - - `type: "output_text"` + - `max_output_length: number` - The content type. Always `output_text`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `output: array of object { outcome, stderr, stdout, created_by }` - Citations associated with the text content. + An array of shell call output contents - - `union_member_0: array of object { file_id, filename, index, type }` + - `outcome: object { type } or object { exit_code, type }` - - `file_id: string` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The ID of the file. + - `timeout: object { type }` - - `filename: string` + Indicates that the shell call exceeded its configured time limit. - The filename of the file cited. + - `exit: object { exit_code, type }` - - `index: number` + Indicates that the shell commands finished and returned an exit code. - The index of the file in the list of files. + - `exit_code: number` - - `type: "file_citation"` + Exit code from the shell process. - The citation type. Always `file_citation`. + - `type: "exit"` - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + The outcome type. Always `exit`. - - `end_index: number` + - `stderr: string` - The index of the last character of the citation in the message. + The standard error output that was captured. - - `start_index: number` + - `stdout: string` - The index of the first character of the citation in the message. + The standard output that was captured. - - `title: string` + - `created_by: optional string` - The title of the cited resource. + The identifier of the actor that created the item. - - `type: "url_citation"` + - `status: "in_progress" or "completed" or "incomplete"` - The citation type. Always `url_citation`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `url: string` + - `"in_progress"` - The URL of the cited resource. + - `"completed"` - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + - `"incomplete"` - - `container_id: string` + - `type: "shell_call_output"` - The ID of the container. + The type of the shell call output. Always `shell_call_output`. - - `end_index: number` + - `agent: optional object { agent_name }` - The index of the last character of the citation in the message. + The agent that produced this item. - - `file_id: string` + - `agent_name: string` - The ID of the container file. + The canonical name of the agent that produced this item. - - `filename: string` + - `caller: optional object { type } or object { caller_id, type }` - The filename of the container file cited. + The execution context that produced this tool call. - - `start_index: number` + - `direct: object { type }` - The index of the first character of the citation in the message. + - `program: object { caller_id, type }` - - `type: "container_file_citation"` + - `caller_id: string` - The citation type. Always `container_file_citation`. + The call ID of the program item that produced this tool call. - - `type: "multi_agent_call_output"` + - `type: "program"` - The item type. Always `multi_agent_call_output`. + - `created_by: optional string` - - `id: optional string` + The identifier of the actor that created the item. - The unique ID of this multi-agent call output. + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `agent: optional object { agent_name }` + A tool call that applies file diffs by creating, deleting, or updating files. - The agent that produced this item. + - `id: string` - - `agent_name: string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The canonical name of the agent that produced this item. + - `call_id: string` - - `tool_search_call: object { arguments, type, id, 4 more }` + The unique ID of the apply patch tool call generated by the model. - - `arguments: unknown` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The arguments supplied to the tool search call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `type: "tool_search_call"` + - `create_file: object { diff, path, type }` - The item type. Always `tool_search_call`. + Instruction describing how to create a file via the apply_patch tool. - - `id: optional string` + - `diff: string` - The unique ID of this tool search call. + Diff to apply. - - `agent: optional object { agent_name }` + - `path: string` - The agent that produced this item. + Path of the file to create. - - `agent_name: string` + - `type: "create_file"` - The canonical name of the agent that produced this item. + Create a new file with the provided diff. - - `call_id: optional string` + - `delete_file: object { path, type }` - The unique ID of the tool search call generated by the model. + Instruction describing how to delete a file via the apply_patch tool. - - `execution: optional "server" or "client"` + - `path: string` - Whether tool search was executed by the server or by the client. + Path of the file to delete. - - `"server"` + - `type: "delete_file"` - - `"client"` + Delete the specified file. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `update_file: object { diff, path, type }` - The status of the tool search call. + Instruction describing how to update a file via the apply_patch tool. - - `"in_progress"` + - `diff: string` - - `"completed"` + Diff to apply. - - `"incomplete"` + - `path: string` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + Path of the file to update. - - `tools: array of BetaTool` + - `type: "update_file"` - The loaded tool definitions returned by the tool search output. + Update an existing file with the provided diff. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `status: "in_progress" or "completed"` - 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). + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `name: string` + - `"in_progress"` - The name of the function to call. + - `"completed"` - - `parameters: map[unknown]` + - `type: "apply_patch_call"` - A JSON schema object describing the parameters of the function. + The type of the item. Always `apply_patch_call`. - - `strict: boolean` + - `agent: optional object { agent_name }` - Whether strict parameter validation is enforced for this function tool. + The agent that produced this item. - - `type: "function"` + - `agent_name: string` - The type of the function tool. Always `function`. + The canonical name of the agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `caller: optional object { type } or object { caller_id, type }` - The tool invocation context(s). + The execution context that produced this tool call. - - `"direct"` + - `direct: object { type }` - - `"programmatic"` + - `program: object { caller_id, type }` - - `defer_loading: optional boolean` + - `caller_id: string` - Whether this function is deferred and loaded via tool search. + The call ID of the program item that produced this tool call. - - `description: optional string` + - `type: "program"` - A description of the function. Used by the model to determine whether or not to call the function. + - `created_by: optional string` - - `output_schema: optional map[unknown]` + The ID of the entity that created this tool call. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The output emitted by an apply patch tool call. - 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). + - `id: string` - - `type: "file_search"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The type of the file search tool. Always `file_search`. + - `call_id: string` - - `vector_store_ids: array of string` + The unique ID of the apply patch tool call generated by the model. - The IDs of the vector stores to search. + - `status: "completed" or "failed"` - - `filters: optional object { key, type, value } or object { filters, type }` + The status of the apply patch tool call output. One of `completed` or `failed`. - A filter to apply. + - `"completed"` - - `Comparison Filter: object { key, type, value }` + - `"failed"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: "apply_patch_call_output"` - - `key: string` + The type of the item. Always `apply_patch_call_output`. - The key to compare against the value. + - `agent: optional object { agent_name }` - - `type: "eq" or "ne" or "gt" or 5 more` + The agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent_name: string` - - `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 + The canonical name of the agent that produced this item. - - `"eq"` + - `caller: optional object { type } or object { caller_id, type }` - - `"ne"` + The execution context that produced this tool call. - - `"gt"` + - `direct: object { type }` - - `"gte"` + - `program: object { caller_id, type }` - - `"lt"` + - `caller_id: string` - - `"lte"` + The call ID of the program item that produced this tool call. - - `"in"` + - `type: "program"` - - `"nin"` + - `created_by: optional string` - - `value: string or number or boolean or array of unknown` + The ID of the entity that created this tool call output. - The value to compare against the attribute key; supports string, number, or boolean types. + - `output: optional string` - - `union_member_0: string` + Optional textual output returned by the apply patch tool. - - `union_member_1: number` + - `mcp_call: object { id, arguments, name, 7 more }` - - `union_member_2: boolean` + An invocation of a tool on an MCP server. - - `union_member_3: array of unknown` + - `id: string` - - `Compound Filter: object { filters, type }` + The unique ID of the tool call. - Combine multiple filters using `and` or `or`. + - `arguments: string` - - `filters: array of object { key, type, value } or unknown` + A JSON string of the arguments passed to the tool. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `name: string` - - `Comparison Filter: object { key, type, value }` + The name of the tool that was run. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `server_label: string` - - `key: string` + The label of the MCP server running the tool. - The key to compare against the value. + - `type: "mcp_call"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the item. Always `mcp_call`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent: optional object { agent_name }` - - `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 + The agent that produced this item. - - `"eq"` + - `agent_name: string` - - `"ne"` + The canonical name of the agent that produced this item. - - `"gt"` + - `approval_request_id: optional string` - - `"gte"` + 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. - - `"lt"` + - `error: optional string` - - `"lte"` + The error from the tool call, if any. - - `"in"` + - `output: optional string` - - `"nin"` + The output from the tool call. - - `value: string or number or boolean or array of unknown` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The value to compare against the attribute key; supports string, number, or boolean types. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `union_member_0: string` + - `"in_progress"` - - `union_member_1: number` + - `"completed"` - - `union_member_2: boolean` + - `"incomplete"` - - `union_member_3: array of unknown` + - `"calling"` - - `union_member_1: unknown` + - `"failed"` - - `type: "and" or "or"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - Type of operation: `and` or `or`. + A list of tools available on an MCP server. - - `"and"` + - `id: string` - - `"or"` + The unique ID of the list. - - `max_num_results: optional number` + - `server_label: string` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The label of the MCP server. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `tools: array of object { input_schema, name, annotations, description }` - Ranking options for search. + The tools available on the server. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `input_schema: unknown` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The JSON schema describing the tool's input. - - `embedding_weight: number` + - `name: string` - The weight of the embedding in the reciprocal ranking fusion. + The name of the tool. - - `text_weight: number` + - `annotations: optional unknown` - The weight of the text in the reciprocal ranking fusion. + Additional annotations about the tool. - - `ranker: optional "auto" or "default-2024-11-15"` + - `description: optional string` - The ranker to use for the file search. + The description of the tool. - - `"auto"` + - `type: "mcp_list_tools"` - - `"default-2024-11-15"` + The type of the item. Always `mcp_list_tools`. - - `score_threshold: optional number` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - - `beta_computer_tool: object { type }` + - `agent_name: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The canonical name of the agent that produced this item. - - `type: "computer"` + - `error: optional string` - The type of the computer tool. Always `computer`. + Error message if the server could not list tools. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A request for human approval of a tool invocation. - - `display_height: number` + - `id: string` - The height of the computer display. + The unique ID of the approval request. - - `display_width: number` + - `arguments: string` - The width of the computer display. + A JSON string of arguments for the tool. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `name: string` - The type of computer environment to control. + The name of the tool to run. - - `"windows"` + - `server_label: string` - - `"mac"` + The label of the MCP server making the request. - - `"linux"` + - `type: "mcp_approval_request"` - - `"ubuntu"` + The type of the item. Always `mcp_approval_request`. - - `"browser"` + - `agent: optional object { agent_name }` - - `type: "computer_use_preview"` + The agent that produced this item. - The type of the computer use tool. Always `computer_use_preview`. + - `agent_name: string` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The canonical name of the agent that produced this item. - 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_approval_response: object { id, approval_request_id, approve, 3 more }` - - `type: "web_search" or "web_search_2025_08_26"` + A response to an MCP approval request. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `id: string` - - `"web_search"` + The unique ID of the approval response - - `"web_search_2025_08_26"` + - `approval_request_id: string` - - `filters: optional object { allowed_domains }` + The ID of the approval request being answered. - Filters for the search. + - `approve: boolean` - - `allowed_domains: optional array of string` + Whether the request was approved. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `type: "mcp_approval_response"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The type of the item. Always `mcp_approval_response`. - - `search_context_size: optional "low" or "medium" or "high"` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `reason: optional string` - - `user_location: optional object { city, country, region, 2 more }` + Optional reason for the decision. - The approximate location of the user. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `city: optional string` + A call to a custom tool created by the model. - Free text input for the city of the user, e.g. `San Francisco`. + - `call_id: string` - - `country: optional string` + An identifier used to map this custom tool call to a tool call output. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `input: string` - - `region: optional string` + The input for the custom tool call generated by the model. - Free text input for the region of the user, e.g. `California`. + - `name: string` - - `timezone: optional string` + The name of the custom tool being called. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "custom_tool_call"` - - `type: optional "approximate"` + The type of the custom tool call. Always `custom_tool_call`. - The type of location approximation. Always `approximate`. + - `id: optional string` - - `"approximate"` + The unique ID of the custom tool call in the OpenAI platform. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `agent: optional object { agent_name }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The agent that produced this item. - - `server_label: string` + - `caller: optional object { type } or object { caller_id, type }` - A label for this MCP server, used to identify it in tool calls. + The execution context that produced this tool call. - - `type: "mcp"` + - `namespace: optional string` - The type of the MCP tool. Always `mcp`. + The namespace of the custom tool being called. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - The tool invocation context(s). + The output of a custom tool call from your code, being sent back to the model. - - `"direct"` + - `id: string` - - `"programmatic"` + The unique ID of the custom tool call output item. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `status: "in_progress" or "completed" or "incomplete"` - List of allowed tool names or a filter object. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `MCP allowed tools: array of string` + - `"in_progress"` - A string array of allowed tool names + - `"completed"` - - `MCP tool filter: object { read_only, tool_names }` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `created_by: optional string` - - `read_only: optional boolean` + The identifier of the actor that created the item. - 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. + - `parallel_tool_calls: boolean` - - `tool_names: optional array of string` + Whether to allow the model to run tool calls in parallel. - List of allowed tool names. + - `temperature: number` - - `authorization: optional string` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - 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. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - 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). + - `beta_tool_choice_options: "none" or "auto" or "required"` - Currently supported `connector_id` values are: + Controls which (if any) tool is called by the model. - - 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` + `none` means the model will not call any tool and instead generates a message. - - `"connector_dropbox"` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `"connector_gmail"` + `required` means the model must call one or more tools. - - `"connector_googlecalendar"` + - `"none"` - - `"connector_googledrive"` + - `"auto"` - - `"connector_microsoftteams"` + - `"required"` - - `"connector_outlookcalendar"` + - `beta_tool_choice_allowed: object { mode, tools, type }` - - `"connector_outlookemail"` + Constrains the tools available to the model to a pre-defined set. - - `"connector_sharepoint"` + - `mode: "auto" or "required"` - - `defer_loading: optional boolean` + Constrains the tools available to the model to a pre-defined set. - Whether this MCP tool is deferred and discovered via tool search. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `headers: optional map[string]` + `required` requires the model to call one or more of the allowed tools. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"auto"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `"required"` - Specify which of the MCP server's tools require approval. + - `tools: array of map[unknown]` - - `MCP tool approval filter: object { always, never }` + A list of tool definitions that the model should be allowed to call. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + For the Responses API, the list of tool definitions might look like: - - `always: optional object { read_only, tool_names }` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - A filter object to specify which tools are allowed. + - `type: "allowed_tools"` - - `read_only: optional boolean` + Allowed tool configuration type. Always `allowed_tools`. - 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. + - `beta_tool_choice_types: object { type }` - - `tool_names: optional array of string` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - List of allowed tool names. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `never: optional object { read_only, tool_names }` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - A filter object to specify which tools are allowed. + Allowed values are: - - `read_only: optional boolean` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - 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. + - `"file_search"` - - `tool_names: optional array of string` + - `"web_search_preview"` - List of allowed tool names. + - `"computer"` - - `MCP tool approval setting: "always" or "never"` + - `"computer_use_preview"` - 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. + - `"computer_use"` - - `"always"` + - `"web_search_preview_2025_03_11"` - - `"never"` + - `"image_generation"` - - `server_description: optional string` + - `"code_interpreter"` - Optional description of the MCP server, used to provide more context. + - `beta_tool_choice_function: object { name, type }` - - `server_url: optional string` + Use this option to force the model to call a specific function. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `name: string` - - `tunnel_id: optional string` + The name of the function to call. - 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. + - `type: "function"` - - `code_interpreter: object { container, type, allowed_callers }` + For function calling, the type is always `function`. - A tool that runs Python code to help generate a response to a prompt. + - `beta_tool_choice_mcp: object { server_label, type, name }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Use this option to force the model to call a specific tool on a remote MCP server. - 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. + - `server_label: string` - - `union_member_0: string` + The label of the MCP server to use. - The container ID. + - `type: "mcp"` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + For MCP tools, the type is always `mcp`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `name: optional string` - - `type: "auto"` + The name of the tool to call on the server. - Always `auto`. + - `beta_tool_choice_custom: object { name, type }` - - `file_ids: optional array of string` + Use this option to force the model to call a specific custom tool. - An optional list of uploaded files to make available to your code. + - `name: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The name of the custom tool to call. - The memory limit for the code interpreter container. + - `type: "custom"` - - `"1g"` + For custom tool calling, the type is always `custom`. - - `"4g"` + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - - `"16g"` + - `beta_tool_choice_apply_patch: object { type }` - - `"64g"` + Forces the model to call the apply_patch tool when executing a tool call. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `type: "apply_patch"` - Network access policy for the container. + The tool to call. Always `apply_patch`. - - `beta_container_network_policy_disabled: object { type }` + - `beta_tool_choice_shell: object { type }` - - `type: "disabled"` + Forces the model to call the shell tool when a tool call is required. - Disable outbound network access. Always `disabled`. + - `type: "shell"` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The tool to call. Always `shell`. - - `allowed_domains: array of string` + - `tools: array of BetaTool` - A list of allowed domains when type is `allowlist`. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `type: "allowlist"` + We support the following categories of tools: - Allow outbound network access only to specified domains. Always `allowlist`. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - Optional domain-scoped secrets for allowlisted domains. + 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). - - `domain: string` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The domain associated with the secret. + 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). - - `name: string` + - `beta_computer_tool: object { type }` - The name of the secret to inject for the domain. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `value: string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The secret value to inject for the domain. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "code_interpreter"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the code interpreter tool. Always `code_interpreter`. + 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). - - `allowed_callers: optional array of "direct" or "programmatic"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The tool invocation context(s). + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"direct"` + - `code_interpreter: object { container, type, allowed_callers }` - - `"programmatic"` + A tool that runs Python code to help generate a response to a prompt. - `programmatic_tool_calling: object { type }` @@ -44592,992 +54941,1085 @@ openai beta:responses compact \ A tool that generates images using the GPT image models. - - `type: "image_generation"` + - `local_shell: object { type }` - The type of the image generation tool. Always `image_generation`. + A tool that allows the model to execute shell commands in a local environment. - - `action: optional "generate" or "edit" or "auto"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - Whether to generate a new image or edit an existing image. Default: `auto`. + A tool that allows the model to execute shell commands. - - `"generate"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"edit"` + 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) - - `"auto"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `background: optional "transparent" or "opaque" or "auto"` + Groups function/custom tools under a shared namespace. - 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. + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `top_p: number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. - `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. + - `background: optional boolean` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `"transparent"` + - `completed_at: optional number` - - `"opaque"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"auto"` + - `conversation: optional object { id }` - - `input_fidelity: optional "high" or "low"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - 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`. + - `id: string` - - `"high"` + The unique ID of the conversation that this response was associated with. - - `"low"` + - `max_output_tokens: optional number` - - `input_image_mask: optional object { file_id, image_url }` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `max_tool_calls: optional number` - - `file_id: optional string` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - File ID for the mask image. + - `moderation: optional object { input, output }` - - `image_url: optional string` + Moderation results for the response input and output, if moderated completions were requested. - Base64-encoded mask image. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + Moderation for the response input. - The image generation model to use. Default: `gpt-image-1`. + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `"gpt-image-1"` + A moderation result produced for the response input or output. - - `"gpt-image-1-mini"` + - `categories: map[boolean]` - - `"gpt-image-2"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"gpt-image-2-2026-04-21"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"gpt-image-1.5"` + Which modalities of input are reflected by the score for each category. - - `"chatgpt-image-latest"` + - `"text"` - - `moderation: optional "auto" or "low"` + - `"image"` - Moderation level for the generated image. Default: `auto`. + - `category_scores: map[number]` - - `"auto"` + A dictionary of moderation categories to scores. - - `"low"` + - `flagged: boolean` - - `output_compression: optional number` + A boolean indicating whether the content was flagged by any category. - Compression level for the output image. Default: 100. + - `model: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The moderation model that produced this result. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `type: "moderation_result"` - - `"png"` + The object type, which was always `moderation_result` for successful moderation results. - - `"webp"` + - `error: object { code, message, type }` - - `"jpeg"` + An error produced while attempting moderation for the response input or output. - - `partial_images: optional number` + - `code: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The error code. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `message: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The error message. - - `"low"` + - `type: "error"` - - `"medium"` + The object type, which was always `error` for moderation failures. - - `"high"` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"auto"` + Moderation for the response output. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - 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`. + A moderation result produced for the response input or output. - - `"1024x1024"` + - `categories: map[boolean]` - - `"1024x1536"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"1536x1024"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"auto"` + Which modalities of input are reflected by the score for each category. - - `local_shell: object { type }` + - `"text"` - A tool that allows the model to execute shell commands in a local environment. + - `"image"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `category_scores: map[number]` - A tool that allows the model to execute shell commands. + A dictionary of moderation categories to scores. - - `type: "shell"` + - `flagged: boolean` - The type of the shell tool. Always `shell`. + A boolean indicating whether the content was flagged by any category. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `model: string` - The tool invocation context(s). + The moderation model that produced this result. - - `"direct"` + - `type: "moderation_result"` - - `"programmatic"` + The object type, which was always `moderation_result` for successful moderation results. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `error: object { code, message, type }` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + An error produced while attempting moderation for the response input or output. - - `type: "container_auto"` + - `code: string` - Automatically creates a container for this request + The error code. - - `file_ids: optional array of string` + - `message: string` - An optional list of uploaded files to make available to your code. + The error message. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "error"` - The memory limit for the container. + The object type, which was always `error` for moderation failures. - - `"1g"` + - `previous_response_id: optional string` - - `"4g"` + 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`. - - `"16g"` + - `prompt: optional object { id, variables, version }` - - `"64g"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `id: string` - Network access policy for the container. + The unique identifier of the prompt template to use. - - `beta_container_network_policy_disabled: object { type }` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `union_member_0: string` - An optional list of skills referenced by id or inline data. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `beta_skill_reference: object { skill_id, type, version }` + A text input to the model. - - `skill_id: string` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The ID of the referenced skill. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `type: "skill_reference"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - References a skill created with the /v1/skills endpoint. + A file input to the model. - `version: optional string` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Optional version of the prompt template. - - `beta_inline_skill: object { description, name, source, type }` + - `prompt_cache_key: optional string` - - `description: string` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The description of the skill. + - `prompt_cache_options: optional object { mode, ttl }` - - `name: string` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The name of the skill. + - `mode: "implicit" or "explicit"` - - `source: object { data, media_type, type }` + Whether implicit prompt-cache breakpoints were enabled. - Inline skill payload + - `"implicit"` - - `data: string` + - `"explicit"` - Base64-encoded skill zip bundle. + - `ttl: "30m"` - - `media_type: "application/zip"` + The minimum lifetime applied to each cache breakpoint. - The media type of the inline skill payload. Must be `application/zip`. + - `"30m"` - - `type: "base64"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The type of the inline skill source. Must be `base64`. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `type: "inline"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - Defines an inline skill for this request. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `beta_local_environment: object { type, skills }` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `type: "local"` + - `"in_memory"` - Use a local computer environment. + - `"24h"` - - `skills: optional array of BetaLocalSkill` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - An optional list of skills. + **gpt-5 and o-series models only** - - `description: string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The description of the skill. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `name: string` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The name of the skill. + - `"auto"` - - `path: string` + - `"current_turn"` - The path to the directory containing the skill. + - `"all_turns"` - - `beta_container_reference: object { container_id, type }` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `container_id: string` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The ID of the referenced container. + - `"none"` - - `type: "container_reference"` + - `"minimal"` - References a container created with the /v1/containers endpoint + - `"low"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `"medium"` - 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) + - `"high"` - - `name: string` + - `"xhigh"` - The name of the custom tool, used to identify it in tool calls. + - `"max"` - - `type: "custom"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The type of the custom tool. Always `custom`. + **Deprecated:** use `summary` instead. - - `allowed_callers: optional array of "direct" or "programmatic"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The tool invocation context(s). + - `"auto"` - - `"direct"` + - `"concise"` - - `"programmatic"` + - `"detailed"` - - `defer_loading: optional boolean` + - `mode: optional string or "standard" or "pro"` - Whether this tool should be deferred and discovered via tool search. + Controls the reasoning execution mode for the request. - - `description: optional string` + When returned on a response, this is the effective execution mode. - Optional description of the custom tool, used to provide more context. + - `"standard"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"pro"` - The input format for the custom tool. Default is unconstrained text. + - `summary: optional "auto" or "concise" or "detailed"` - - `text: object { type }` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - Unconstrained free-form text. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `grammar: object { definition, syntax, type }` + - `"auto"` - A grammar defined by the user. + - `"concise"` - - `definition: string` + - `"detailed"` - The grammar definition. + - `safety_identifier: optional string` - - `syntax: "lark" or "regex"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The syntax of the grammar definition. One of `lark` or `regex`. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `"lark"` + Specifies the processing type used for serving the request. - - `"regex"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `type: "grammar"` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - Grammar format. Always `grammar`. + - `"auto"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `"default"` - Groups function/custom tools under a shared namespace. + - `"flex"` - - `description: string` + - `"scale"` - A description of the namespace shown to the model. + - `"priority"` - - `name: string` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - The namespace name used in tool calls (for example, `crm`). + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `"completed"` - The function/custom tools available inside this namespace. + - `"failed"` - - `function: object { name, type, allowed_callers, 5 more }` + - `"in_progress"` - - `name: string` + - `"cancelled"` - - `type: "function"` + - `"queued"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"incomplete"` - The tool invocation context(s). + - `text: optional object { format, verbosity }` - - `"direct"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"programmatic"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `defer_loading: optional boolean` + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - Whether this function should be deferred and discovered via tool search. + An object specifying the format that the model must output. - - `description: optional string` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `output_schema: optional map[unknown]` + The default format is `{ "type": "text" }` with no additional options. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + **Not recommended for gpt-4o and newer models:** - - `parameters: optional unknown` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `strict: optional boolean` + - `text: object { type }` - 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. + Default response format. Used to generate text responses. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - 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) + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `name: string` - The name of the custom tool, used to identify it in tool calls. - - - `type: "custom"` - - The type of the custom tool. Always `custom`. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `schema: map[unknown]` - The tool invocation context(s). + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `defer_loading: optional boolean` + - `type: "json_schema"` - Whether this tool should be deferred and discovered via tool search. + The type of response format being defined. Always `json_schema`. - `description: optional string` - Optional description of the custom tool, used to provide more context. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `format: optional object { type } or object { definition, syntax, type }` + - `strict: optional boolean` - The input format for the custom tool. Default is unconstrained text. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `type: "namespace"` + - `json_object: object { type }` - The type of the tool. Always `namespace`. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `verbosity: optional "low" or "medium" or "high"` - Hosted or BYOT tool search configuration for deferred tools. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `type: "tool_search"` + - `"low"` - The type of the tool. Always `tool_search`. + - `"medium"` - - `description: optional string` + - `"high"` - Description shown to the model for a client-executed tool search tool. + - `top_logprobs: optional number` - - `execution: optional "server" or "client"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - Whether tool search is executed by the server or by the client. + - `truncation: optional "auto" or "disabled"` - - `"server"` + The truncation strategy to use for the model response. - - `"client"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `parameters: optional unknown` + - `"auto"` - Parameter schema for a client-executed tool search tool. + - `"disabled"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - 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). + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `input_tokens: number` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The number of input tokens. - - `"web_search_preview"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `"web_search_preview_2025_03_11"` + A detailed breakdown of the input tokens. - - `search_content_types: optional array of "text" or "image"` + - `cache_write_tokens: number` - - `"text"` + The number of input tokens that were written to the cache. - - `"image"` + - `cached_tokens: number` - - `search_context_size: optional "low" or "medium" or "high"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - 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. + - `output_tokens: number` - - `"low"` + The number of output tokens. - - `"medium"` + - `output_tokens_details: object { reasoning_tokens }` - - `"high"` + A detailed breakdown of the output tokens. - - `user_location: optional object { type, city, country, 2 more }` + - `reasoning_tokens: number` - The user's location. + The number of reasoning tokens. - - `type: "approximate"` + - `total_tokens: number` - The type of location approximation. Always `approximate`. + The total number of tokens used. - - `city: optional string` + - `user: optional string` - Free text input for the city of the user, e.g. `San Francisco`. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `country: optional string` + - `sequence_number: number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The sequence number of this event. - - `region: optional string` + - `type: "response.failed"` - Free text input for the region of the user, e.g. `California`. + The type of the event. Always `response.failed`. - - `timezone: optional string` + - `agent: optional object { agent_name }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The agent that owns this multi-agent streaming event. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `agent_name: string` - Allows the assistant to create, delete, or update files using unified diffs. + The canonical name of the agent that produced this item. - - `type: "apply_patch"` +### Beta Response File Search Call Completed Event - The type of the tool. Always `apply_patch`. +- `beta_response_file_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Emitted when a file search call is completed (results found). - The tool invocation context(s). + - `item_id: string` - - `"direct"` + The ID of the output item that the file search call is initiated. - - `"programmatic"` + - `output_index: number` - - `type: "tool_search_output"` + The index of the output item that the file search call is initiated. - The item type. Always `tool_search_output`. + - `sequence_number: number` - - `id: optional string` + The sequence number of this event. - The unique ID of this tool search output. + - `type: "response.file_search_call.completed"` + + The type of the event. Always `response.file_search_call.completed`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `call_id: optional string` +### Beta Response File Search Call In Progress Event - The unique ID of the tool search call generated by the model. +- `beta_response_file_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `execution: optional "server" or "client"` + Emitted when a file search call is initiated. - Whether tool search was executed by the server or by the client. + - `item_id: string` - - `"server"` + The ID of the output item that the file search call is initiated. - - `"client"` + - `output_index: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The index of the output item that the file search call is initiated. - The status of the tool search output. + - `sequence_number: number` - - `"in_progress"` + The sequence number of this event. - - `"completed"` + - `type: "response.file_search_call.in_progress"` - - `"incomplete"` + The type of the event. Always `response.file_search_call.in_progress`. - - `additional_tools: object { role, tools, type, 2 more }` + - `agent: optional object { agent_name }` - - `role: "developer"` + The agent that owns this multi-agent streaming event. - The role that provided the additional tools. Only `developer` is supported. + - `agent_name: string` - - `tools: array of BetaTool` + The canonical name of the agent that produced this item. - A list of additional tools made available at this item. +### Beta Response File Search Call Searching Event - - `beta_function_tool: object { name, parameters, strict, 5 more }` +- `beta_response_file_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` - 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). + Emitted when a file search is currently searching. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `item_id: string` - 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). + The ID of the output item that the file search call is initiated. - - `beta_computer_tool: object { type }` + - `output_index: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the output item that the file search call is searching. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `sequence_number: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The sequence number of this event. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `type: "response.file_search_call.searching"` - 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). + The type of the event. Always `response.file_search_call.searching`. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `agent: optional object { agent_name }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The agent that owns this multi-agent streaming event. - - `code_interpreter: object { container, type, allowed_callers }` + - `agent_name: string` - A tool that runs Python code to help generate a response to a prompt. + The canonical name of the agent that produced this item. - - `programmatic_tool_calling: object { type }` +### Beta Response File Search Tool Call - - `image_generation: object { type, action, background, 9 more }` +- `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - A tool that generates images using the GPT image models. + 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. - - `local_shell: object { type }` + - `id: string` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the file search tool call. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `queries: array of string` - A tool that allows the model to execute shell commands. + The queries used to search for files. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `status: "in_progress" or "searching" or "completed" or 2 more` - 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) + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `beta_namespace_tool: object { description, name, tools, type }` + - `"in_progress"` - Groups function/custom tools under a shared namespace. + - `"searching"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `"completed"` - Hosted or BYOT tool search configuration for deferred tools. + - `"incomplete"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `"failed"` - 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: "file_search_call"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The type of the file search tool call. Always `file_search_call`. - Allows the assistant to create, delete, or update files using unified diffs. + - `agent: optional object { agent_name }` - - `type: "additional_tools"` + The agent that produced this item. - The item type. Always `additional_tools`. + - `agent_name: string` - - `id: optional string` + The canonical name of the agent that produced this item. - The unique ID of this additional tools item. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `agent: optional object { agent_name }` + The results of the file search tool call. - The agent that produced this item. + - `attributes: optional map[string or number or boolean]` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `union_member_0: string` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `union_member_1: number` - 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). + - `union_member_2: boolean` - - `id: string` + - `file_id: optional string` - The unique identifier of the reasoning content. + The unique ID of the file. - - `summary: array of object { text, type }` + - `filename: optional string` - Reasoning summary content. + The name of the file. - - `text: string` + - `score: optional number` - A summary of the reasoning output from the model so far. + The relevance score of the file - a value between 0 and 1. - - `type: "summary_text"` + - `text: optional string` - The type of the object. Always `summary_text`. + The text that was retrieved from the file. - - `type: "reasoning"` +### Beta Response Format Text Config - The type of the object. Always `reasoning`. +- `beta_response_format_text_config: object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - `agent: optional object { agent_name }` + An object specifying the format that the model must output. - The agent that produced this item. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `agent_name: string` + The default format is `{ "type": "text" }` with no additional options. - The canonical name of the agent that produced this item. + **Not recommended for gpt-4o and newer models:** - - `content: optional array of object { text, type }` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - Reasoning text content. + - `text: object { type }` - - `text: string` + Default response format. Used to generate text responses. - The reasoning text from the model. + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - - `type: "reasoning_text"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The type of the reasoning text. Always `reasoning_text`. + - `name: string` - - `encrypted_content: optional string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `schema: map[unknown]` - - `status: optional "in_progress" or "completed" or "incomplete"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "json_schema"` - - `"in_progress"` + The type of response format being defined. Always `json_schema`. - - `"completed"` + - `description: optional string` - - `"incomplete"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `strict: optional boolean` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `encrypted_content: string` + - `json_object: object { type }` - The encrypted content of the compaction summary. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `type: "compaction"` +### Beta Response Format Text JSON Schema Config - The type of the item. Always `compaction`. +- `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - - `id: optional string` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The ID of the compaction item. + - `name: string` - - `agent: optional object { agent_name }` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The agent that produced this item. + - `schema: map[unknown]` - - `agent_name: string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The canonical name of the agent that produced this item. + - `type: "json_schema"` - - `image_generation_call: object { id, result, status, 2 more }` + The type of response format being defined. Always `json_schema`. - An image generation request made by the model. + - `description: optional string` - - `id: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The unique ID of the image generation call. + - `strict: optional boolean` - - `result: string` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The generated image encoded in base64. +### Beta Response Function Call Arguments Delta Event - - `status: "in_progress" or "completed" or "generating" or "failed"` +- `beta_response_function_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` - The status of the image generation call. + Emitted when there is a partial function-call arguments delta. - - `"in_progress"` + - `delta: string` - - `"completed"` + The function-call arguments delta that is added. - - `"generating"` + - `item_id: string` - - `"failed"` + The ID of the output item that the function-call arguments delta is added to. - - `type: "image_generation_call"` + - `output_index: number` - The type of the image generation call. Always `image_generation_call`. + The index of the output item that the function-call arguments delta is added to. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.function_call_arguments.delta"` + + The type of the event. Always `response.function_call_arguments.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - A tool call to run code. +### Beta Response Function Call Arguments Done Event - - `id: string` +- `beta_response_function_call_arguments_done_event: object { arguments, item_id, name, 4 more }` - The unique ID of the code interpreter tool call. + Emitted when function-call arguments are finalized. - - `code: string` + - `arguments: string` - The code to run, or null if not available. + The function-call arguments. - - `container_id: string` + - `item_id: string` - The ID of the container used to run the code. + The ID of the item. - - `outputs: array of object { logs, type } or object { type, url }` + - `name: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The name of the function that was called. - - `logs: object { logs, type }` + - `output_index: number` - The logs output from the code interpreter. + The index of the output item. - - `logs: string` + - `sequence_number: number` - The logs output from the code interpreter. + The sequence number of this event. - - `type: "logs"` + - `type: "response.function_call_arguments.done"` - The type of the output. Always `logs`. + - `agent: optional object { agent_name }` - - `image: object { type, url }` + The agent that owns this multi-agent streaming event. - The image output from the code interpreter. + - `agent_name: string` - - `type: "image"` + The canonical name of the agent that produced this item. - The type of the output. Always `image`. +### Beta Response Function Call Output Item - - `url: string` +- `beta_response_function_call_output_item: BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The URL of the image output from the code interpreter. + A piece of message content, such as text, an image, or a file. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + A text input to the model. - - `"in_progress"` + - `text: string` - - `"completed"` + The text input to the model. - - `"incomplete"` + - `type: "input_text"` - - `"interpreting"` + The type of the input item. Always `input_text`. - - `"failed"` + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "code_interpreter_call"` + 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. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `mode: "explicit"` - - `agent: optional object { agent_name }` + The breakpoint mode. Always `explicit`. - The agent that produced this item. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `agent_name: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The canonical name of the agent that produced this item. + - `type: "input_image"` - - `local_shell_call: object { id, action, call_id, 3 more }` + The type of the input item. Always `input_image`. - A tool call to run a command on the local shell. + - `detail: optional "low" or "high" or "auto" or "original"` - - `id: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The unique ID of the local shell call. + - `"low"` - - `action: object { command, env, type, 3 more }` + - `"high"` - Execute a shell command on the server. + - `"auto"` - - `command: array of string` + - `"original"` - The command to run. + - `file_id: optional string` - - `env: map[string]` + The ID of the file to be sent to the model. - Environment variables to set for the command. + - `image_url: optional string` - - `type: "exec"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The type of the local shell action. Always `exec`. + - `prompt_cache_breakpoint: optional object { mode }` - - `timeout_ms: optional number` + 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. - Optional timeout in milliseconds for the command. + - `mode: "explicit"` - - `user: optional string` + The breakpoint mode. Always `explicit`. - Optional user to run the command as. + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `working_directory: optional string` + A file input to the model. - Optional working directory to run the command in. + - `type: "input_file"` - - `call_id: string` + The type of the input item. Always `input_file`. - The unique ID of the local shell tool call generated by the model. + - `detail: optional "auto" or "low" or "high"` - - `status: "in_progress" or "completed" or "incomplete"` + 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`. - The status of the local shell call. + - `"auto"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `file_data: optional string` - - `type: "local_shell_call"` + The base64-encoded data of the file to be sent to the model. - The type of the local shell call. Always `local_shell_call`. + - `file_id: optional string` - - `agent: optional object { agent_name }` + The ID of the file to be sent to the model. - The agent that produced this item. + - `file_url: optional string` - - `agent_name: string` + The URL of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `filename: optional string` - - `local_shell_call_output: object { id, output, type, 2 more }` + The name of the file to be sent to the model. - The output of a local shell tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `id: string` + 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. - The unique ID of the local shell tool call generated by the model. + - `mode: "explicit"` - - `output: string` + The breakpoint mode. Always `explicit`. - A JSON string of the output of the local shell tool call. +### Beta Response Function Call Output Item List - - `type: "local_shell_call_output"` +- `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - The type of the local shell tool call output. Always `local_shell_call_output`. + An array of content outputs (text, image, file) for the function tool call. - - `agent: optional object { agent_name }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - The agent that produced this item. + A text input to the model. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + The text input to the model. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "input_text"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The type of the input item. Always `input_text`. - - `"in_progress"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"completed"` + 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. - - `"incomplete"` + - `mode: "explicit"` - - `shell_call: object { action, call_id, type, 5 more }` + The breakpoint mode. Always `explicit`. - A tool representing a request to execute one or more shell commands. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `action: object { commands, max_output_length, timeout_ms }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The shell commands and limits that describe how to run the tool call. + - `type: "input_image"` - - `commands: array of string` + The type of the input item. Always `input_image`. - Ordered shell commands for the execution environment to run. + - `detail: optional "low" or "high" or "auto" or "original"` - - `max_output_length: optional number` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"low"` - - `timeout_ms: optional number` + - `"high"` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"auto"` - - `call_id: string` + - `"original"` - The unique ID of the shell tool call generated by the model. + - `file_id: optional string` - - `type: "shell_call"` + The ID of the file to be sent to the model. - The type of the item. Always `shell_call`. + - `image_url: optional string` - - `id: optional string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `prompt_cache_breakpoint: optional object { mode }` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + - `mode: "explicit"` - - `agent_name: string` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `caller: optional object { type } or object { caller_id, type }` + A file input to the model. - The execution context that produced this tool call. + - `type: "input_file"` - - `direct: object { type }` + The type of the input item. Always `input_file`. - - `program: object { caller_id, type }` + - `detail: optional "auto" or "low" or "high"` - - `caller_id: string` + 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`. - The call ID of the program item that produced this tool call. + - `"auto"` - - `type: "program"` + - `"low"` - The caller type. Always `program`. + - `"high"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `file_data: optional string` - The environment to execute the shell commands in. + The base64-encoded data of the file to be sent to the model. - - `beta_local_environment: object { type, skills }` + - `file_id: optional string` - - `beta_container_reference: object { container_id, type }` + The ID of the file to be sent to the model. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `file_url: optional string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The URL of the file to be sent to the model. - - `"in_progress"` + - `filename: optional string` - - `"completed"` + The name of the file to be sent to the model. - - `"incomplete"` + - `prompt_cache_breakpoint: optional object { mode }` - - `shell_call_output: object { call_id, output, type, 5 more }` + 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. - The streamed output items emitted by a shell tool call. + - `mode: "explicit"` - - `call_id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the shell tool call generated by the model. +### Beta Response Function Shell Call Output Content - - `output: array of BetaResponseFunctionShellCallOutputContent` +- `beta_response_function_shell_call_output_content: object { outcome, stderr, stdout }` - Captured chunks of stdout and stderr output, along with their associated outcomes. + Captured stdout and stderr for a portion of a shell tool call output. - `outcome: object { type } or object { exit_code, type }` @@ -45607,123 +56049,69 @@ openai beta:responses compact \ Captured stdout output for the shell call. - - `type: "shell_call_output"` - - The type of the item. Always `shell_call_output`. - - - `id: optional string` - - The unique ID of the shell tool call output. Populated when this item is returned via API. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. +### Beta Response Function Shell Tool Call - - `type: "program"` +- `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - The caller type. Always `program`. + A tool call that executes one or more shell commands in a managed environment. - - `max_output_length: optional number` + - `id: string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `action: object { commands, max_output_length, timeout_ms }` - The status of the shell call output. + The shell commands and limits that describe how to run the tool call. - - `"in_progress"` + - `commands: array of string` - - `"completed"` + - `max_output_length: number` - - `"incomplete"` + Optional maximum number of characters to return from each command. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `timeout_ms: number` - A tool call representing a request to create, delete, or update files using diff patches. + Optional timeout in milliseconds for the commands. - `call_id: string` - The unique ID of the apply patch tool call generated by the model. - - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - The specific create, delete, or update instruction for the apply_patch tool call. - - - `create_file: object { diff, path, type }` - - Instruction for creating a new file via the apply_patch tool. - - - `diff: string` - - Unified diff content to apply when creating the file. - - - `path: string` - - Path of the file to create relative to the workspace root. - - - `type: "create_file"` - - The operation type. Always `create_file`. - - - `delete_file: object { path, type }` - - Instruction for deleting an existing file via the apply_patch tool. - - - `path: string` + The unique ID of the shell tool call generated by the model. - Path of the file to delete relative to the workspace root. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `type: "delete_file"` + Represents the use of a local environment to perform shell actions. - The operation type. Always `delete_file`. + - `beta_response_local_environment: object { type }` - - `update_file: object { diff, path, type }` + Represents the use of a local environment to perform shell actions. - Instruction for updating an existing file via the apply_patch tool. + - `type: "local"` - - `diff: string` + The environment type. Always `local`. - Unified diff content to apply to the existing file. + - `beta_response_container_reference: object { container_id, type }` - - `path: string` + Represents a container created with /v1/containers. - Path of the file to update relative to the workspace root. + - `container_id: string` - - `type: "update_file"` + - `type: "container_reference"` - The operation type. Always `update_file`. + The environment type. Always `container_reference`. - - `status: "in_progress" or "completed"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - `"completed"` - - `type: "apply_patch_call"` - - The type of the item. Always `apply_patch_call`. + - `"incomplete"` - - `id: optional string` + - `type: "shell_call"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of the item. Always `shell_call`. - `agent: optional object { agent_name }` @@ -45747,95 +56135,77 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `apply_patch_call_output: object { call_id, status, type, 4 more }` - - The streamed output emitted by an apply patch tool call. - - - `call_id: string` - - The unique ID of the apply patch tool call generated by the model. - - - `status: "completed" or "failed"` - - The status of the apply patch tool call output. One of `completed` or `failed`. - - - `"completed"` - - - `"failed"` - - - `type: "apply_patch_call_output"` + - `created_by: optional string` - The type of the item. Always `apply_patch_call_output`. + The ID of the entity that created this tool call. - - `id: optional string` +### Beta Response Function Shell Tool Call Output - The unique ID of the apply patch tool call output. Populated when this item is returned via API. +- `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `agent: optional object { agent_name }` + The output of a shell tool call that was emitted. - The agent that produced this item. + - `id: string` - - `agent_name: string` + The unique ID of the shell call output. Populated when this item is returned via API. - The canonical name of the agent that produced this item. + - `call_id: string` - - `caller: optional object { type } or object { caller_id, type }` + The unique ID of the shell tool call generated by the model. - The execution context that produced this tool call. + - `max_output_length: number` - - `direct: object { type }` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `program: object { caller_id, type }` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `caller_id: string` + An array of shell call output contents - The call ID of the program item that produced this tool call. + - `outcome: object { type } or object { exit_code, type }` - - `type: "program"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The caller type. Always `program`. + - `timeout: object { type }` - - `output: optional string` + Indicates that the shell call exceeded its configured time limit. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `exit: object { exit_code, type }` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + Indicates that the shell commands finished and returned an exit code. - A list of tools available on an MCP server. + - `exit_code: number` - - `id: string` + Exit code from the shell process. - The unique ID of the list. + - `type: "exit"` - - `server_label: string` + The outcome type. Always `exit`. - The label of the MCP server. + - `stderr: string` - - `tools: array of object { input_schema, name, annotations, description }` + The standard error output that was captured. - The tools available on the server. + - `stdout: string` - - `input_schema: unknown` + The standard output that was captured. - The JSON schema describing the tool's input. + - `created_by: optional string` - - `name: string` + The identifier of the actor that created the item. - The name of the tool. + - `status: "in_progress" or "completed" or "incomplete"` - - `annotations: optional unknown` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - Additional annotations about the tool. + - `"in_progress"` - - `description: optional string` + - `"completed"` - The description of the tool. + - `"incomplete"` - - `type: "mcp_list_tools"` + - `type: "shell_call_output"` - The type of the item. Always `mcp_list_tools`. + The type of the shell call output. Always `shell_call_output`. - `agent: optional object { agent_name }` @@ -45845,61 +56215,50 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `error: optional string` - - Error message if the server could not list tools. - - - `mcp_approval_request: object { id, arguments, name, 3 more }` - - A request for human approval of a tool invocation. - - - `id: string` - - The unique ID of the approval request. - - - `arguments: string` + - `caller: optional object { type } or object { caller_id, type }` - A JSON string of arguments for the tool. + The execution context that produced this tool call. - - `name: string` + - `direct: object { type }` - The name of the tool to run. + - `program: object { caller_id, type }` - - `server_label: string` + - `caller_id: string` - The label of the MCP server making the request. + The call ID of the program item that produced this tool call. - - `type: "mcp_approval_request"` + - `type: "program"` - The type of the item. Always `mcp_approval_request`. + - `created_by: optional string` - - `agent: optional object { agent_name }` + The identifier of the actor that created the item. - The agent that produced this item. +### Beta Response Function Tool Call - - `agent_name: string` +- `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The canonical name of the agent that produced this item. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + - `arguments: string` - A response to an MCP approval request. + A JSON string of the arguments to pass to the function. - - `approval_request_id: string` + - `call_id: string` - The ID of the approval request being answered. + The unique ID of the function tool call generated by the model. - - `approve: boolean` + - `name: string` - Whether the request was approved. + The name of the function to run. - - `type: "mcp_approval_response"` + - `type: "function_call"` - The type of the item. Always `mcp_approval_response`. + The type of the function tool call. Always `function_call`. - `id: optional string` - The unique ID of the approval response + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -45909,58 +56268,50 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `reason: optional string` - - Optional reason for the decision. - - - `mcp_call: object { id, arguments, name, 7 more }` - - An invocation of a tool on an MCP server. - - - `id: string` - - The unique ID of the tool call. + - `caller: optional object { type } or object { caller_id, type }` - - `arguments: string` + The execution context that produced this tool call. - A JSON string of the arguments passed to the tool. + - `direct: object { type }` - - `name: string` + - `program: object { caller_id, type }` - The name of the tool that was run. + - `caller_id: string` - - `server_label: string` + The call ID of the program item that produced this tool call. - The label of the MCP server running the tool. + - `type: "program"` - - `type: "mcp_call"` + - `namespace: optional string` - The type of the item. Always `mcp_call`. + The namespace of the function to run. - - `agent: optional object { agent_name }` + - `status: optional "in_progress" or "completed" or "incomplete"` - The agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"completed"` - - `approval_request_id: optional string` + - `"incomplete"` - 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. +### Beta Response Function Tool Call Item - - `error: optional string` +- `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` - The error from the tool call, if any. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `output: optional string` + - `id: string` - The output from the tool call. + The unique ID of the function tool call. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -45968,30 +56319,34 @@ openai beta:responses compact \ - `"incomplete"` - - `"calling"` + - `created_by: optional string` - - `"failed"` + The identifier of the actor that created the item. - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` +### Beta Response Function Tool Call Output Item - The output of a custom tool call from your code, being sent back to the model. +- `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the function call tool output. - `call_id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the function tool call generated by the model. - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The output from the custom tool call generated by your code. + The output from the function call generated by your code. Can be a string or an list of output content. - `string output: string` - A string of the output of the custom tool call. + A string of the output of the function call. - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Text, image, or file output of the custom tool call. + Text, image, or file output of the function call. - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` @@ -46009,6 +56364,10 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -46017,6 +56376,14 @@ openai beta:responses compact \ The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + - `type: "input_image"` The type of the input item. Always `input_image`. @@ -46033,6 +56400,10 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. @@ -46045,6 +56416,12 @@ openai beta:responses compact \ The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"auto"` + + - `"low"` + + - `"high"` + - `file_data: optional string` The content of the file to be sent to the model. @@ -46065,61 +56442,24 @@ openai beta:responses compact \ 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. - - `type: "custom_tool_call_output"` - - The type of the custom tool call output. Always `custom_tool_call_output`. - - - `id: optional string` - - The unique ID of the custom tool call output in the OpenAI platform. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - The caller type. Always `program`. - - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - A call to a custom tool created by the model. - - - `call_id: string` - - An identifier used to map this custom tool call to a tool call output. + - `mode: "explicit"` - - `input: string` + The breakpoint mode. Always `explicit`. - The input for the custom tool call generated by the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The name of the custom tool being called. + - `"in_progress"` - - `type: "custom_tool_call"` + - `"completed"` - The type of the custom tool call. Always `custom_tool_call`. + - `"incomplete"` - - `id: optional string` + - `type: "function_call_output"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` @@ -46143,103 +56483,99 @@ openai beta:responses compact \ - `type: "program"` - - `namespace: optional string` - - The namespace of the custom tool being called. - - - `compaction_trigger: object { type, agent }` - - Compacts the current context. Must be the final input item. + The caller type. Always `program`. - - `type: "compaction_trigger"` + - `created_by: optional string` - The type of the item. Always `compaction_trigger`. + The identifier of the actor that created the item. - - `agent: optional object { agent_name }` +### Beta Response Function Web Search - The agent that produced this item. +- `beta_response_function_web_search: object { id, action, status, 2 more }` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `id: string` - - `item_reference: object { id, agent, type }` + The unique ID of the web search tool call. - An internal identifier for an item to reference. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `id: string` + 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). - The ID of the item to reference. + - `search: object { type, queries, query, sources }` - - `agent: optional object { agent_name }` + Action type "search" - Performs a web search query. - The agent that produced this item. + - `type: "search"` - - `agent_name: string` + The action type. - The canonical name of the agent that produced this item. + - `queries: optional array of string` - - `type: optional "item_reference"` + The search queries. - The type of item to reference. Always `item_reference`. + - `query: optional string` - - `"item_reference"` + The search query. - - `program: object { id, call_id, code, 3 more }` + - `sources: optional array of object { type, url }` - - `id: string` + The sources used in the search. - The unique ID of this program item. + - `type: "url"` - - `call_id: string` + The type of source. Always `url`. - The stable call ID of the program item. + - `url: string` - - `code: string` + The URL of the source. - The JavaScript source executed by programmatic tool calling. + - `open_page: object { type, url }` - - `fingerprint: string` + Action type "open_page" - Opens a specific URL from search results. - Opaque program replay fingerprint that must be round-tripped. + - `type: "open_page"` - - `type: "program"` + The action type. - The item type. Always `program`. + - `url: optional string` - - `agent: optional object { agent_name }` + The URL opened by the model. - The agent that produced this item. + - `find_in_page: object { pattern, type, url }` - - `agent_name: string` + Action type "find_in_page": Searches for a pattern within a loaded page. - The canonical name of the agent that produced this item. + - `pattern: string` - - `program_output: object { id, call_id, result, 3 more }` + The pattern or text to search for within the page. - - `id: string` + - `type: "find_in_page"` - The unique ID of this program output item. + The action type. - - `call_id: string` + - `url: string` - The call ID of the program item. + The URL of the page searched for the pattern. - - `result: string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The result produced by the program item. + The status of the web search tool call. - - `status: "completed" or "incomplete"` + - `"in_progress"` - The terminal status of the program output. + - `"searching"` - `"completed"` - - `"incomplete"` + - `"failed"` - - `type: "program_output"` + - `type: "web_search_call"` - The item type. Always `program_output`. + The type of the web search tool call. Always `web_search_call`. - `agent: optional object { agent_name }` @@ -46249,736 +56585,641 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `metadata: map[string]` - - 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. - - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. - - - `"gpt-5.6-sol"` - - - `"gpt-5.6-terra"` - - - `"gpt-5.6-luna"` - - - `"gpt-5.4"` - - - `"gpt-5.4-mini"` - - - `"gpt-5.4-nano"` - - - `"gpt-5.4-mini-2026-03-17"` - - - `"gpt-5.4-nano-2026-03-17"` - - - `"gpt-5.3-chat-latest"` - - - `"gpt-5.2"` - - - `"gpt-5.2-2025-12-11"` - - - `"gpt-5.2-chat-latest"` - - - `"gpt-5.2-pro"` - - - `"gpt-5.2-pro-2025-12-11"` - - - `"gpt-5.1"` - - - `"gpt-5.1-2025-11-13"` - - - `"gpt-5.1-codex"` - - - `"gpt-5.1-mini"` - - - `"gpt-5.1-chat-latest"` - - - `"gpt-5"` - - - `"gpt-5-mini"` - - - `"gpt-5-nano"` - - - `"gpt-5-2025-08-07"` - - - `"gpt-5-mini-2025-08-07"` - - - `"gpt-5-nano-2025-08-07"` - - - `"gpt-5-chat-latest"` - - - `"gpt-4.1"` - - - `"gpt-4.1-mini"` - - - `"gpt-4.1-nano"` - - - `"gpt-4.1-2025-04-14"` - - - `"gpt-4.1-mini-2025-04-14"` - - - `"gpt-4.1-nano-2025-04-14"` - - - `"o4-mini"` - - - `"o4-mini-2025-04-16"` +### Beta Response Image Gen Call Completed Event - - `"o3"` +- `beta_response_image_gen_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `"o3-2025-04-16"` + Emitted when an image generation tool call has completed and the final image is available. - - `"o3-mini"` + - `item_id: string` - - `"o3-mini-2025-01-31"` + The unique identifier of the image generation item being processed. - - `"o1"` + - `output_index: number` - - `"o1-2024-12-17"` + The index of the output item in the response's output array. - - `"o1-preview"` + - `sequence_number: number` - - `"o1-preview-2024-09-12"` + The sequence number of this event. - - `"o1-mini"` + - `type: "response.image_generation_call.completed"` - - `"o1-mini-2024-09-12"` + The type of the event. Always 'response.image_generation_call.completed'. - - `"gpt-4o"` + - `agent: optional object { agent_name }` - - `"gpt-4o-2024-11-20"` + The agent that owns this multi-agent streaming event. - - `"gpt-4o-2024-08-06"` + - `agent_name: string` - - `"gpt-4o-2024-05-13"` + The canonical name of the agent that produced this item. - - `"gpt-4o-audio-preview"` +### Beta Response Image Gen Call Generating Event - - `"gpt-4o-audio-preview-2024-10-01"` +- `beta_response_image_gen_call_generating_event: object { item_id, output_index, sequence_number, 2 more }` - - `"gpt-4o-audio-preview-2024-12-17"` + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `"gpt-4o-audio-preview-2025-06-03"` + - `item_id: string` - - `"gpt-4o-mini-audio-preview"` + The unique identifier of the image generation item being processed. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `output_index: number` - - `"gpt-4o-search-preview"` + The index of the output item in the response's output array. - - `"gpt-4o-mini-search-preview"` + - `sequence_number: number` - - `"gpt-4o-search-preview-2025-03-11"` + The sequence number of the image generation item being processed. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `type: "response.image_generation_call.generating"` - - `"chatgpt-4o-latest"` + The type of the event. Always 'response.image_generation_call.generating'. - - `"codex-mini-latest"` + - `agent: optional object { agent_name }` - - `"gpt-4o-mini"` + The agent that owns this multi-agent streaming event. - - `"gpt-4o-mini-2024-07-18"` + - `agent_name: string` - - `"gpt-4-turbo"` + The canonical name of the agent that produced this item. - - `"gpt-4-turbo-2024-04-09"` +### Beta Response Image Gen Call In Progress Event - - `"gpt-4-0125-preview"` +- `beta_response_image_gen_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `"gpt-4-turbo-preview"` + Emitted when an image generation tool call is in progress. - - `"gpt-4-1106-preview"` + - `item_id: string` - - `"gpt-4-vision-preview"` + The unique identifier of the image generation item being processed. - - `"gpt-4"` + - `output_index: number` - - `"gpt-4-0314"` + The index of the output item in the response's output array. - - `"gpt-4-0613"` + - `sequence_number: number` - - `"gpt-4-32k"` + The sequence number of the image generation item being processed. - - `"gpt-4-32k-0314"` + - `type: "response.image_generation_call.in_progress"` - - `"gpt-4-32k-0613"` + The type of the event. Always 'response.image_generation_call.in_progress'. - - `"gpt-3.5-turbo"` + - `agent: optional object { agent_name }` - - `"gpt-3.5-turbo-16k"` + The agent that owns this multi-agent streaming event. - - `"gpt-3.5-turbo-0301"` + - `agent_name: string` - - `"gpt-3.5-turbo-0613"` + The canonical name of the agent that produced this item. - - `"gpt-3.5-turbo-1106"` +### Beta Response Image Gen Call Partial Image Event - - `"gpt-3.5-turbo-0125"` +- `beta_response_image_gen_call_partial_image_event: object { item_id, output_index, partial_image_b64, 4 more }` - - `"gpt-3.5-turbo-16k-0613"` + Emitted when a partial image is available during image generation streaming. - - `"o1-pro"` + - `item_id: string` - - `"o1-pro-2025-03-19"` + The unique identifier of the image generation item being processed. - - `"o3-pro"` + - `output_index: number` - - `"o3-pro-2025-06-10"` + The index of the output item in the response's output array. - - `"o3-deep-research"` + - `partial_image_b64: string` - - `"o3-deep-research-2025-06-26"` + Base64-encoded partial image data, suitable for rendering as an image. - - `"o4-mini-deep-research"` + - `partial_image_index: number` - - `"o4-mini-deep-research-2025-06-26"` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `"computer-use-preview"` + - `sequence_number: number` - - `"computer-use-preview-2025-03-11"` + The sequence number of the image generation item being processed. - - `"gpt-5-codex"` + - `type: "response.image_generation_call.partial_image"` - - `"gpt-5-pro"` + The type of the event. Always 'response.image_generation_call.partial_image'. - - `"gpt-5-pro-2025-10-06"` + - `agent: optional object { agent_name }` - - `"gpt-5.1-codex-max"` + The agent that owns this multi-agent streaming event. - - `object: "response"` + - `agent_name: string` - The object type of this resource - always set to `response`. + The canonical name of the agent that produced this item. - - `output: array of BetaResponseOutputItem` +### Beta Response In Progress Event - An array of content items generated by the model. +- `beta_response_in_progress_event: object { response, sequence_number, type, agent }` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + Emitted when the response is in progress. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `response: object { id, created_at, error, 31 more }` - An output message from the model. + The response that is in progress. - `id: string` - The unique ID of the output message. - - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + Unique identifier for this Response. - The content of the output message. + - `created_at: number` - - `role: "assistant"` + Unix timestamp (in seconds) of when this Response was created. - The role of the output message. Always `assistant`. + - `error: object { code, message }` - - `status: "in_progress" or "completed" or "incomplete"` + An error object returned when the model fails to generate a Response. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `type: "message"` + The error code for the response. - The type of the output message. Always `message`. + - `"server_error"` - - `agent: optional object { agent_name }` + - `"rate_limit_exceeded"` - The agent that produced this item. + - `"invalid_prompt"` - - `phase: optional "commentary"` + - `"bio_policy"` - 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. + - `"vector_store_timeout"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `"invalid_image"` - 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. + - `"invalid_image_format"` - - `id: string` + - `"invalid_base64_image"` - The unique ID of the file search tool call. + - `"invalid_image_url"` - - `queries: array of string` + - `"image_too_large"` - The queries used to search for files. + - `"image_too_small"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"image_parse_error"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"image_content_policy_violation"` - - `type: "file_search_call"` + - `"invalid_image_mode"` - The type of the file search tool call. Always `file_search_call`. + - `"image_file_too_large"` - - `agent: optional object { agent_name }` + - `"unsupported_image_media_type"` - The agent that produced this item. + - `"empty_image_file"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"failed_to_download_image"` - The results of the file search tool call. + - `"image_file_not_found"` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `message: string` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + A human-readable description of the error. - - `arguments: string` + - `incomplete_details: object { reason }` - A JSON string of the arguments to pass to the function. + Details about why the response is incomplete. - - `call_id: string` + - `reason: optional "max_output_tokens" or "content_filter"` - The unique ID of the function tool call generated by the model. + The reason why the response is incomplete. - - `name: string` + - `"max_output_tokens"` - The name of the function to run. + - `"content_filter"` - - `type: "function_call"` + - `instructions: string or array of BetaResponseInputItem` - The type of the function tool call. Always `function_call`. + A system (or developer) message inserted into the model's context. - - `id: optional string` + When using 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. - The unique ID of the function tool call. + - `union_member_0: string` - - `agent: optional object { agent_name }` + A text input to the model, equivalent to a text input with the + `developer` role. - The agent that produced this item. + - `Input item list: array of BetaResponseInputItem` - - `caller: optional object { type } or object { caller_id, type }` + A list of one or many input items to the model, containing + different content types. - The execution context that produced this tool call. + - `beta_easy_input_message: object { content, role, phase, type }` - - `namespace: optional string` + 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. - The namespace of the function to run. + - `content: string or BetaResponseInputMessageContentList` - - `status: optional "in_progress" or "completed" or "incomplete"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Text input: string` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + A text input to the model. - - `id: string` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - The unique ID of the function call tool output. + A list of one or many input items to the model, containing different content + types. - - `call_id: string` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The unique ID of the function tool call generated by the model. + A text input to the model. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `text: string` - The output from the function call generated by your code. - Can be a string or an list of output content. + The text input to the model. - - `string output: string` + - `type: "input_text"` - A string of the output of the function call. + The type of the input item. Always `input_text`. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `prompt_cache_breakpoint: optional object { mode }` - Text, image, or file output of the function call. + 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. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `mode: "explicit"` - A text input to the model. + The breakpoint mode. Always `explicit`. - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + - `detail: "low" or "high" or "auto" or "original"` - - `type: "function_call_output"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of the function tool call output. Always `function_call_output`. + - `"low"` - - `agent: optional object { agent_name }` + - `"high"` - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"original"` - The canonical name of the agent that produced this item. + - `type: "input_image"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the input item. Always `input_image`. - The execution context that produced this tool call. + - `file_id: optional string` - - `direct: object { type }` + The ID of the file to be sent to the model. - - `program: object { caller_id, type }` + - `image_url: optional string` - - `caller_id: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The call ID of the program item that produced this tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "program"` + 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. - The caller type. Always `program`. + - `mode: "explicit"` - - `created_by: optional string` + The breakpoint mode. Always `explicit`. - The identifier of the actor that created the item. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `agent_message: object { id, author, content, 3 more }` + A file input to the model. - - `id: string` + - `type: "input_file"` - The unique ID of the agent message. + The type of the input item. Always `input_file`. - - `author: string` + - `detail: optional "auto" or "low" or "high"` - The sending agent identity. + 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`. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"auto"` - Encrypted content sent between agents. + - `"low"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"high"` - A text input to the model. + - `file_data: optional string` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + The content of the file to be sent to the model. - A text output from the model. + - `file_id: optional string` - - `text: object { text, type }` + The ID of the file to be sent to the model. - A text content. + - `file_url: optional string` - - `text: string` + The URL of the file to be sent to the model. - - `type: "text"` + - `filename: optional string` - - `summary_text: object { text, type }` + The name of the file to be sent to the model. - A summary text from the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `text: string` + 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. - A summary of the reasoning output from the model so far. + - `mode: "explicit"` - - `type: "summary_text"` + The breakpoint mode. Always `explicit`. - The type of the object. Always `summary_text`. + - `role: "user" or "assistant" or "system" or "developer"` - - `reasoning_text: object { text, type }` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Reasoning text from the model. + - `"user"` - - `text: string` + - `"assistant"` - The reasoning text from the model. + - `"system"` - - `type: "reasoning_text"` + - `"developer"` - The type of the reasoning text. Always `reasoning_text`. + - `phase: optional "commentary" or "final_answer"` - - `beta_response_output_refusal: object { refusal, type }` + 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. - A refusal from the model. + - `"commentary"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"final_answer"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: optional "message"` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + The type of the message input. Always `message`. - A screenshot of a computer. + - `"message"` - - `detail: "low" or "high" or "auto" or "original"` + - `message: object { content, role, agent, 2 more }` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + 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. - - `"low"` + - `content: array of BetaResponseInputContent` - - `"high"` + A list of one or many input items to the model, containing different content + types. - - `"auto"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"original"` + A text input to the model. - - `file_id: string` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The identifier of an uploaded file that contains the screenshot. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `image_url: string` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The URL of the screenshot image. + A file input to the model. - - `type: "computer_screenshot"` + - `role: "user" or "system" or "developer"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The role of the message input. One of `user`, `system`, or `developer`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"user"` - 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. + - `"system"` - - `mode: "explicit"` + - `"developer"` - The breakpoint mode. Always `explicit`. + - `agent: optional object { agent_name }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The agent that produced this item. - A file input to the model. + - `agent_name: string` - - `encrypted_content: object { encrypted_content, type }` + The canonical name of the agent that produced this item. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `encrypted_content: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Opaque encrypted content. + - `"in_progress"` - - `type: "encrypted_content"` + - `"completed"` - The type of the input item. Always `encrypted_content`. + - `"incomplete"` - - `recipient: string` + - `type: optional "message"` - The destination agent identity. + The type of the message input. Always set to `message`. - - `type: "agent_message"` + - `"message"` - The type of the item. Always `agent_message`. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `agent: optional object { agent_name }` + An output message from the model. - The agent that produced this item. + - `id: string` - - `agent_name: string` + The unique ID of the output message. - The canonical name of the agent that produced this item. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `multi_agent_call: object { id, action, arguments, 3 more }` + The content of the output message. - - `id: string` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - The unique ID of the multi-agent call item. + A text output from the model. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The multi-agent action to execute. + The annotations of the text output. - - `"spawn_agent"` + - `file_citation: object { file_id, filename, index, type }` - - `"interrupt_agent"` + A citation to a file. - - `"list_agents"` + - `file_id: string` - - `"send_message"` + The ID of the file. - - `"followup_task"` + - `filename: string` - - `"wait_agent"` + The filename of the file cited. - - `arguments: string` + - `index: number` - The JSON string of arguments generated for the action. + The index of the file in the list of files. - - `call_id: string` + - `type: "file_citation"` - The unique ID linking this call to its output. + The type of the file citation. Always `file_citation`. - - `type: "multi_agent_call"` + - `url_citation: object { end_index, start_index, title, 2 more }` - The type of the multi-agent call. Always `multi_agent_call`. + A citation for a web resource used to generate a model response. - - `agent: optional object { agent_name }` + - `end_index: number` - The agent that produced this item. + The index of the last character of the URL citation in the message. - - `agent_name: string` + - `start_index: number` - The canonical name of the agent that produced this item. + The index of the first character of the URL citation in the message. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `title: string` - - `id: string` + The title of the web resource. - The unique ID of the multi-agent call output item. + - `type: "url_citation"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The type of the URL citation. Always `url_citation`. - The multi-agent action that produced this result. + - `url: string` - - `"spawn_agent"` + The URL of the web resource. - - `"interrupt_agent"` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `"list_agents"` + A citation for a container file used to generate a model response. - - `"send_message"` + - `container_id: string` - - `"followup_task"` + The ID of the container file. - - `"wait_agent"` + - `end_index: number` - - `call_id: string` + The index of the last character of the container file citation in the message. - The unique ID of the multi-agent call. + - `file_id: string` - - `output: array of BetaResponseOutputText` + The ID of the file. - Text output returned by the multi-agent action. + - `filename: string` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The filename of the container file cited. - The annotations of the text output. + - `start_index: number` - - `text: string` + The index of the first character of the container file citation in the message. - The text output from the model. + - `type: "container_file_citation"` - - `type: "output_text"` + The type of the container file citation. Always `container_file_citation`. - The type of the output text. Always `output_text`. + - `file_path: object { file_id, index, type }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + A path to a file. - - `type: "multi_agent_call_output"` + - `file_id: string` - The type of the multi-agent result. Always `multi_agent_call_output`. + The ID of the file. - - `agent: optional object { agent_name }` + - `index: number` - The agent that produced this item. + The index of the file in the list of files. - - `agent_name: string` + - `type: "file_path"` - The canonical name of the agent that produced this item. + The type of the file path. Always `file_path`. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `text: string` - 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. + The text output from the model. - - `id: string` + - `type: "output_text"` - The unique ID of the web search tool call. + The type of the output text. Always `output_text`. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - 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). + - `token: string` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `bytes: array of number` - The status of the web search tool call. + - `logprob: number` - - `type: "web_search_call"` + - `top_logprobs: array of object { token, bytes, logprob }` - The type of the web search tool call. Always `web_search_call`. + - `token: string` - - `agent: optional object { agent_name }` + - `bytes: array of number` - The agent that produced this item. + - `logprob: number` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `beta_response_output_refusal: object { refusal, type }` - 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. + A refusal from the model. - - `id: string` + - `refusal: string` - The unique ID of the computer call. + The refusal explanation from the model. - - `call_id: string` + - `type: "refusal"` - An identifier used when responding to the tool call with output. + The type of the refusal. Always `refusal`. - - `pending_safety_checks: array of object { id, code, message }` + - `role: "assistant"` - The pending safety checks for the computer call. + The role of the output message. Always `assistant`. - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `type: "computer_call"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The type of the computer call. Always `computer_call`. + - `"in_progress"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `"completed"` - A click action. + - `"incomplete"` - - `actions: optional array of BetaComputerAction` + - `type: "message"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The type of the output message. Always `message`. - `agent: optional object { agent_name }` The agent that produced this item. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The unique ID of the computer call tool output. + - `phase: optional "commentary" or "final_answer"` - - `call_id: string` + 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. - The ID of the computer tool call that produced the output. + - `"commentary"` - - `output: object { type, file_id, image_url }` + - `"final_answer"` - A computer screenshot image used with the computer use tool. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `type: "computer_screenshot"` + 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. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `id: string` - - `file_id: optional string` + The unique ID of the file search tool call. - The identifier of an uploaded file that contains the screenshot. + - `queries: array of string` - - `image_url: optional string` + The queries used to search for files. - The URL of the screenshot image. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"in_progress"` + + - `"searching"` - `"completed"` @@ -46986,463 +57227,468 @@ openai beta:responses compact \ - `"failed"` - - `"in_progress"` + - `type: "file_search_call"` - - `type: "computer_call_output"` + The type of the file search tool call. Always `file_search_call`. - The type of the computer tool call output. Always `computer_call_output`. + - `agent: optional object { agent_name }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The agent that produced this item. - The safety checks reported by the API that have been acknowledged by the - developer. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The ID of the pending safety check. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `code: optional string` + The results of the file search tool call. - The type of the pending safety check. + - `attributes: optional map[string or number or boolean]` - - `message: optional string` + 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. - Details about the pending safety check. + - `union_member_0: string` - - `agent: optional object { agent_name }` + - `union_member_1: number` - The agent that produced this item. + - `union_member_2: boolean` - - `agent_name: string` + - `file_id: optional string` - The canonical name of the agent that produced this item. + The unique ID of the file. - - `created_by: optional string` + - `filename: optional string` - The identifier of the actor that created the item. + The name of the file. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `score: optional number` - 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). + The relevance score of the file - a value between 0 and 1. - - `id: string` + - `text: optional string` - The unique identifier of the reasoning content. + The text that was retrieved from the file. - - `summary: array of object { text, type }` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - Reasoning summary content. + 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. - - `type: "reasoning"` + - `id: string` - The type of the object. Always `reasoning`. + The unique ID of the computer call. - - `agent: optional object { agent_name }` + - `call_id: string` - The agent that produced this item. + An identifier used when responding to the tool call with output. - - `content: optional array of object { text, type }` + - `pending_safety_checks: array of object { id, code, message }` - Reasoning text content. + The pending safety checks for the computer call. - - `encrypted_content: optional string` + - `id: string` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The ID of the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `code: optional string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the pending safety check. - - `program: object { id, call_id, code, 3 more }` + - `message: optional string` - - `id: string` + Details about the pending safety check. - The unique ID of the program item. + - `status: "in_progress" or "completed" or "incomplete"` - - `call_id: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The stable call ID of the program item. + - `"in_progress"` - - `code: string` + - `"completed"` - The JavaScript source executed by programmatic tool calling. + - `"incomplete"` - - `fingerprint: string` + - `type: "computer_call"` - Opaque program replay fingerprint that must be round-tripped. + The type of the computer call. Always `computer_call`. - - `type: "program"` + - `"computer_call"` - The type of the item. Always `program`. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `agent: optional object { agent_name }` + A click action. - The agent that produced this item. + - `click: object { button, type, x, 2 more }` - - `agent_name: string` + A click action. - The canonical name of the agent that produced this item. + - `button: "left" or "right" or "wheel" or 2 more` - - `program_output: object { id, call_id, result, 3 more }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `id: string` + - `"left"` - The unique ID of the program output item. + - `"right"` - - `call_id: string` + - `"wheel"` - The call ID of the program item. + - `"back"` - - `result: string` + - `"forward"` - The result produced by the program item. + - `type: "click"` - - `status: "completed" or "incomplete"` + Specifies the event type. For a click action, this property is always `click`. - The terminal status of the program output item. + - `x: number` - - `"completed"` + The x-coordinate where the click occurred. - - `"incomplete"` + - `y: number` - - `type: "program_output"` + The y-coordinate where the click occurred. - The type of the item. Always `program_output`. + - `keys: optional array of string` - - `agent: optional object { agent_name }` + The keys being held while clicking. - The agent that produced this item. + - `double_click: object { keys, type, x, y }` - - `agent_name: string` + A double click action. - The canonical name of the agent that produced this item. + - `keys: array of string` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + The keys being held while double-clicking. - - `id: string` + - `type: "double_click"` - The unique ID of the tool search call item. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `arguments: unknown` + - `x: number` - Arguments used for the tool search call. + The x-coordinate where the double click occurred. - - `call_id: string` + - `y: number` - The unique ID of the tool search call generated by the model. + The y-coordinate where the double click occurred. - - `execution: "server" or "client"` + - `drag: object { path, type, keys }` - Whether tool search was executed by the server or by the client. + A drag action. - - `"server"` + - `path: array of object { x, y }` - - `"client"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `status: "in_progress" or "completed" or "incomplete"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The status of the tool search call item that was recorded. + - `x: number` - - `"in_progress"` + The x-coordinate. - - `"completed"` + - `y: number` - - `"incomplete"` + The y-coordinate. - - `type: "tool_search_call"` + - `type: "drag"` - The type of the item. Always `tool_search_call`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `agent: optional object { agent_name }` + - `keys: optional array of string` - The agent that produced this item. + The keys being held while dragging the mouse. - - `agent_name: string` + - `keypress: object { keys, type }` - The canonical name of the agent that produced this item. + A collection of keypresses the model would like to perform. - - `created_by: optional string` + - `keys: array of string` - The identifier of the actor that created the item. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `type: "keypress"` - - `id: string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The unique ID of the tool search output item. + - `move: object { type, x, y, keys }` - - `call_id: string` + A mouse move action. - The unique ID of the tool search call generated by the model. + - `type: "move"` - - `execution: "server" or "client"` + Specifies the event type. For a move action, this property is always set to `move`. - Whether tool search was executed by the server or by the client. + - `x: number` - - `"server"` + The x-coordinate to move to. - - `"client"` + - `y: number` - - `status: "in_progress" or "completed" or "incomplete"` + The y-coordinate to move to. - The status of the tool search output item that was recorded. + - `keys: optional array of string` - - `"in_progress"` + The keys being held while moving the mouse. - - `"completed"` + - `screenshot: object { type }` - - `"incomplete"` + A screenshot action. - - `tools: array of BetaTool` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The loaded tool definitions returned by tool search. + A scroll action. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `scroll_x: number` - 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). + The horizontal scroll distance. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `scroll_y: number` - 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). + The vertical scroll distance. - - `beta_computer_tool: object { type }` + - `type: "scroll"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `x: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The x-coordinate where the scroll occurred. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `y: number` - 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). + The y-coordinate where the scroll occurred. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `keys: optional array of string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The keys being held while scrolling. - - `code_interpreter: object { container, type, allowed_callers }` + - `type: object { text, type }` - A tool that runs Python code to help generate a response to a prompt. + An action to type in text. - - `programmatic_tool_calling: object { type }` + - `text: string` - - `image_generation: object { type, action, background, 9 more }` + The text to type. - A tool that generates images using the GPT image models. + - `type: "type"` - - `local_shell: object { type }` + Specifies the event type. For a type action, this property is always set to `type`. - A tool that allows the model to execute shell commands in a local environment. + - `wait: object { type }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + A wait action. - A tool that allows the model to execute shell commands. + - `actions: optional array of BetaComputerAction` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - 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) + - `click: object { button, type, x, 2 more }` - - `beta_namespace_tool: object { description, name, tools, type }` + A click action. - Groups function/custom tools under a shared namespace. + - `double_click: object { keys, type, x, y }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + A double click action. - Hosted or BYOT tool search configuration for deferred tools. + - `drag: object { path, type, keys }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + A drag action. - 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). + - `keypress: object { keys, type }` - - `beta_apply_patch_tool: object { type, allowed_callers }` + A collection of keypresses the model would like to perform. - Allows the assistant to create, delete, or update files using unified diffs. + - `move: object { type, x, y, keys }` - - `type: "tool_search_output"` + A mouse move action. - The type of the item. Always `tool_search_output`. + - `screenshot: object { type }` - - `agent: optional object { agent_name }` + A screenshot action. - The agent that produced this item. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `agent_name: string` + A scroll action. - The canonical name of the agent that produced this item. + - `type: object { text, type }` - - `created_by: optional string` + An action to type in text. - The identifier of the actor that created the item. + - `wait: object { type }` - - `additional_tools: object { id, role, tools, 2 more }` + A wait action. - - `id: string` + - `agent: optional object { agent_name }` - The unique ID of the additional tools item. + The agent that produced this item. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `agent_name: string` - The role that provided the additional tools. + The canonical name of the agent that produced this item. - - `"unknown"` + - `computer_call_output: object { call_id, output, type, 4 more }` - - `"user"` + The output of a computer tool call. - - `"assistant"` + - `call_id: string` - - `"system"` + The ID of the computer tool call that produced the output. - - `"critic"` + - `output: object { type, file_id, image_url }` - - `"discriminator"` + A computer screenshot image used with the computer use tool. - - `"developer"` + - `type: "computer_screenshot"` - - `"tool"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `tools: array of BetaTool` + - `file_id: optional string` - The additional tool definitions made available at this item. + The identifier of an uploaded file that contains the screenshot. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `image_url: optional string` - 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). + The URL of the screenshot image. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `type: "computer_call_output"` - 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). + The type of the computer tool call output. Always `computer_call_output`. - - `beta_computer_tool: object { type }` + - `id: optional string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the computer tool call output. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The safety checks reported by the API that have been acknowledged by the developer. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `id: string` - 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). + The ID of the pending safety check. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `code: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The type of the pending safety check. - - `code_interpreter: object { container, type, allowed_callers }` + - `message: optional string` - A tool that runs Python code to help generate a response to a prompt. + Details about the pending safety check. - - `programmatic_tool_calling: object { type }` + - `agent: optional object { agent_name }` - - `image_generation: object { type, action, background, 9 more }` + The agent that produced this item. - A tool that generates images using the GPT image models. + - `agent_name: string` - - `local_shell: object { type }` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands in a local environment. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - A tool that allows the model to execute shell commands. + - `"in_progress"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `"completed"` - 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) + - `"incomplete"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - Groups function/custom tools under a shared namespace. + 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. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `id: string` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the web search tool call. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - 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). + 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). - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `search: object { type, queries, query, sources }` - Allows the assistant to create, delete, or update files using unified diffs. + Action type "search" - Performs a web search query. - - `type: "additional_tools"` + - `type: "search"` - The type of the item. Always `additional_tools`. + The action type. - - `agent: optional object { agent_name }` + - `queries: optional array of string` - The agent that produced this item. + The search queries. - - `agent_name: string` + - `query: optional string` - The canonical name of the agent that produced this item. + The search query. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `sources: optional array of object { type, url }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The sources used in the search. - - `id: string` + - `type: "url"` - The unique ID of the compaction item. + The type of source. Always `url`. - - `encrypted_content: string` + - `url: string` - The encrypted content that was produced by compaction. + The URL of the source. - - `type: "compaction"` + - `open_page: object { type, url }` - The type of the item. Always `compaction`. + Action type "open_page" - Opens a specific URL from search results. - - `agent: optional object { agent_name }` + - `type: "open_page"` - The agent that produced this item. + The action type. - - `agent_name: string` + - `url: optional string` - The canonical name of the agent that produced this item. + The URL opened by the model. - - `created_by: optional string` + - `find_in_page: object { pattern, type, url }` - The identifier of the actor that created the item. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `image_generation_call: object { id, result, status, 2 more }` + - `pattern: string` - An image generation request made by the model. + The pattern or text to search for within the page. - - `id: string` + - `type: "find_in_page"` - The unique ID of the image generation call. + The action type. - - `result: string` + - `url: string` - The generated image encoded in base64. + The URL of the page searched for the pattern. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The status of the image generation call. + The status of the web search tool call. - `"in_progress"` - - `"completed"` + - `"searching"` - - `"generating"` + - `"completed"` - `"failed"` - - `type: "image_generation_call"` + - `type: "web_search_call"` - The type of the image generation call. Always `image_generation_call`. + The type of the web search tool call. Always `web_search_call`. - `agent: optional object { agent_name }` @@ -47452,196 +57698,193 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - A tool call to run code. - - - `id: string` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The unique ID of the code interpreter tool call. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `code: string` + - `arguments: string` - The code to run, or null if not available. + A JSON string of the arguments to pass to the function. - - `container_id: string` + - `call_id: string` - The ID of the container used to run the code. + The unique ID of the function tool call generated by the model. - - `outputs: array of object { logs, type } or object { type, url }` + - `name: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The name of the function to run. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `type: "function_call"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The type of the function tool call. Always `function_call`. - - `type: "code_interpreter_call"` + - `id: optional string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The unique ID of the function tool call. - `agent: optional object { agent_name }` The agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `agent_name: string` - A tool call to run a command on the local shell. + The canonical name of the agent that produced this item. - - `id: string` + - `caller: optional object { type } or object { caller_id, type }` - The unique ID of the local shell call. + The execution context that produced this tool call. - - `action: object { command, env, type, 3 more }` + - `direct: object { type }` - Execute a shell command on the server. + - `program: object { caller_id, type }` - - `command: array of string` + - `caller_id: string` - The command to run. + The call ID of the program item that produced this tool call. - - `env: map[string]` + - `type: "program"` - Environment variables to set for the command. + - `namespace: optional string` - - `type: "exec"` + The namespace of the function to run. - The type of the local shell action. Always `exec`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `timeout_ms: optional number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Optional timeout in milliseconds for the command. + - `"in_progress"` - - `user: optional string` + - `"completed"` - Optional user to run the command as. + - `"incomplete"` - - `working_directory: optional string` + - `function_call_output: object { call_id, output, type, 4 more }` - Optional working directory to run the command in. + The output of a function tool call. - `call_id: string` - The unique ID of the local shell tool call generated by the model. + The unique ID of the function tool call generated by the model. - - `status: "in_progress" or "completed" or "incomplete"` + - `output: string or BetaResponseFunctionCallOutputItemList` - The status of the local shell call. + Text, image, or file output of the function tool call. - - `"in_progress"` + - `union_member_0: string` - - `"completed"` + A JSON string of the output of the function tool call. - - `"incomplete"` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - - `type: "local_shell_call"` + An array of content outputs (text, image, file) for the function tool call. - The type of the local shell call. Always `local_shell_call`. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text input to the model. - The canonical name of the agent that produced this item. + - `type: "input_text"` - - `local_shell_call_output: object { id, output, type, 2 more }` + The type of the input item. Always `input_text`. - The output of a local shell tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `id: string` + 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. - The unique ID of the local shell tool call generated by the model. + - `mode: "explicit"` - - `output: string` + The breakpoint mode. Always `explicit`. - A JSON string of the output of the local shell tool call. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `type: "local_shell_call_output"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The type of the local shell tool call output. Always `local_shell_call_output`. + - `type: "input_image"` - - `agent: optional object { agent_name }` + The type of the input item. Always `input_image`. - The agent that produced this item. + - `detail: optional "low" or "high" or "auto" or "original"` - - `agent_name: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The canonical name of the agent that produced this item. + - `"low"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"high"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"auto"` - - `"in_progress"` + - `"original"` - - `"completed"` + - `file_id: optional string` - - `"incomplete"` + The ID of the file to be sent to the model. - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `image_url: optional string` - A tool call that executes one or more shell commands in a managed environment. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The unique ID of the shell tool call. Populated when this item is returned via API. + 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. - - `action: object { commands, max_output_length, timeout_ms }` + - `mode: "explicit"` - The shell commands and limits that describe how to run the tool call. + The breakpoint mode. Always `explicit`. - - `commands: array of string` + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `max_output_length: number` + A file input to the model. - Optional maximum number of characters to return from each command. + - `type: "input_file"` - - `timeout_ms: number` + The type of the input item. Always `input_file`. - Optional timeout in milliseconds for the commands. + - `detail: optional "auto" or "low" or "high"` - - `call_id: string` + 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`. - The unique ID of the shell tool call generated by the model. + - `"auto"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `"low"` - Represents the use of a local environment to perform shell actions. + - `"high"` - - `beta_response_local_environment: object { type }` + - `file_data: optional string` - Represents the use of a local environment to perform shell actions. + The base64-encoded data of the file to be sent to the model. - - `type: "local"` + - `file_id: optional string` - The environment type. Always `local`. + The ID of the file to be sent to the model. - - `beta_response_container_reference: object { container_id, type }` + - `file_url: optional string` - Represents a container created with /v1/containers. + The URL of the file to be sent to the model. - - `container_id: string` + - `filename: optional string` - - `type: "container_reference"` + The name of the file to be sent to the model. - The environment type. Always `container_reference`. + - `prompt_cache_breakpoint: optional object { mode }` - - `status: "in_progress" or "completed" or "incomplete"` + 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. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `mode: "explicit"` - - `"in_progress"` + The breakpoint mode. Always `explicit`. - - `"completed"` + - `type: "function_call_output"` - - `"incomplete"` + The type of the function tool call output. Always `function_call_output`. - - `type: "shell_call"` + - `id: optional string` - The type of the item. Always `shell_call`. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -47665,277 +57908,277 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The ID of the entity that created this tool call. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The output of a shell tool call that was emitted. + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"incomplete"` - - `call_id: string` + - `agent_message: object { author, content, recipient, 3 more }` - The unique ID of the shell tool call generated by the model. + A message routed between agents. - - `max_output_length: number` + - `author: string` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The sending agent identity. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - An array of shell call output contents + Plaintext, image, or encrypted content sent between agents. - - `outcome: object { type } or object { exit_code, type }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + A text input to the model. - - `timeout: object { type }` + - `text: string` - Indicates that the shell call exceeded its configured time limit. + The text input to the model. - - `exit: object { exit_code, type }` + - `type: "input_text"` - Indicates that the shell commands finished and returned an exit code. + The type of the input item. Always `input_text`. - - `exit_code: number` + - `prompt_cache_breakpoint: optional object { mode }` - Exit code from the shell process. + 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. - - `type: "exit"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The outcome type. Always `exit`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `stderr: string` + - `type: "input_image"` - The standard error output that was captured. + The type of the input item. Always `input_image`. - - `stdout: string` + - `detail: optional "low" or "high" or "auto" or "original"` - The standard output that was captured. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `created_by: optional string` + - `file_id: optional string` - The identifier of the actor that created the item. + The ID of the file to be sent to the model. - - `status: "in_progress" or "completed" or "incomplete"` + - `image_url: optional string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"in_progress"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"completed"` + 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. - - `"incomplete"` + - `encrypted_content: object { encrypted_content, type }` - - `type: "shell_call_output"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The type of the shell call output. Always `shell_call_output`. + - `encrypted_content: string` - - `agent: optional object { agent_name }` + Opaque encrypted content. - The agent that produced this item. + - `type: "encrypted_content"` - - `agent_name: string` + The type of the input item. Always `encrypted_content`. - The canonical name of the agent that produced this item. + - `recipient: string` - - `caller: optional object { type } or object { caller_id, type }` + The destination agent identity. - The execution context that produced this tool call. + - `type: "agent_message"` - - `direct: object { type }` + The item type. Always `agent_message`. - - `program: object { caller_id, type }` + - `id: optional string` - - `caller_id: string` + The unique ID of this agent message item. - The call ID of the program item that produced this tool call. + - `agent: optional object { agent_name }` - - `type: "program"` + The agent that produced this item. - - `created_by: optional string` + - `agent_name: string` - The identifier of the actor that created the item. + The canonical name of the agent that produced this item. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - A tool call that applies file diffs by creating, deleting, or updating files. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `id: string` + The multi-agent action that was executed. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"spawn_agent"` - - `call_id: string` + - `"interrupt_agent"` - The unique ID of the apply patch tool call generated by the model. + - `"list_agents"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"send_message"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `"followup_task"` - - `create_file: object { diff, path, type }` + - `"wait_agent"` - Instruction describing how to create a file via the apply_patch tool. + - `arguments: string` - - `diff: string` + The action arguments as a JSON string. - Diff to apply. + - `call_id: string` - - `path: string` + The unique ID linking this call to its output. - Path of the file to create. + - `type: "multi_agent_call"` - - `type: "create_file"` + The item type. Always `multi_agent_call`. - Create a new file with the provided diff. + - `id: optional string` - - `delete_file: object { path, type }` + The unique ID of this multi-agent call. - Instruction describing how to delete a file via the apply_patch tool. + - `agent: optional object { agent_name }` - - `path: string` + The agent that produced this item. - Path of the file to delete. + - `agent_name: string` - - `type: "delete_file"` + The canonical name of the agent that produced this item. - Delete the specified file. + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - `update_file: object { diff, path, type }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Instruction describing how to update a file via the apply_patch tool. + The multi-agent action that produced this result. - - `diff: string` + - `"spawn_agent"` - Diff to apply. + - `"interrupt_agent"` - - `path: string` + - `"list_agents"` - Path of the file to update. + - `"send_message"` - - `type: "update_file"` + - `"followup_task"` - Update an existing file with the provided diff. + - `"wait_agent"` - - `status: "in_progress" or "completed"` + - `call_id: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The unique ID of the multi-agent call. - - `"in_progress"` + - `output: array of object { text, type, annotations }` - - `"completed"` + Text output returned by the multi-agent action. - - `type: "apply_patch_call"` + - `text: string` - The type of the item. Always `apply_patch_call`. + The text content. - - `agent: optional object { agent_name }` + - `type: "output_text"` - The agent that produced this item. + The content type. Always `output_text`. - - `agent_name: string` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - The canonical name of the agent that produced this item. + Citations associated with the text content. - - `caller: optional object { type } or object { caller_id, type }` + - `union_member_0: array of object { file_id, filename, index, type }` - The execution context that produced this tool call. + - `file_id: string` - - `direct: object { type }` + The ID of the file. - - `program: object { caller_id, type }` + - `filename: string` - - `caller_id: string` + The filename of the file cited. - The call ID of the program item that produced this tool call. + - `index: number` - - `type: "program"` + The index of the file in the list of files. - - `created_by: optional string` + - `type: "file_citation"` - The ID of the entity that created this tool call. + The citation type. Always `file_citation`. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - The output emitted by an apply patch tool call. + - `end_index: number` - - `id: string` + The index of the last character of the citation in the message. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `start_index: number` - - `call_id: string` + The index of the first character of the citation in the message. - The unique ID of the apply patch tool call generated by the model. + - `title: string` - - `status: "completed" or "failed"` + The title of the cited resource. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `type: "url_citation"` - - `"completed"` + The citation type. Always `url_citation`. - - `"failed"` + - `url: string` - - `type: "apply_patch_call_output"` + The URL of the cited resource. - The type of the item. Always `apply_patch_call_output`. + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `agent: optional object { agent_name }` + - `container_id: string` - The agent that produced this item. + The ID of the container. - - `agent_name: string` + - `end_index: number` - The canonical name of the agent that produced this item. + The index of the last character of the citation in the message. - - `caller: optional object { type } or object { caller_id, type }` + - `file_id: string` - The execution context that produced this tool call. + The ID of the container file. - - `direct: object { type }` + - `filename: string` - - `program: object { caller_id, type }` + The filename of the container file cited. - - `caller_id: string` + - `start_index: number` - The call ID of the program item that produced this tool call. + The index of the first character of the citation in the message. - - `type: "program"` + - `type: "container_file_citation"` - - `created_by: optional string` + The citation type. Always `container_file_citation`. - The ID of the entity that created this tool call output. + - `type: "multi_agent_call_output"` - - `output: optional string` + The item type. Always `multi_agent_call_output`. - Optional textual output returned by the apply patch tool. + - `id: optional string` - - `mcp_call: object { id, arguments, name, 7 more }` + The unique ID of this multi-agent call output. - An invocation of a tool on an MCP server. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - The unique ID of the tool call. + - `agent_name: string` - - `arguments: string` + The canonical name of the agent that produced this item. - A JSON string of the arguments passed to the tool. + - `tool_search_call: object { arguments, type, id, 4 more }` - - `name: string` + - `arguments: unknown` - The name of the tool that was run. + The arguments supplied to the tool search call. - - `server_label: string` + - `type: "tool_search_call"` - The label of the MCP server running the tool. + The item type. Always `tool_search_call`. - - `type: "mcp_call"` + - `id: optional string` - The type of the item. Always `mcp_call`. + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -47945,22 +58188,21 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `call_id: optional string` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The unique ID of the tool search call generated by the model. - - `error: optional string` + - `execution: optional "server" or "client"` - The error from the tool call, if any. + Whether tool search was executed by the server or by the client. - - `output: optional string` + - `"server"` - The output from the tool call. + - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the tool search call. - `"in_progress"` @@ -47968,681 +58210,671 @@ openai beta:responses compact \ - `"incomplete"` - - `"calling"` - - - `"failed"` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `tools: array of BetaTool` - A list of tools available on an MCP server. + The loaded tool definitions returned by the tool search output. - - `id: string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The unique ID of the list. + 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). - - `server_label: string` + - `name: string` - The label of the MCP server. + The name of the function to call. - - `tools: array of object { input_schema, name, annotations, description }` + - `parameters: map[unknown]` - The tools available on the server. + A JSON schema object describing the parameters of the function. - - `input_schema: unknown` + - `strict: boolean` - The JSON schema describing the tool's input. + Whether strict parameter validation is enforced for this function tool. - - `name: string` + - `type: "function"` - The name of the tool. + The type of the function tool. Always `function`. - - `annotations: optional unknown` + - `allowed_callers: optional array of "direct" or "programmatic"` - Additional annotations about the tool. + The tool invocation context(s). - - `description: optional string` + - `"direct"` - The description of the tool. + - `"programmatic"` - - `type: "mcp_list_tools"` + - `defer_loading: optional boolean` - The type of the item. Always `mcp_list_tools`. + Whether this function is deferred and loaded via tool search. - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + A description of the function. Used by the model to determine whether or not to call the function. - - `agent_name: string` + - `output_schema: optional map[unknown]` - The canonical name of the agent that produced this item. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `error: optional string` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - Error message if the server could not list tools. + 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). - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `type: "file_search"` - A request for human approval of a tool invocation. + The type of the file search tool. Always `file_search`. - - `id: string` + - `vector_store_ids: array of string` - The unique ID of the approval request. + The IDs of the vector stores to search. - - `arguments: string` + - `filters: optional object { key, type, value } or object { filters, type }` - A JSON string of arguments for the tool. + A filter to apply. - - `name: string` + - `Comparison Filter: object { key, type, value }` - The name of the tool to run. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `server_label: string` + - `key: string` - The label of the MCP server making the request. + The key to compare against the value. - - `type: "mcp_approval_request"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of the item. Always `mcp_approval_request`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent: optional object { agent_name }` + - `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 - The agent that produced this item. + - `"eq"` - - `agent_name: string` + - `"ne"` - The canonical name of the agent that produced this item. + - `"gt"` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `"gte"` - A response to an MCP approval request. + - `"lt"` - - `id: string` + - `"lte"` - The unique ID of the approval response + - `"in"` - - `approval_request_id: string` + - `"nin"` - The ID of the approval request being answered. + - `value: string or number or boolean or array of string or number` - - `approve: boolean` + The value to compare against the attribute key; supports string, number, or boolean types. - Whether the request was approved. + - `union_member_0: string` - - `type: "mcp_approval_response"` + - `union_member_1: number` - The type of the item. Always `mcp_approval_response`. + - `union_member_2: boolean` - - `agent: optional object { agent_name }` + - `union_member_3: array of string or number` - The agent that produced this item. + - `union_member_0: string` - - `agent_name: string` + - `union_member_1: number` - The canonical name of the agent that produced this item. + - `Compound Filter: object { filters, type }` - - `reason: optional string` + Combine multiple filters using `and` or `or`. - Optional reason for the decision. + - `filters: array of object { key, type, value } or unknown` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - A call to a custom tool created by the model. + - `Comparison Filter: object { key, type, value }` - - `call_id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - An identifier used to map this custom tool call to a tool call output. + - `key: string` - - `input: string` + The key to compare against the value. - The input for the custom tool call generated by the model. + - `type: "eq" or "ne" or "gt" or 5 more` - - `name: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The name of the custom tool being called. + - `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 - - `type: "custom_tool_call"` + - `"eq"` - The type of the custom tool call. Always `custom_tool_call`. + - `"ne"` - - `id: optional string` + - `"gt"` - The unique ID of the custom tool call in the OpenAI platform. + - `"gte"` - - `agent: optional object { agent_name }` + - `"lt"` - The agent that produced this item. + - `"lte"` - - `caller: optional object { type } or object { caller_id, type }` + - `"in"` - The execution context that produced this tool call. + - `"nin"` - - `namespace: optional string` + - `value: string or number or boolean or array of string or number` - The namespace of the custom tool being called. + The value to compare against the attribute key; supports string, number, or boolean types. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `union_member_0: string` - The output of a custom tool call from your code, being sent back to the model. + - `union_member_1: number` - - `id: string` + - `union_member_2: boolean` - The unique ID of the custom tool call output item. + - `union_member_3: array of string or number` - - `status: "in_progress" or "completed" or "incomplete"` + - `union_member_0: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `union_member_1: number` - - `"in_progress"` + - `union_member_1: unknown` - - `"completed"` + - `type: "and" or "or"` - - `"incomplete"` + Type of operation: `and` or `or`. - - `created_by: optional string` + - `"and"` - The identifier of the actor that created the item. + - `"or"` - - `parallel_tool_calls: boolean` + - `max_num_results: optional number` - Whether to allow the model to run tool calls in parallel. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `temperature: number` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + Ranking options for search. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `hybrid_search: optional object { embedding_weight, text_weight }` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `beta_tool_choice_options: "none" or "auto" or "required"` + - `embedding_weight: number` - Controls which (if any) tool is called by the model. + The weight of the embedding in the reciprocal ranking fusion. - `none` means the model will not call any tool and instead generates a message. + - `text_weight: number` - `auto` means the model can pick between generating a message or calling one or - more tools. + The weight of the text in the reciprocal ranking fusion. - `required` means the model must call one or more tools. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"none"` + The ranker to use for the file search. - `"auto"` - - `"required"` - - - `beta_tool_choice_allowed: object { mode, tools, type }` - - Constrains the tools available to the model to a pre-defined set. + - `"default-2024-11-15"` - - `mode: "auto" or "required"` + - `score_threshold: optional number` - Constrains the tools available to the model to a pre-defined set. + 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. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `beta_computer_tool: object { type }` - `required` requires the model to call one or more of the allowed tools. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"auto"` + - `type: "computer"` - - `"required"` + The type of the computer tool. Always `computer`. - - `tools: array of map[unknown]` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - A list of tool definitions that the model should be allowed to call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - For the Responses API, the list of tool definitions might look like: + - `display_height: number` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The height of the computer display. - - `type: "allowed_tools"` + - `display_width: number` - Allowed tool configuration type. Always `allowed_tools`. + The width of the computer display. - - `beta_tool_choice_types: object { type }` + - `environment: "windows" or "mac" or "linux" or 2 more` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + The type of computer environment to control. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `"windows"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"mac"` - Allowed values are: + - `"linux"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"ubuntu"` - - `"file_search"` + - `"browser"` - - `"web_search_preview"` + - `type: "computer_use_preview"` - - `"computer"` + The type of the computer use tool. Always `computer_use_preview`. - - `"computer_use_preview"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `"computer_use"` + 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). - - `"web_search_preview_2025_03_11"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"image_generation"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"code_interpreter"` + - `"web_search"` - - `beta_tool_choice_function: object { name, type }` + - `"web_search_2025_08_26"` - Use this option to force the model to call a specific function. + - `filters: optional object { allowed_domains }` - - `name: string` + Filters for the search. - The name of the function to call. + - `allowed_domains: optional array of string` - - `type: "function"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - For function calling, the type is always `function`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `beta_tool_choice_mcp: object { server_label, type, name }` + - `search_context_size: optional "low" or "medium" or "high"` - Use this option to force the model to call a specific tool on a remote MCP server. + 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. - - `server_label: string` + - `"low"` - The label of the MCP server to use. + - `"medium"` - - `type: "mcp"` + - `"high"` - For MCP tools, the type is always `mcp`. + - `user_location: optional object { city, country, region, 2 more }` - - `name: optional string` + The approximate location of the user. - The name of the tool to call on the server. + - `city: optional string` - - `beta_tool_choice_custom: object { name, type }` + Free text input for the city of the user, e.g. `San Francisco`. - Use this option to force the model to call a specific custom tool. + - `country: optional string` - - `name: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The name of the custom tool to call. + - `region: optional string` - - `type: "custom"` + Free text input for the region of the user, e.g. `California`. - For custom tool calling, the type is always `custom`. + - `timezone: optional string` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `beta_tool_choice_apply_patch: object { type }` + - `type: optional "approximate"` - Forces the model to call the apply_patch tool when executing a tool call. + The type of location approximation. Always `approximate`. - - `type: "apply_patch"` + - `"approximate"` - The tool to call. Always `apply_patch`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `beta_tool_choice_shell: object { type }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Forces the model to call the shell tool when a tool call is required. + - `server_label: string` - - `type: "shell"` + A label for this MCP server, used to identify it in tool calls. - The tool to call. Always `shell`. + - `type: "mcp"` - - `tools: array of BetaTool` + The type of the MCP tool. Always `mcp`. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `allowed_callers: optional array of "direct" or "programmatic"` - We support the following categories of tools: + The tool invocation context(s). - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `"direct"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `"programmatic"` - 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). + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + List of allowed tool names or a filter object. - 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). + - `MCP allowed tools: array of string` - - `beta_computer_tool: object { type }` + A string array of allowed tool names - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `MCP tool filter: object { read_only, tool_names }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + A filter object to specify which tools are allowed. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `read_only: optional boolean` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + 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. - 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). + - `tool_names: optional array of string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + List of allowed tool names. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `authorization: optional string` - - `code_interpreter: object { container, type, allowed_callers }` + 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. - A tool that runs Python code to help generate a response to a prompt. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `programmatic_tool_calling: object { type }` + 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). - - `image_generation: object { type, action, background, 9 more }` + Currently supported `connector_id` values are: - A tool that generates images using the GPT image models. + - 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` - - `local_shell: object { type }` + - `"connector_dropbox"` - A tool that allows the model to execute shell commands in a local environment. + - `"connector_gmail"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `"connector_googlecalendar"` - A tool that allows the model to execute shell commands. + - `"connector_googledrive"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `"connector_microsoftteams"` - 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) + - `"connector_outlookcalendar"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `"connector_outlookemail"` - Groups function/custom tools under a shared namespace. + - `"connector_sharepoint"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `defer_loading: optional boolean` - Hosted or BYOT tool search configuration for deferred tools. + Whether this MCP tool is deferred and discovered via tool search. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `headers: optional map[string]` - 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). + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `require_approval: optional object { always, never } or "always" or "never"` - Allows the assistant to create, delete, or update files using unified diffs. + Specify which of the MCP server's tools require approval. - - `top_p: number` + - `MCP tool approval filter: object { always, never }` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - We generally recommend altering this or `temperature` but not both. + - `always: optional object { read_only, tool_names }` - - `background: optional boolean` + A filter object to specify which tools are allowed. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `read_only: optional boolean` - - `completed_at: optional number` + 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. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `tool_names: optional array of string` - - `conversation: optional object { id }` + List of allowed tool names. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `never: optional object { read_only, tool_names }` - - `id: string` + A filter object to specify which tools are allowed. - The unique ID of the conversation that this response was associated with. + - `read_only: optional boolean` - - `max_output_tokens: optional number` + 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. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `tool_names: optional array of string` - - `max_tool_calls: optional number` + List of allowed tool names. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `MCP tool approval setting: "always" or "never"` - - `moderation: optional object { input, output }` + 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. - Moderation results for the response input and output, if moderated completions were requested. + - `"always"` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"never"` - Moderation for the response input. + - `server_description: optional string` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + Optional description of the MCP server, used to provide more context. - A moderation result produced for the response input or output. + - `server_url: optional string` - - `categories: map[boolean]` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `tunnel_id: optional string` - - `category_applied_input_types: map[array of "text" or "image"]` + 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. - Which modalities of input are reflected by the score for each category. + - `code_interpreter: object { container, type, allowed_callers }` - - `"text"` + A tool that runs Python code to help generate a response to a prompt. - - `"image"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `category_scores: map[number]` + 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. - A dictionary of moderation categories to scores. + - `union_member_0: string` - - `flagged: boolean` + The container ID. - A boolean indicating whether the content was flagged by any category. + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `model: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The moderation model that produced this result. + - `type: "auto"` - - `type: "moderation_result"` + Always `auto`. - The object type, which was always `moderation_result` for successful moderation results. + - `file_ids: optional array of string` - - `error: object { code, message, type }` + An optional list of uploaded files to make available to your code. - An error produced while attempting moderation for the response input or output. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `code: string` + The memory limit for the code interpreter container. - The error code. + - `"1g"` - - `message: string` + - `"4g"` - The error message. + - `"16g"` - - `type: "error"` + - `"64g"` - The object type, which was always `error` for moderation failures. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + Network access policy for the container. - Moderation for the response output. + - `beta_container_network_policy_disabled: object { type }` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `type: "disabled"` - A moderation result produced for the response input or output. + Disable outbound network access. Always `disabled`. - - `categories: map[boolean]` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `allowed_domains: array of string` - - `category_applied_input_types: map[array of "text" or "image"]` + A list of allowed domains when type is `allowlist`. - Which modalities of input are reflected by the score for each category. + - `type: "allowlist"` - - `"text"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"image"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `category_scores: map[number]` + Optional domain-scoped secrets for allowlisted domains. - A dictionary of moderation categories to scores. + - `domain: string` - - `flagged: boolean` + The domain associated with the secret. - A boolean indicating whether the content was flagged by any category. + - `name: string` - - `model: string` + The name of the secret to inject for the domain. - The moderation model that produced this result. + - `value: string` - - `type: "moderation_result"` + The secret value to inject for the domain. - The object type, which was always `moderation_result` for successful moderation results. + - `type: "code_interpreter"` - - `error: object { code, message, type }` + The type of the code interpreter tool. Always `code_interpreter`. - An error produced while attempting moderation for the response input or output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `code: string` + The tool invocation context(s). - The error code. + - `"direct"` - - `message: string` + - `"programmatic"` - The error message. + - `programmatic_tool_calling: object { type }` - - `type: "error"` + - `image_generation: object { type, action, background, 9 more }` - The object type, which was always `error` for moderation failures. + A tool that generates images using the GPT image models. - - `previous_response_id: optional string` + - `type: "image_generation"` - 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`. + The type of the image generation tool. Always `image_generation`. - - `prompt: optional object { id, variables, version }` + - `action: optional "generate" or "edit" or "auto"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Whether to generate a new image or edit an existing image. Default: `auto`. - - `id: string` + - `"generate"` - The unique identifier of the prompt template to use. + - `"edit"` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `"auto"` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `background: optional "transparent" or "opaque" or "auto"` - - `union_member_0: string` + 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. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + `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. - A text input to the model. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"transparent"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"opaque"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"auto"` - A file input to the model. + - `input_fidelity: optional "high" or "low"` - - `version: optional string` + 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`. - Optional version of the prompt template. + - `"high"` - - `prompt_cache_key: optional string` + - `"low"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `input_image_mask: optional object { file_id, image_url }` - - `prompt_cache_options: optional object { mode, ttl }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `file_id: optional string` - - `mode: "implicit" or "explicit"` + File ID for the mask image. - Whether implicit prompt-cache breakpoints were enabled. + - `image_url: optional string` - - `"implicit"` + Base64-encoded mask image. - - `"explicit"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `ttl: "30m"` + The image generation model to use. Default: `gpt-image-1`. - The minimum lifetime applied to each cache breakpoint. + - `"gpt-image-1"` - - `"30m"` + - `"gpt-image-1-mini"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"gpt-image-2"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"gpt-image-2-2026-04-21"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `"gpt-image-1.5"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"chatgpt-image-latest"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `moderation: optional "auto" or "low"` - - `"in_memory"` + Moderation level for the generated image. Default: `auto`. - - `"24h"` + - `"auto"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `"low"` - **gpt-5 and o-series models only** + - `output_compression: optional number` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Compression level for the output image. Default: 100. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `output_format: optional "png" or "webp" or "jpeg"` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"auto"` + - `"png"` - - `"current_turn"` + - `"webp"` - - `"all_turns"` + - `"jpeg"` - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `partial_images: optional number` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"none"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"minimal"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - `"low"` @@ -48650,648 +58882,630 @@ openai beta:responses compact \ - `"high"` - - `"xhigh"` + - `"auto"` - - `"max"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + 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`. - **Deprecated:** use `summary` instead. + - `"1024x1024"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"1024x1536"` + + - `"1536x1024"` - `"auto"` - - `"concise"` + - `local_shell: object { type }` - - `"detailed"` + A tool that allows the model to execute shell commands in a local environment. - - `mode: optional string or "standard" or "pro"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - Controls the reasoning execution mode for the request. + A tool that allows the model to execute shell commands. - When returned on a response, this is the effective execution mode. + - `type: "shell"` - - `"standard"` + The type of the shell tool. Always `shell`. - - `"pro"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `summary: optional "auto" or "concise" or "detailed"` + The tool invocation context(s). - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"direct"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"programmatic"` - - `"auto"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"concise"` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `"detailed"` + - `type: "container_auto"` - - `safety_identifier: optional string` + Automatically creates a container for this request - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `file_ids: optional array of string` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + An optional list of uploaded files to make available to your code. - Specifies the processing type used for serving the request. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The memory limit for the container. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `"1g"` - - `"auto"` + - `"4g"` - - `"default"` + - `"16g"` - - `"flex"` + - `"64g"` - - `"scale"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"priority"` + Network access policy for the container. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `beta_container_network_policy_disabled: object { type }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `"completed"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"failed"` + An optional list of skills referenced by id or inline data. - - `"in_progress"` + - `beta_skill_reference: object { skill_id, type, version }` - - `"cancelled"` + - `skill_id: string` - - `"queued"` + The ID of the referenced skill. - - `"incomplete"` + - `type: "skill_reference"` - - `text: optional object { format, verbosity }` + References a skill created with the /v1/skills endpoint. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `version: optional string` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `beta_inline_skill: object { description, name, source, type }` - An object specifying the format that the model must output. + - `description: string` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The description of the skill. - The default format is `{ "type": "text" }` with no additional options. + - `name: string` - **Not recommended for gpt-4o and newer models:** + The name of the skill. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `source: object { data, media_type, type }` - - `text: object { type }` + Inline skill payload - Default response format. Used to generate text responses. + - `data: string` - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + Base64-encoded skill zip bundle. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `media_type: "application/zip"` - - `name: string` + The media type of the inline skill payload. Must be `application/zip`. + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `type: "inline"` + + Defines an inline skill for this request. + + - `beta_local_environment: object { type, skills }` + + - `type: "local"` + + Use a local computer environment. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `skills: optional array of BetaLocalSkill` - - `schema: map[unknown]` + An optional list of skills. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `description: string` - - `type: "json_schema"` + The description of the skill. - The type of response format being defined. Always `json_schema`. + - `name: string` - - `description: optional string` + The name of the skill. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `path: string` - - `strict: optional boolean` + The path to the directory containing the skill. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `beta_container_reference: object { container_id, type }` - - `json_object: object { type }` + - `container_id: string` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The ID of the referenced container. - - `verbosity: optional "low" or "medium" or "high"` + - `type: "container_reference"` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + References a container created with the /v1/containers endpoint - - `"low"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"medium"` + 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) - - `"high"` + - `name: string` - - `top_logprobs: optional number` + The name of the custom tool, used to identify it in tool calls. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `type: "custom"` - - `truncation: optional "auto" or "disabled"` + The type of the custom tool. Always `custom`. - The truncation strategy to use for the model response. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The tool invocation context(s). - - `"auto"` + - `"direct"` - - `"disabled"` + - `"programmatic"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `defer_loading: optional boolean` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + Whether this tool should be deferred and discovered via tool search. - - `input_tokens: number` + - `description: optional string` - The number of input tokens. + Optional description of the custom tool, used to provide more context. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `format: optional object { type } or object { definition, syntax, type }` - A detailed breakdown of the input tokens. + The input format for the custom tool. Default is unconstrained text. - - `cache_write_tokens: number` + - `text: object { type }` - The number of input tokens that were written to the cache. + Unconstrained free-form text. - - `cached_tokens: number` + - `grammar: object { definition, syntax, type }` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + A grammar defined by the user. - - `output_tokens: number` + - `definition: string` - The number of output tokens. + The grammar definition. - - `output_tokens_details: object { reasoning_tokens }` + - `syntax: "lark" or "regex"` - A detailed breakdown of the output tokens. + The syntax of the grammar definition. One of `lark` or `regex`. - - `reasoning_tokens: number` + - `"lark"` - The number of reasoning tokens. + - `"regex"` - - `total_tokens: number` + - `type: "grammar"` - The total number of tokens used. + Grammar format. Always `grammar`. - - `user: optional string` + - `beta_namespace_tool: object { description, name, tools, type }` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Groups function/custom tools under a shared namespace. -### Beta Response Apply Patch Tool Call + - `description: string` -- `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + A description of the namespace shown to the model. - A tool call that applies file diffs by creating, deleting, or updating files. + - `name: string` - - `id: string` + The namespace name used in tool calls (for example, `crm`). - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `call_id: string` + The function/custom tools available inside this namespace. - The unique ID of the apply patch tool call generated by the model. + - `function: object { name, type, allowed_callers, 5 more }` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `name: string` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `type: "function"` - - `create_file: object { diff, path, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Instruction describing how to create a file via the apply_patch tool. + The tool invocation context(s). - - `diff: string` + - `"direct"` - Diff to apply. + - `"programmatic"` - - `path: string` + - `defer_loading: optional boolean` - Path of the file to create. + Whether this function should be deferred and discovered via tool search. - - `type: "create_file"` + - `description: optional string` - Create a new file with the provided diff. + - `output_schema: optional map[unknown]` - - `delete_file: object { path, type }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Instruction describing how to delete a file via the apply_patch tool. + - `parameters: optional unknown` - - `path: string` + - `strict: optional boolean` - Path of the file to delete. + 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. - - `type: "delete_file"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Delete the specified file. + 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) - - `update_file: object { diff, path, type }` + - `name: string` - Instruction describing how to update a file via the apply_patch tool. + The name of the custom tool, used to identify it in tool calls. - - `diff: string` + - `type: "custom"` - Diff to apply. + The type of the custom tool. Always `custom`. - - `path: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Path of the file to update. + The tool invocation context(s). - - `type: "update_file"` + - `defer_loading: optional boolean` - Update an existing file with the provided diff. + Whether this tool should be deferred and discovered via tool search. - - `status: "in_progress" or "completed"` + - `description: optional string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Optional description of the custom tool, used to provide more context. - - `"in_progress"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"completed"` + The input format for the custom tool. Default is unconstrained text. - - `type: "apply_patch_call"` + - `type: "namespace"` - The type of the item. Always `apply_patch_call`. + The type of the tool. Always `namespace`. - - `agent: optional object { agent_name }` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The agent that produced this item. + Hosted or BYOT tool search configuration for deferred tools. - - `agent_name: string` + - `type: "tool_search"` - The canonical name of the agent that produced this item. + The type of the tool. Always `tool_search`. - - `caller: optional object { type } or object { caller_id, type }` + - `description: optional string` - The execution context that produced this tool call. + Description shown to the model for a client-executed tool search tool. - - `direct: object { type }` + - `execution: optional "server" or "client"` - - `program: object { caller_id, type }` + Whether tool search is executed by the server or by the client. - - `caller_id: string` + - `"server"` - The call ID of the program item that produced this tool call. + - `"client"` - - `type: "program"` + - `parameters: optional unknown` - - `created_by: optional string` + Parameter schema for a client-executed tool search tool. - The ID of the entity that created this tool call. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` -### Beta Response Apply Patch Tool Call Output + 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). -- `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The output emitted by an apply patch tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `id: string` + - `"web_search_preview"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"web_search_preview_2025_03_11"` - - `call_id: string` + - `search_content_types: optional array of "text" or "image"` - The unique ID of the apply patch tool call generated by the model. + - `"text"` - - `status: "completed" or "failed"` + - `"image"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"completed"` + 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. - - `"failed"` + - `"low"` - - `type: "apply_patch_call_output"` + - `"medium"` - The type of the item. Always `apply_patch_call_output`. + - `"high"` - - `agent: optional object { agent_name }` + - `user_location: optional object { type, city, country, 2 more }` - The agent that produced this item. + The user's location. - - `agent_name: string` + - `type: "approximate"` - The canonical name of the agent that produced this item. + The type of location approximation. Always `approximate`. - - `caller: optional object { type } or object { caller_id, type }` + - `city: optional string` - The execution context that produced this tool call. + Free text input for the city of the user, e.g. `San Francisco`. - - `direct: object { type }` + - `country: optional string` - - `program: object { caller_id, type }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `caller_id: string` + - `region: optional string` - The call ID of the program item that produced this tool call. + Free text input for the region of the user, e.g. `California`. - - `type: "program"` + - `timezone: optional string` - - `created_by: optional string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The ID of the entity that created this tool call output. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `output: optional string` + Allows the assistant to create, delete, or update files using unified diffs. - Optional textual output returned by the apply patch tool. + - `type: "apply_patch"` -### Beta Response Audio Delta Event + The type of the tool. Always `apply_patch`. -- `beta_response_audio_delta_event: object { delta, sequence_number, type, agent }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Emitted when there is a partial audio response. + The tool invocation context(s). - - `delta: string` + - `"direct"` - A chunk of Base64 encoded response audio bytes. + - `"programmatic"` - - `sequence_number: number` + - `type: "tool_search_output"` - A sequence number for this chunk of the stream response. + The item type. Always `tool_search_output`. - - `type: "response.audio.delta"` + - `id: optional string` - The type of the event. Always `response.audio.delta`. + The unique ID of this tool search output. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Audio Done Event + - `call_id: optional string` -- `beta_response_audio_done_event: object { sequence_number, type, agent }` + The unique ID of the tool search call generated by the model. - Emitted when the audio response is complete. + - `execution: optional "server" or "client"` - - `sequence_number: number` + Whether tool search was executed by the server or by the client. - The sequence number of the delta. + - `"server"` - - `type: "response.audio.done"` + - `"client"` - The type of the event. Always `response.audio.done`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of the tool search output. - The agent that owns this multi-agent streaming event. + - `"in_progress"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` -### Beta Response Audio Transcript Delta Event + - `additional_tools: object { role, tools, type, 2 more }` -- `beta_response_audio_transcript_delta_event: object { delta, sequence_number, type, agent }` + - `role: "developer"` - Emitted when there is a partial transcript of audio. + The role that provided the additional tools. Only `developer` is supported. - - `delta: string` + - `tools: array of BetaTool` - The partial transcript of the audio response. + A list of additional tools made available at this item. - - `sequence_number: number` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The sequence number of this event. + 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). - - `type: "response.audio.transcript.delta"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The type of the event. Always `response.audio.transcript.delta`. + 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). - - `agent: optional object { agent_name }` + - `beta_computer_tool: object { type }` - The agent that owns this multi-agent streaming event. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent_name: string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -### Beta Response Audio Transcript Done Event + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` -- `beta_response_audio_transcript_done_event: object { sequence_number, type, agent }` + 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). - Emitted when the full audio transcript is completed. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `sequence_number: number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The sequence number of this event. + - `code_interpreter: object { container, type, allowed_callers }` - - `type: "response.audio.transcript.done"` + A tool that runs Python code to help generate a response to a prompt. - The type of the event. Always `response.audio.transcript.done`. + - `programmatic_tool_calling: object { type }` - - `agent: optional object { agent_name }` + - `image_generation: object { type, action, background, 9 more }` - The agent that owns this multi-agent streaming event. + A tool that generates images using the GPT image models. - - `agent_name: string` + - `local_shell: object { type }` - The canonical name of the agent that produced this item. + A tool that allows the model to execute shell commands in a local environment. -### Beta Response Code Interpreter Call Code Delta Event + - `beta_function_shell_tool: object { type, allowed_callers, environment }` -- `beta_response_code_interpreter_call_code_delta_event: object { delta, item_id, output_index, 3 more }` + A tool that allows the model to execute shell commands. - Emitted when a partial code snippet is streamed by the code interpreter. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `delta: string` + 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) - The partial code snippet being streamed by the code interpreter. + - `beta_namespace_tool: object { description, name, tools, type }` - - `item_id: string` + Groups function/custom tools under a shared namespace. - The unique identifier of the code interpreter tool call item. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `output_index: number` + Hosted or BYOT tool search configuration for deferred tools. - The index of the output item in the response for which the code is being streamed. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `sequence_number: number` + 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). - The sequence number of this event, used to order streaming events. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `type: "response.code_interpreter_call_code.delta"` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Code Interpreter Call Code Done Event - -- `beta_response_code_interpreter_call_code_done_event: object { code, item_id, output_index, 3 more }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - Emitted when the code snippet is finalized by the code interpreter. + 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). - - `code: string` + - `id: string` - The final code snippet output by the code interpreter. + The unique identifier of the reasoning content. - - `item_id: string` + - `summary: array of object { text, type }` - The unique identifier of the code interpreter tool call item. + Reasoning summary content. - - `output_index: number` + - `text: string` - The index of the output item in the response for which the code is finalized. + A summary of the reasoning output from the model so far. - - `sequence_number: number` + - `type: "summary_text"` - The sequence number of this event, used to order streaming events. + The type of the object. Always `summary_text`. - - `type: "response.code_interpreter_call_code.done"` + - `type: "reasoning"` - The type of the event. Always `response.code_interpreter_call_code.done`. + The type of the object. Always `reasoning`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Code Interpreter Call Completed Event - -- `beta_response_code_interpreter_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - Emitted when the code interpreter call is completed. - - - `item_id: string` - - The unique identifier of the code interpreter tool call item. - - - `output_index: number` + - `content: optional array of object { text, type }` - The index of the output item in the response for which the code interpreter call is completed. + Reasoning text content. - - `sequence_number: number` + - `text: string` - The sequence number of this event, used to order streaming events. + The reasoning text from the model. - - `type: "response.code_interpreter_call.completed"` + - `type: "reasoning_text"` - The type of the event. Always `response.code_interpreter_call.completed`. + The type of the reasoning text. Always `reasoning_text`. - - `agent: optional object { agent_name }` + - `encrypted_content: optional string` - The agent that owns this multi-agent streaming event. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `agent_name: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -### Beta Response Code Interpreter Call In Progress Event + - `"in_progress"` -- `beta_response_code_interpreter_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + - `"completed"` - Emitted when a code interpreter call is in progress. + - `"incomplete"` - - `item_id: string` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - The unique identifier of the code interpreter tool call item. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `output_index: number` + - `encrypted_content: string` - The index of the output item in the response for which the code interpreter call is in progress. + The encrypted content of the compaction summary. - - `sequence_number: number` + - `type: "compaction"` - The sequence number of this event, used to order streaming events. + The type of the item. Always `compaction`. - - `type: "response.code_interpreter_call.in_progress"` + - `id: optional string` - The type of the event. Always `response.code_interpreter_call.in_progress`. + The ID of the compaction item. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Code Interpreter Call Interpreting Event + - `image_generation_call: object { id, result, status, 2 more }` -- `beta_response_code_interpreter_call_interpreting_event: object { item_id, output_index, sequence_number, 2 more }` + An image generation request made by the model. - Emitted when the code interpreter is actively interpreting the code snippet. + - `id: string` - - `item_id: string` + The unique ID of the image generation call. - The unique identifier of the code interpreter tool call item. + - `result: string` - - `output_index: number` + The generated image encoded in base64. - The index of the output item in the response for which the code interpreter is interpreting code. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `sequence_number: number` + The status of the image generation call. - The sequence number of this event, used to order streaming events. + - `"in_progress"` - - `type: "response.code_interpreter_call.interpreting"` + - `"completed"` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Code Interpreter Tool Call - -- `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` A tool call to run code. @@ -49362,23 +59576,83 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Compaction Item + - `local_shell_call: object { id, action, call_id, 3 more }` -- `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + A tool call to run a command on the local shell. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. - `id: string` - The unique ID of the compaction item. + The unique ID of the local shell tool call generated by the model. - - `encrypted_content: string` + - `output: string` - The encrypted content that was produced by compaction. + A JSON string of the output of the local shell tool call. - - `type: "compaction"` + - `type: "local_shell_call_output"` - The type of the item. Always `compaction`. + The type of the local shell tool call output. Always `local_shell_call_output`. - `agent: optional object { agent_name }` @@ -49388,27 +59662,47 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The identifier of the actor that created the item. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. -### Beta Response Compaction Item Param + - `"in_progress"` -- `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `"completed"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"incomplete"` - - `encrypted_content: string` + - `shell_call: object { action, call_id, type, 5 more }` - The encrypted content of the compaction summary. + A tool representing a request to execute one or more shell commands. - - `type: "compaction"` + - `action: object { commands, max_output_length, timeout_ms }` - The type of the item. Always `compaction`. + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. - `id: optional string` - The ID of the compaction item. + The unique ID of the shell tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -49418,283 +59712,309 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Completed Event + - `caller: optional object { type } or object { caller_id, type }` -- `beta_response_completed_event: object { response, sequence_number, type, agent }` + The execution context that produced this tool call. - Emitted when the model response is complete. + - `direct: object { type }` - - `response: object { id, created_at, error, 31 more }` + - `program: object { caller_id, type }` - Properties of the completed response. + - `caller_id: string` - - `id: string` + The call ID of the program item that produced this tool call. - Unique identifier for this Response. + - `type: "program"` - - `created_at: number` + The caller type. Always `program`. - Unix timestamp (in seconds) of when this Response was created. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `error: object { code, message }` + The environment to execute the shell commands in. - An error object returned when the model fails to generate a Response. + - `beta_local_environment: object { type, skills }` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `beta_container_reference: object { container_id, type }` - The error code for the response. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"server_error"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"rate_limit_exceeded"` + - `"in_progress"` - - `"invalid_prompt"` + - `"completed"` - - `"bio_policy"` + - `"incomplete"` - - `"vector_store_timeout"` + - `shell_call_output: object { call_id, output, type, 5 more }` - - `"invalid_image"` + The streamed output items emitted by a shell tool call. - - `"invalid_image_format"` + - `call_id: string` - - `"invalid_base64_image"` + The unique ID of the shell tool call generated by the model. - - `"invalid_image_url"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `"image_too_large"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `"image_too_small"` + - `outcome: object { type } or object { exit_code, type }` - - `"image_parse_error"` + The exit or timeout outcome associated with this shell call. - - `"image_content_policy_violation"` + - `timeout: object { type }` - - `"invalid_image_mode"` + Indicates that the shell call exceeded its configured time limit. - - `"image_file_too_large"` + - `exit: object { exit_code, type }` - - `"unsupported_image_media_type"` + Indicates that the shell commands finished and returned an exit code. - - `"empty_image_file"` + - `exit_code: number` - - `"failed_to_download_image"` + The exit code returned by the shell process. - - `"image_file_not_found"` + - `type: "exit"` - - `message: string` + The outcome type. Always `exit`. - A human-readable description of the error. + - `stderr: string` - - `incomplete_details: object { reason }` + Captured stderr output for the shell call. - Details about why the response is incomplete. + - `stdout: string` - - `reason: optional "max_output_tokens" or "content_filter"` + Captured stdout output for the shell call. - The reason why the response is incomplete. + - `type: "shell_call_output"` - - `"max_output_tokens"` + The type of the item. Always `shell_call_output`. - - `"content_filter"` + - `id: optional string` - - `instructions: string or array of BetaResponseInputItem` + The unique ID of the shell tool call output. Populated when this item is returned via API. - A system (or developer) message inserted into the model's context. + - `agent: optional object { agent_name }` - When using 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. + The agent that produced this item. - - `union_member_0: string` + - `agent_name: string` - A text input to the model, equivalent to a text input with the - `developer` role. + The canonical name of the agent that produced this item. - - `Input item list: array of BetaResponseInputItem` + - `caller: optional object { type } or object { caller_id, type }` - A list of one or many input items to the model, containing - different content types. + The execution context that produced this tool call. - - `beta_easy_input_message: object { content, role, phase, type }` + - `direct: object { type }` - 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. + - `program: object { caller_id, type }` - - `content: string or BetaResponseInputMessageContentList` + - `caller_id: string` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The call ID of the program item that produced this tool call. - - `Text input: string` + - `type: "program"` - A text input to the model. + The caller type. Always `program`. - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `max_output_length: optional number` - A list of one or many input items to the model, containing different content - types. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A text input to the model. + The status of the shell call output. - - `text: string` + - `"in_progress"` - The text input to the model. + - `"completed"` - - `type: "input_text"` + - `"incomplete"` - The type of the input item. Always `input_text`. + - `apply_patch_call: object { call_id, operation, status, 4 more }` - - `prompt_cache_breakpoint: optional object { mode }` + A tool call representing a request to create, delete, or update files using diff patches. - 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. + - `call_id: string` - - `mode: "explicit"` + The unique ID of the apply patch tool call generated by the model. - The breakpoint mode. Always `explicit`. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The specific create, delete, or update instruction for the apply_patch tool call. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `create_file: object { diff, path, type }` - - `detail: "low" or "high" or "auto" or "original"` + Instruction for creating a new file via the apply_patch tool. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `diff: string` - - `"low"` + Unified diff content to apply when creating the file. - - `"high"` + - `path: string` - - `"auto"` + Path of the file to create relative to the workspace root. - - `"original"` + - `type: "create_file"` - - `type: "input_image"` + The operation type. Always `create_file`. - The type of the input item. Always `input_image`. + - `delete_file: object { path, type }` - - `file_id: optional string` + Instruction for deleting an existing file via the apply_patch tool. - The ID of the file to be sent to the model. + - `path: string` - - `image_url: optional string` + Path of the file to delete relative to the workspace root. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: "delete_file"` - - `prompt_cache_breakpoint: optional object { mode }` + The operation type. Always `delete_file`. - 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. + - `update_file: object { diff, path, type }` - - `mode: "explicit"` + Instruction for updating an existing file via the apply_patch tool. - The breakpoint mode. Always `explicit`. + - `diff: string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Unified diff content to apply to the existing file. - A file input to the model. + - `path: string` - - `type: "input_file"` + Path of the file to update relative to the workspace root. - The type of the input item. Always `input_file`. + - `type: "update_file"` - - `detail: optional "auto" or "low" or "high"` + The operation type. Always `update_file`. - 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`. + - `status: "in_progress" or "completed"` - - `"auto"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"low"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `file_data: optional string` + - `type: "apply_patch_call"` - The content of the file to be sent to the model. + The type of the item. Always `apply_patch_call`. - - `file_id: optional string` + - `id: optional string` - The ID of the file to be sent to the model. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `file_url: optional string` + - `agent: optional object { agent_name }` - The URL of the file to be sent to the model. + The agent that produced this item. - - `filename: optional string` + - `agent_name: string` - The name of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - - `mode: "explicit"` + - `direct: object { type }` - The breakpoint mode. Always `explicit`. + - `program: object { caller_id, type }` - - `role: "user" or "assistant" or "system" or "developer"` + - `caller_id: string` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The call ID of the program item that produced this tool call. - - `"user"` + - `type: "program"` - - `"assistant"` + The caller type. Always `program`. - - `"system"` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - - `"developer"` + The streamed output emitted by an apply patch tool call. - - `phase: optional "commentary"` + - `call_id: string` - 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. + The unique ID of the apply patch tool call generated by the model. - - `"commentary"` + - `status: "completed" or "failed"` - - `type: optional "message"` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the message input. Always `message`. + - `"completed"` - - `"message"` + - `"failed"` - - `message: object { content, role, agent, 2 more }` + - `type: "apply_patch_call_output"` - 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. + The type of the item. Always `apply_patch_call_output`. - - `content: array of BetaResponseInputContent` + - `id: optional string` - A list of one or many input items to the model, containing different content - types. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `agent: optional object { agent_name }` - A text input to the model. + The agent that produced this item. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `agent_name: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - A file input to the model. + The execution context that produced this tool call. - - `role: "user" or "system" or "developer"` + - `direct: object { type }` - The role of the message input. One of `user`, `system`, or `developer`. + - `program: object { caller_id, type }` - - `"user"` + - `caller_id: string` - - `"system"` + The call ID of the program item that produced this tool call. - - `"developer"` + - `type: "program"` + + The caller type. Always `program`. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. - `agent: optional object { agent_name }` @@ -49704,233 +60024,233 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `error: optional string` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Error message if the server could not list tools. - - `"in_progress"` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `"completed"` + A request for human approval of a tool invocation. - - `"incomplete"` + - `id: string` - - `type: optional "message"` + The unique ID of the approval request. - The type of the message input. Always set to `message`. + - `arguments: string` - - `"message"` + A JSON string of arguments for the tool. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `name: string` - An output message from the model. + The name of the tool to run. - - `id: string` + - `server_label: string` - The unique ID of the output message. + The label of the MCP server making the request. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `type: "mcp_approval_request"` - The content of the output message. + The type of the item. Always `mcp_approval_request`. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `agent: optional object { agent_name }` - A text output from the model. + The agent that produced this item. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `agent_name: string` - The annotations of the text output. + The canonical name of the agent that produced this item. - - `file_citation: object { file_id, filename, index, type }` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - A citation to a file. + A response to an MCP approval request. - - `file_id: string` + - `approval_request_id: string` - The ID of the file. + The ID of the approval request being answered. - - `filename: string` + - `approve: boolean` - The filename of the file cited. + Whether the request was approved. - - `index: number` + - `type: "mcp_approval_response"` - The index of the file in the list of files. + The type of the item. Always `mcp_approval_response`. - - `type: "file_citation"` + - `id: optional string` - The type of the file citation. Always `file_citation`. + The unique ID of the approval response - - `url_citation: object { end_index, start_index, title, 2 more }` + - `agent: optional object { agent_name }` - A citation for a web resource used to generate a model response. + The agent that produced this item. - - `end_index: number` + - `agent_name: string` - The index of the last character of the URL citation in the message. + The canonical name of the agent that produced this item. - - `start_index: number` + - `reason: optional string` - The index of the first character of the URL citation in the message. + Optional reason for the decision. - - `title: string` + - `mcp_call: object { id, arguments, name, 7 more }` - The title of the web resource. + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. - - `type: "url_citation"` + - `arguments: string` - The type of the URL citation. Always `url_citation`. + A JSON string of the arguments passed to the tool. - - `url: string` + - `name: string` - The URL of the web resource. + The name of the tool that was run. - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `server_label: string` - A citation for a container file used to generate a model response. + The label of the MCP server running the tool. - - `container_id: string` + - `type: "mcp_call"` - The ID of the container file. + The type of the item. Always `mcp_call`. - - `end_index: number` + - `agent: optional object { agent_name }` - The index of the last character of the container file citation in the message. + The agent that produced this item. - - `file_id: string` + - `agent_name: string` - The ID of the file. + The canonical name of the agent that produced this item. - - `filename: string` + - `approval_request_id: optional string` - The filename of the container file cited. + 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. - - `start_index: number` + - `error: optional string` - The index of the first character of the container file citation in the message. + The error from the tool call, if any. - - `type: "container_file_citation"` + - `output: optional string` - The type of the container file citation. Always `container_file_citation`. + The output from the tool call. - - `file_path: object { file_id, index, type }` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - A path to a file. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `file_id: string` + - `"in_progress"` - The ID of the file. + - `"completed"` - - `index: number` + - `"incomplete"` - The index of the file in the list of files. + - `"calling"` - - `type: "file_path"` + - `"failed"` - The type of the file path. Always `file_path`. + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `text: string` + The output of a custom tool call from your code, being sent back to the model. - The text output from the model. + - `call_id: string` - - `type: "output_text"` + The call ID, used to map this custom tool call output to a custom tool call. - The type of the output text. Always `output_text`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `token: string` + - `string output: string` - - `bytes: array of number` + A string of the output of the custom tool call. - - `logprob: number` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `top_logprobs: array of object { token, bytes, logprob }` + Text, image, or file output of the custom tool call. - - `token: string` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `bytes: array of number` + A text input to the model. - - `logprob: number` + - `text: string` - - `beta_response_output_refusal: object { refusal, type }` + The text input to the model. - A refusal from the model. + - `type: "input_text"` - - `refusal: string` + The type of the input item. Always `input_text`. - The refusal explanation from the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "refusal"` + 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. - The type of the refusal. Always `refusal`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `role: "assistant"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The role of the output message. Always `assistant`. + - `detail: "low" or "high" or "auto" or "original"` - - `status: "in_progress" or "completed" or "incomplete"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "input_image"` - - `"in_progress"` + The type of the input item. Always `input_image`. - - `"completed"` + - `file_id: optional string` - - `"incomplete"` + The ID of the file to be sent to the model. - - `type: "message"` + - `image_url: optional string` - The type of the output message. Always `message`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent: optional object { agent_name }` + - `prompt_cache_breakpoint: optional object { mode }` - The agent that produced this item. + 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. - - `agent_name: string` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The canonical name of the agent that produced this item. + A file input to the model. - - `phase: optional "commentary"` + - `type: "input_file"` - 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. + The type of the input item. Always `input_file`. - - `"commentary"` + - `detail: optional "auto" or "low" or "high"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + 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`. - 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. + - `file_data: optional string` - - `id: string` + The content of the file to be sent to the model. - The unique ID of the file search tool call. + - `file_id: optional string` - - `queries: array of string` + The ID of the file to be sent to the model. - The queries used to search for files. + - `file_url: optional string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The URL of the file to be sent to the model. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `filename: optional string` - - `"in_progress"` + The name of the file to be sent to the model. - - `"searching"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"completed"` + 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. - - `"incomplete"` + - `type: "custom_tool_call_output"` - - `"failed"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `type: "file_search_call"` + - `id: optional string` - The type of the file search tool call. Always `file_search_call`. + The unique ID of the custom tool call output in the OpenAI platform. - `agent: optional object { agent_name }` @@ -49940,464 +60260,459 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. - - - `attributes: optional map[string or number or boolean]` - - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `union_member_0: string` + The execution context that produced this tool call. - - `union_member_1: number` + - `direct: object { type }` - - `union_member_2: boolean` + - `program: object { caller_id, type }` - - `file_id: optional string` + - `caller_id: string` - The unique ID of the file. + The call ID of the program item that produced this tool call. - - `filename: optional string` + - `type: "program"` - The name of the file. + The caller type. Always `program`. - - `score: optional number` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - The relevance score of the file - a value between 0 and 1. + A call to a custom tool created by the model. - - `text: optional string` + - `call_id: string` - The text that was retrieved from the file. + An identifier used to map this custom tool call to a tool call output. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `input: string` - 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. + The input for the custom tool call generated by the model. - - `id: string` + - `name: string` - The unique ID of the computer call. + The name of the custom tool being called. - - `call_id: string` + - `type: "custom_tool_call"` - An identifier used when responding to the tool call with output. + The type of the custom tool call. Always `custom_tool_call`. - - `pending_safety_checks: array of object { id, code, message }` + - `id: optional string` - The pending safety checks for the computer call. + The unique ID of the custom tool call in the OpenAI platform. - - `id: string` + - `agent: optional object { agent_name }` - The ID of the pending safety check. + The agent that produced this item. - - `code: optional string` + - `agent_name: string` - The type of the pending safety check. + The canonical name of the agent that produced this item. - - `message: optional string` + - `caller: optional object { type } or object { caller_id, type }` - Details about the pending safety check. + The execution context that produced this tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `direct: object { type }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `program: object { caller_id, type }` - - `"in_progress"` + - `caller_id: string` - - `"completed"` + The call ID of the program item that produced this tool call. - - `"incomplete"` + - `type: "program"` - - `type: "computer_call"` + - `namespace: optional string` - The type of the computer call. Always `computer_call`. + The namespace of the custom tool being called. - - `"computer_call"` + - `compaction_trigger: object { type, agent }` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + Compacts the current context. Must be the final input item. - A click action. + - `type: "compaction_trigger"` - - `click: object { button, type, x, 2 more }` + The type of the item. Always `compaction_trigger`. - A click action. + - `agent: optional object { agent_name }` - - `button: "left" or "right" or "wheel" or 2 more` + The agent that produced this item. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `agent_name: string` - - `"left"` + The canonical name of the agent that produced this item. - - `"right"` + - `item_reference: object { id, agent, type }` - - `"wheel"` + An internal identifier for an item to reference. - - `"back"` + - `id: string` - - `"forward"` + The ID of the item to reference. - - `type: "click"` + - `agent: optional object { agent_name }` - Specifies the event type. For a click action, this property is always `click`. + The agent that produced this item. - - `x: number` + - `agent_name: string` - The x-coordinate where the click occurred. + The canonical name of the agent that produced this item. - - `y: number` + - `type: optional "item_reference"` - The y-coordinate where the click occurred. + The type of item to reference. Always `item_reference`. - - `keys: optional array of string` + - `"item_reference"` - The keys being held while clicking. + - `program: object { id, call_id, code, 3 more }` - - `double_click: object { keys, type, x, y }` + - `id: string` - A double click action. + The unique ID of this program item. - - `keys: array of string` + - `call_id: string` - The keys being held while double-clicking. + The stable call ID of the program item. - - `type: "double_click"` + - `code: string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The JavaScript source executed by programmatic tool calling. - - `x: number` + - `fingerprint: string` - The x-coordinate where the double click occurred. + Opaque program replay fingerprint that must be round-tripped. - - `y: number` + - `type: "program"` - The y-coordinate where the double click occurred. + The item type. Always `program`. - - `drag: object { path, type, keys }` + - `agent: optional object { agent_name }` - A drag action. + The agent that produced this item. - - `path: array of object { x, y }` + - `agent_name: string` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The canonical name of the agent that produced this item. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `program_output: object { id, call_id, result, 3 more }` - - `x: number` + - `id: string` - The x-coordinate. + The unique ID of this program output item. - - `y: number` + - `call_id: string` - The y-coordinate. + The call ID of the program item. - - `type: "drag"` + - `result: string` - Specifies the event type. For a drag action, this property is always set to `drag`. + The result produced by the program item. - - `keys: optional array of string` + - `status: "completed" or "incomplete"` - The keys being held while dragging the mouse. + The terminal status of the program output. - - `keypress: object { keys, type }` + - `"completed"` - A collection of keypresses the model would like to perform. + - `"incomplete"` - - `keys: array of string` + - `type: "program_output"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The item type. Always `program_output`. - - `type: "keypress"` + - `agent: optional object { agent_name }` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The agent that produced this item. - - `move: object { type, x, y, keys }` + - `agent_name: string` - A mouse move action. + The canonical name of the agent that produced this item. - - `type: "move"` + - `metadata: map[string]` - Specifies the event type. For a move action, this property is always set to `move`. + 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. - - `x: number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The x-coordinate to move to. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `y: number` + Model ID used to generate the response, like `gpt-4o` 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. - The y-coordinate to move to. + - `"gpt-5.6-sol"` - - `keys: optional array of string` + - `"gpt-5.6-terra"` - The keys being held while moving the mouse. + - `"gpt-5.6-luna"` - - `screenshot: object { type }` + - `"gpt-5.4"` - A screenshot action. + - `"gpt-5.4-mini"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"gpt-5.4-nano"` - A scroll action. + - `"gpt-5.4-mini-2026-03-17"` - - `scroll_x: number` + - `"gpt-5.4-nano-2026-03-17"` - The horizontal scroll distance. + - `"gpt-5.3-chat-latest"` - - `scroll_y: number` + - `"gpt-5.2"` - The vertical scroll distance. + - `"gpt-5.2-2025-12-11"` - - `type: "scroll"` + - `"gpt-5.2-chat-latest"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"gpt-5.2-pro"` - - `x: number` + - `"gpt-5.2-pro-2025-12-11"` - The x-coordinate where the scroll occurred. + - `"gpt-5.1"` - - `y: number` + - `"gpt-5.1-2025-11-13"` - The y-coordinate where the scroll occurred. + - `"gpt-5.1-codex"` - - `keys: optional array of string` + - `"gpt-5.1-mini"` - The keys being held while scrolling. + - `"gpt-5.1-chat-latest"` - - `type: object { text, type }` + - `"gpt-5"` - An action to type in text. + - `"gpt-5-mini"` - - `text: string` + - `"gpt-5-nano"` - The text to type. + - `"gpt-5-2025-08-07"` - - `type: "type"` + - `"gpt-5-mini-2025-08-07"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"gpt-5-nano-2025-08-07"` - - `wait: object { type }` + - `"gpt-5-chat-latest"` - A wait action. + - `"gpt-4.1"` - - `actions: optional array of BetaComputerAction` + - `"gpt-4.1-mini"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"gpt-4.1-nano"` - - `click: object { button, type, x, 2 more }` + - `"gpt-4.1-2025-04-14"` - A click action. + - `"gpt-4.1-mini-2025-04-14"` - - `double_click: object { keys, type, x, y }` + - `"gpt-4.1-nano-2025-04-14"` - A double click action. + - `"o4-mini"` - - `drag: object { path, type, keys }` + - `"o4-mini-2025-04-16"` - A drag action. + - `"o3"` - - `keypress: object { keys, type }` + - `"o3-2025-04-16"` - A collection of keypresses the model would like to perform. + - `"o3-mini"` - - `move: object { type, x, y, keys }` + - `"o3-mini-2025-01-31"` - A mouse move action. + - `"o1"` - - `screenshot: object { type }` + - `"o1-2024-12-17"` - A screenshot action. + - `"o1-preview"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"o1-preview-2024-09-12"` - A scroll action. + - `"o1-mini"` - - `type: object { text, type }` + - `"o1-mini-2024-09-12"` - An action to type in text. + - `"gpt-4o"` - - `wait: object { type }` + - `"gpt-4o-2024-11-20"` - A wait action. + - `"gpt-4o-2024-08-06"` - - `agent: optional object { agent_name }` + - `"gpt-4o-2024-05-13"` - The agent that produced this item. + - `"gpt-4o-audio-preview"` - - `agent_name: string` + - `"gpt-4o-audio-preview-2024-10-01"` - The canonical name of the agent that produced this item. + - `"gpt-4o-audio-preview-2024-12-17"` - - `computer_call_output: object { call_id, output, type, 4 more }` + - `"gpt-4o-audio-preview-2025-06-03"` - The output of a computer tool call. + - `"gpt-4o-mini-audio-preview"` - - `call_id: string` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The ID of the computer tool call that produced the output. + - `"gpt-4o-search-preview"` - - `output: object { type, file_id, image_url }` + - `"gpt-4o-mini-search-preview"` - A computer screenshot image used with the computer use tool. + - `"gpt-4o-search-preview-2025-03-11"` - - `type: "computer_screenshot"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"chatgpt-4o-latest"` - - `file_id: optional string` + - `"codex-mini-latest"` - The identifier of an uploaded file that contains the screenshot. + - `"gpt-4o-mini"` - - `image_url: optional string` + - `"gpt-4o-mini-2024-07-18"` - The URL of the screenshot image. + - `"gpt-4-turbo"` - - `type: "computer_call_output"` + - `"gpt-4-turbo-2024-04-09"` - The type of the computer tool call output. Always `computer_call_output`. + - `"gpt-4-0125-preview"` - - `id: optional string` + - `"gpt-4-turbo-preview"` - The ID of the computer tool call output. + - `"gpt-4-1106-preview"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"gpt-4-vision-preview"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"gpt-4"` - - `id: string` + - `"gpt-4-0314"` - The ID of the pending safety check. + - `"gpt-4-0613"` - - `code: optional string` + - `"gpt-4-32k"` - The type of the pending safety check. + - `"gpt-4-32k-0314"` - - `message: optional string` + - `"gpt-4-32k-0613"` - Details about the pending safety check. + - `"gpt-3.5-turbo"` - - `agent: optional object { agent_name }` + - `"gpt-3.5-turbo-16k"` - The agent that produced this item. + - `"gpt-3.5-turbo-0301"` - - `agent_name: string` + - `"gpt-3.5-turbo-0613"` - The canonical name of the agent that produced this item. + - `"gpt-3.5-turbo-1106"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-3.5-turbo-0125"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"gpt-3.5-turbo-16k-0613"` - - `"in_progress"` + - `"o1-pro"` - - `"completed"` + - `"o1-pro-2025-03-19"` - - `"incomplete"` + - `"o3-pro"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `"o3-pro-2025-06-10"` - 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. + - `"o3-deep-research"` - - `id: string` + - `"o3-deep-research-2025-06-26"` - The unique ID of the web search tool call. + - `"o4-mini-deep-research"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `"o4-mini-deep-research-2025-06-26"` - 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). + - `"computer-use-preview"` - - `search: object { type, queries, query, sources }` + - `"computer-use-preview-2025-03-11"` - Action type "search" - Performs a web search query. + - `"gpt-5-codex"` - - `type: "search"` + - `"gpt-5-pro"` - The action type. + - `"gpt-5-pro-2025-10-06"` - - `queries: optional array of string` + - `"gpt-5.1-codex-max"` - The search queries. + - `object: "response"` - - `query: optional string` + The object type of this resource - always set to `response`. - The search query. + - `output: array of BetaResponseOutputItem` - - `sources: optional array of object { type, url }` + An array of content items generated by the model. - The sources used in the search. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `type: "url"` + - `beta_response_output_message: object { id, content, role, 4 more }` - The type of source. Always `url`. + An output message from the model. - - `url: string` + - `id: string` - The URL of the source. + The unique ID of the output message. - - `open_page: object { type, url }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Action type "open_page" - Opens a specific URL from search results. + The content of the output message. - - `type: "open_page"` + - `role: "assistant"` - The action type. + The role of the output message. Always `assistant`. - - `url: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The URL opened by the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `find_in_page: object { pattern, type, url }` + - `type: "message"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The type of the output message. Always `message`. - - `pattern: string` + - `agent: optional object { agent_name }` - The pattern or text to search for within the page. + The agent that produced this item. - - `type: "find_in_page"` + - `phase: optional "commentary" or "final_answer"` - The action type. + 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. - - `url: string` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The URL of the page searched for the pattern. + 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. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `id: string` - The status of the web search tool call. + The unique ID of the file search tool call. - - `"in_progress"` + - `queries: array of string` - - `"searching"` + The queries used to search for files. - - `"completed"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"failed"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: "web_search_call"` + - `type: "file_search_call"` - The type of the web search tool call. Always `web_search_call`. + The type of the file search tool call. Always `file_search_call`. - `agent: optional object { agent_name }` The agent that produced this item. - - `agent_name: string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The canonical name of the agent that produced this item. + The results of the file search tool call. - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` @@ -50428,24 +60743,10 @@ openai beta:responses compact \ The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - `namespace: optional string` The namespace of the function to run. @@ -50455,223 +60756,185 @@ openai beta:responses compact \ The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `function_call_output: object { call_id, output, type, 4 more }` + - `id: string` - The output of a function tool call. + The unique ID of the function call tool output. - `call_id: string` The unique ID of the function tool call generated by the model. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Text, image, or file output of the function tool call. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `union_member_0: string` + - `string output: string` - A JSON string of the output of the function tool call. + A string of the output of the function call. - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - An array of content outputs (text, image, file) for the function tool call. + Text, image, or file output of the function call. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: "input_image"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The type of the input item. Always `input_image`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: optional "low" or "high" or "auto" or "original"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A file input to the model. - - `"low"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"high"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"auto"` + - `"in_progress"` - - `"original"` + - `"completed"` - - `file_id: optional string` + - `"incomplete"` - The ID of the file to be sent to the model. + - `type: "function_call_output"` - - `image_url: optional string` + The type of the function tool call output. Always `function_call_output`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `agent: optional object { agent_name }` - - `prompt_cache_breakpoint: optional object { mode }` + The agent that produced this item. - 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. + - `agent_name: string` - - `mode: "explicit"` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. + - `caller: optional object { type } or object { caller_id, type }` - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + The execution context that produced this tool call. - A file input to the model. + - `direct: object { type }` - - `type: "input_file"` + - `program: object { caller_id, type }` - The type of the input item. Always `input_file`. + - `caller_id: string` - - `detail: optional "auto" or "low" or "high"` + The call ID of the program item that produced this tool call. - 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`. + - `type: "program"` - - `"auto"` + The caller type. Always `program`. - - `"low"` + - `created_by: optional string` - - `"high"` + The identifier of the actor that created the item. - - `file_data: optional string` + - `agent_message: object { id, author, content, 3 more }` - The base64-encoded data of the file to be sent to the model. + - `id: string` - - `file_id: optional string` + The unique ID of the agent message. - The ID of the file to be sent to the model. + - `author: string` - - `file_url: optional string` + The sending agent identity. - The URL of the file to be sent to the model. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `filename: optional string` + Encrypted content sent between agents. - The name of the file to be sent to the model. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `prompt_cache_breakpoint: optional object { mode }` + A text input to the model. - 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. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `mode: "explicit"` + A text output from the model. - The breakpoint mode. Always `explicit`. + - `text: object { text, type }` - - `type: "function_call_output"` + A text content. - The type of the function tool call output. Always `function_call_output`. + - `text: string` - - `id: optional string` + - `type: "text"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `summary_text: object { text, type }` - - `agent: optional object { agent_name }` + A summary text from the model. - The agent that produced this item. + - `text: string` - - `agent_name: string` + A summary of the reasoning output from the model so far. - The canonical name of the agent that produced this item. + - `type: "summary_text"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the object. Always `summary_text`. - The execution context that produced this tool call. + - `reasoning_text: object { text, type }` - - `direct: object { type }` + Reasoning text from the model. - - `program: object { caller_id, type }` + - `text: string` - - `caller_id: string` + The reasoning text from the model. - The call ID of the program item that produced this tool call. + - `type: "reasoning_text"` - - `type: "program"` + The type of the reasoning text. Always `reasoning_text`. - The caller type. Always `program`. + - `beta_response_output_refusal: object { refusal, type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A refusal from the model. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"in_progress"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"completed"` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - - `"incomplete"` + A screenshot of a computer. - - `agent_message: object { author, content, recipient, 3 more }` + - `detail: "low" or "high" or "auto" or "original"` - A message routed between agents. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `author: string` + - `"low"` - The sending agent identity. + - `"high"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `"auto"` - Plaintext, image, or encrypted content sent between agents. + - `"original"` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `file_id: string` - A text input to the model. + The identifier of an uploaded file that contains the screenshot. - - `text: string` + - `image_url: string` - The text input to the model. + The URL of the screenshot image. - - `type: "input_text"` + - `type: "computer_screenshot"` - The type of the input item. Always `input_text`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `prompt_cache_breakpoint: optional object { mode }` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `detail: optional "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` + - `mode: "explicit"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The breakpoint mode. Always `explicit`. - - `prompt_cache_breakpoint: optional object { mode }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - 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. + A file input to the model. - `encrypted_content: object { encrypted_content, type }` @@ -50691,11 +60954,7 @@ openai beta:responses compact \ - `type: "agent_message"` - The item type. Always `agent_message`. - - - `id: optional string` - - The unique ID of this agent message item. + The type of the item. Always `agent_message`. - `agent: optional object { agent_name }` @@ -50705,11 +60964,15 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` + - `multi_agent_call: object { id, action, arguments, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call item. - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The multi-agent action that was executed. + The multi-agent action to execute. - `"spawn_agent"` @@ -50725,7 +60988,7 @@ openai beta:responses compact \ - `arguments: string` - The action arguments as a JSON string. + The JSON string of arguments generated for the action. - `call_id: string` @@ -50733,11 +60996,7 @@ openai beta:responses compact \ - `type: "multi_agent_call"` - The item type. Always `multi_agent_call`. - - - `id: optional string` - - The unique ID of this multi-agent call. + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` @@ -50747,7 +61006,11 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call output item. - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` @@ -50769,117 +61032,161 @@ openai beta:responses compact \ The unique ID of the multi-agent call. - - `output: array of object { text, type, annotations }` + - `output: array of BetaResponseOutputText` Text output returned by the multi-agent action. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + - `text: string` - The text content. + The text output from the model. - `type: "output_text"` - The content type. Always `output_text`. + The type of the output text. Always `output_text`. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - Citations associated with the text content. + - `type: "multi_agent_call_output"` - - `union_member_0: array of object { file_id, filename, index, type }` + The type of the multi-agent result. Always `multi_agent_call_output`. - - `file_id: string` + - `agent: optional object { agent_name }` - The ID of the file. + The agent that produced this item. - - `filename: string` + - `agent_name: string` - The filename of the file cited. + The canonical name of the agent that produced this item. - - `index: number` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - The index of the file in the list of files. + 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. - - `type: "file_citation"` + - `id: string` - The citation type. Always `file_citation`. + The unique ID of the web search tool call. - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `end_index: number` + 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). - The index of the last character of the citation in the message. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `start_index: number` + The status of the web search tool call. - The index of the first character of the citation in the message. + - `type: "web_search_call"` - - `title: string` + The type of the web search tool call. Always `web_search_call`. - The title of the cited resource. + - `agent: optional object { agent_name }` - - `type: "url_citation"` + The agent that produced this item. - The citation type. Always `url_citation`. + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `url: string` + 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. - The URL of the cited resource. + - `id: string` - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + The unique ID of the computer call. - - `container_id: string` + - `call_id: string` - The ID of the container. + An identifier used when responding to the tool call with output. - - `end_index: number` + - `pending_safety_checks: array of object { id, code, message }` - The index of the last character of the citation in the message. + The pending safety checks for the computer call. - - `file_id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The ID of the container file. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `filename: string` + - `type: "computer_call"` - The filename of the container file cited. + The type of the computer call. Always `computer_call`. - - `start_index: number` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - The index of the first character of the citation in the message. + A click action. - - `type: "container_file_citation"` + - `actions: optional array of BetaComputerAction` - The citation type. Always `container_file_citation`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `type: "multi_agent_call_output"` + - `agent: optional object { agent_name }` - The item type. Always `multi_agent_call_output`. + The agent that produced this item. - - `id: optional string` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - The unique ID of this multi-agent call output. + - `id: string` - - `agent: optional object { agent_name }` + The unique ID of the computer call tool output. - The agent that produced this item. + - `call_id: string` - - `agent_name: string` + The ID of the computer tool call that produced the output. - The canonical name of the agent that produced this item. + - `output: object { type, file_id, image_url }` - - `tool_search_call: object { arguments, type, id, 4 more }` + A computer screenshot image used with the computer use tool. - - `arguments: unknown` + - `type: "computer_screenshot"` - The arguments supplied to the tool search call. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: "tool_search_call"` + - `file_id: optional string` - The item type. Always `tool_search_call`. + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. - - `id: optional string` + - `message: optional string` - The unique ID of this tool search call. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -50889,1071 +61196,1032 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. - - - `execution: optional "server" or "client"` - - Whether tool search was executed by the server or by the client. + - `created_by: optional string` - - `"server"` + The identifier of the actor that created the item. - - `"client"` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + 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). - The status of the tool search call. + - `id: string` - - `"in_progress"` + The unique identifier of the reasoning content. - - `"completed"` + - `summary: array of object { text, type }` - - `"incomplete"` + Reasoning summary content. - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + - `type: "reasoning"` - - `tools: array of BetaTool` + The type of the object. Always `reasoning`. - The loaded tool definitions returned by the tool search output. + - `agent: optional object { agent_name }` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The agent that produced this item. - 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). + - `content: optional array of object { text, type }` - - `name: string` + Reasoning text content. - The name of the function to call. + - `encrypted_content: optional string` - - `parameters: map[unknown]` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - A JSON schema object describing the parameters of the function. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `strict: boolean` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Whether strict parameter validation is enforced for this function tool. + - `program: object { id, call_id, code, 3 more }` - - `type: "function"` + - `id: string` - The type of the function tool. Always `function`. + The unique ID of the program item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + The stable call ID of the program item. - - `"direct"` + - `code: string` - - `"programmatic"` + The JavaScript source executed by programmatic tool calling. - - `defer_loading: optional boolean` + - `fingerprint: string` - Whether this function is deferred and loaded via tool search. + Opaque program replay fingerprint that must be round-tripped. - - `description: optional string` + - `type: "program"` - A description of the function. Used by the model to determine whether or not to call the function. + The type of the item. Always `program`. - - `output_schema: optional map[unknown]` + - `agent: optional object { agent_name }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The agent that produced this item. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `agent_name: string` - 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). + The canonical name of the agent that produced this item. - - `type: "file_search"` + - `program_output: object { id, call_id, result, 3 more }` - The type of the file search tool. Always `file_search`. + - `id: string` - - `vector_store_ids: array of string` + The unique ID of the program output item. - The IDs of the vector stores to search. + - `call_id: string` - - `filters: optional object { key, type, value } or object { filters, type }` + The call ID of the program item. - A filter to apply. + - `result: string` - - `Comparison Filter: object { key, type, value }` + The result produced by the program item. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `status: "completed" or "incomplete"` - - `key: string` + The terminal status of the program output item. - The key to compare against the value. + - `"completed"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"incomplete"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: "program_output"` - - `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 + The type of the item. Always `program_output`. - - `"eq"` + - `agent: optional object { agent_name }` - - `"ne"` + The agent that produced this item. - - `"gt"` + - `agent_name: string` - - `"gte"` + The canonical name of the agent that produced this item. - - `"lt"` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `"lte"` + - `id: string` - - `"in"` + The unique ID of the tool search call item. - - `"nin"` + - `arguments: unknown` - - `value: string or number or boolean or array of unknown` + Arguments used for the tool search call. - The value to compare against the attribute key; supports string, number, or boolean types. + - `call_id: string` - - `union_member_0: string` + The unique ID of the tool search call generated by the model. - - `union_member_1: number` + - `execution: "server" or "client"` - - `union_member_2: boolean` + Whether tool search was executed by the server or by the client. - - `union_member_3: array of unknown` + - `"server"` - - `Compound Filter: object { filters, type }` + - `"client"` - Combine multiple filters using `and` or `or`. + - `status: "in_progress" or "completed" or "incomplete"` - - `filters: array of object { key, type, value } or unknown` + The status of the tool search call item that was recorded. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"in_progress"` - - `Comparison Filter: object { key, type, value }` + - `"completed"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"incomplete"` - - `key: string` + - `type: "tool_search_call"` - The key to compare against the value. + The type of the item. Always `tool_search_call`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `agent: optional object { agent_name }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The agent that produced this item. - - `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 + - `agent_name: string` - - `"eq"` + The canonical name of the agent that produced this item. - - `"ne"` + - `created_by: optional string` - - `"gt"` + The identifier of the actor that created the item. - - `"gte"` + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `"lt"` + - `id: string` - - `"lte"` + The unique ID of the tool search output item. - - `"in"` + - `call_id: string` - - `"nin"` + The unique ID of the tool search call generated by the model. - - `value: string or number or boolean or array of unknown` + - `execution: "server" or "client"` - The value to compare against the attribute key; supports string, number, or boolean types. + Whether tool search was executed by the server or by the client. - - `union_member_0: string` + - `"server"` - - `union_member_1: number` + - `"client"` - - `union_member_2: boolean` + - `status: "in_progress" or "completed" or "incomplete"` - - `union_member_3: array of unknown` + The status of the tool search output item that was recorded. - - `union_member_1: unknown` + - `"in_progress"` - - `type: "and" or "or"` + - `"completed"` - Type of operation: `and` or `or`. + - `"incomplete"` - - `"and"` + - `tools: array of BetaTool` - - `"or"` + The loaded tool definitions returned by tool search. - - `max_num_results: optional number` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + 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). - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - Ranking options for search. + 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). - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `beta_computer_tool: object { type }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `embedding_weight: number` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The weight of the embedding in the reciprocal ranking fusion. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `text_weight: number` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The weight of the text in the reciprocal ranking fusion. + 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). - - `ranker: optional "auto" or "default-2024-11-15"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The ranker to use for the file search. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"auto"` + - `code_interpreter: object { container, type, allowed_callers }` - - `"default-2024-11-15"` + A tool that runs Python code to help generate a response to a prompt. - - `score_threshold: optional number` + - `programmatic_tool_calling: object { type }` - 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. + - `image_generation: object { type, action, background, 9 more }` - - `beta_computer_tool: object { type }` + A tool that generates images using the GPT image models. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `local_shell: object { type }` - - `type: "computer"` + A tool that allows the model to execute shell commands in a local environment. - The type of the computer tool. Always `computer`. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + A tool that allows the model to execute shell commands. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `display_height: number` + 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) - The height of the computer display. + - `beta_namespace_tool: object { description, name, tools, type }` - - `display_width: number` + Groups function/custom tools under a shared namespace. - The width of the computer display. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `environment: "windows" or "mac" or "linux" or 2 more` + Hosted or BYOT tool search configuration for deferred tools. - The type of computer environment to control. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"windows"` + 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). - - `"mac"` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `"linux"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"ubuntu"` + - `type: "tool_search_output"` - - `"browser"` + The type of the item. Always `tool_search_output`. - - `type: "computer_use_preview"` + - `agent: optional object { agent_name }` - The type of the computer use tool. Always `computer_use_preview`. + The agent that produced this item. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `agent_name: string` - 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). + The canonical name of the agent that produced this item. - - `type: "web_search" or "web_search_2025_08_26"` + - `created_by: optional string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The identifier of the actor that created the item. - - `"web_search"` + - `additional_tools: object { id, role, tools, 2 more }` - - `"web_search_2025_08_26"` + - `id: string` - - `filters: optional object { allowed_domains }` + The unique ID of the additional tools item. - Filters for the search. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `allowed_domains: optional array of string` + The role that provided the additional tools. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"unknown"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"user"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"assistant"` - 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. + - `"system"` - - `"low"` + - `"critic"` - - `"medium"` + - `"discriminator"` - - `"high"` + - `"developer"` - - `user_location: optional object { city, country, region, 2 more }` + - `"tool"` - The approximate location of the user. + - `tools: array of BetaTool` - - `city: optional string` + The additional tool definitions made available at this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `country: optional string` + 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). - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `region: optional string` + 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). - Free text input for the region of the user, e.g. `California`. + - `beta_computer_tool: object { type }` - - `timezone: optional string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `type: optional "approximate"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of location approximation. Always `approximate`. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `"approximate"` + 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: object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `server_label: string` + - `code_interpreter: object { container, type, allowed_callers }` - A label for this MCP server, used to identify it in tool calls. + A tool that runs Python code to help generate a response to a prompt. - - `type: "mcp"` + - `programmatic_tool_calling: object { type }` - The type of the MCP tool. Always `mcp`. + - `image_generation: object { type, action, background, 9 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A tool that generates images using the GPT image models. - The tool invocation context(s). + - `local_shell: object { type }` - - `"direct"` + A tool that allows the model to execute shell commands in a local environment. - - `"programmatic"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + A tool that allows the model to execute shell commands. - List of allowed tool names or a filter object. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `MCP allowed tools: array of string` + 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) - A string array of allowed tool names + - `beta_namespace_tool: object { description, name, tools, type }` - - `MCP tool filter: object { read_only, tool_names }` + Groups function/custom tools under a shared namespace. - A filter object to specify which tools are allowed. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `read_only: optional boolean` + Hosted or BYOT tool search configuration for deferred tools. - 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. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `tool_names: optional array of string` + 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). - List of allowed tool names. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `authorization: optional string` + Allows the assistant to create, delete, or update files using unified diffs. - 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. + - `type: "additional_tools"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The type of the item. Always `additional_tools`. - 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). + - `agent: optional object { agent_name }` - Currently supported `connector_id` values are: + The agent that produced this item. - - 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` + - `agent_name: string` - - `"connector_dropbox"` + The canonical name of the agent that produced this item. - - `"connector_gmail"` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - `"connector_googlecalendar"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `"connector_googledrive"` + - `id: string` - - `"connector_microsoftteams"` + The unique ID of the compaction item. - - `"connector_outlookcalendar"` + - `encrypted_content: string` - - `"connector_outlookemail"` + The encrypted content that was produced by compaction. - - `"connector_sharepoint"` + - `type: "compaction"` - - `defer_loading: optional boolean` + The type of the item. Always `compaction`. - Whether this MCP tool is deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `headers: optional map[string]` + The agent that produced this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `agent_name: string` - - `require_approval: optional object { always, never } or "always" or "never"` + The canonical name of the agent that produced this item. - Specify which of the MCP server's tools require approval. + - `created_by: optional string` - - `MCP tool approval filter: object { always, never }` + The identifier of the actor that created the item. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `image_generation_call: object { id, result, status, 2 more }` - - `always: optional object { read_only, tool_names }` + An image generation request made by the model. - A filter object to specify which tools are allowed. + - `id: string` - - `read_only: optional boolean` + The unique ID of the image generation call. - 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. + - `result: string` - - `tool_names: optional array of string` + The generated image encoded in base64. - List of allowed tool names. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `never: optional object { read_only, tool_names }` + The status of the image generation call. - A filter object to specify which tools are allowed. + - `"in_progress"` - - `read_only: optional boolean` + - `"completed"` - 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. + - `"generating"` - - `tool_names: optional array of string` + - `"failed"` - List of allowed tool names. + - `type: "image_generation_call"` - - `MCP tool approval setting: "always" or "never"` + The type of the image generation call. Always `image_generation_call`. - 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. + - `agent: optional object { agent_name }` - - `"always"` + The agent that produced this item. - - `"never"` + - `agent_name: string` - - `server_description: optional string` + The canonical name of the agent that produced this item. - Optional description of the MCP server, used to provide more context. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `server_url: optional string` + A tool call to run code. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `id: string` - - `tunnel_id: optional string` + The unique ID of the code interpreter tool call. - 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. + - `code: string` - - `code_interpreter: object { container, type, allowed_callers }` + The code to run, or null if not available. - A tool that runs Python code to help generate a response to a prompt. + - `container_id: string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The ID of the container used to run the code. - 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. + - `outputs: array of object { logs, type } or object { type, url }` - - `union_member_0: string` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The container ID. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `type: "code_interpreter_call"` - - `type: "auto"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Always `auto`. + - `agent: optional object { agent_name }` - - `file_ids: optional array of string` + The agent that produced this item. - An optional list of uploaded files to make available to your code. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A tool call to run a command on the local shell. - The memory limit for the code interpreter container. + - `id: string` - - `"1g"` + The unique ID of the local shell call. - - `"4g"` + - `action: object { command, env, type, 3 more }` - - `"16g"` + Execute a shell command on the server. - - `"64g"` + - `command: array of string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The command to run. - Network access policy for the container. + - `env: map[string]` - - `beta_container_network_policy_disabled: object { type }` + Environment variables to set for the command. - - `type: "disabled"` + - `type: "exec"` - Disable outbound network access. Always `disabled`. + The type of the local shell action. Always `exec`. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `timeout_ms: optional number` - - `allowed_domains: array of string` + Optional timeout in milliseconds for the command. - A list of allowed domains when type is `allowlist`. + - `user: optional string` - - `type: "allowlist"` + Optional user to run the command as. - Allow outbound network access only to specified domains. Always `allowlist`. + - `working_directory: optional string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + Optional working directory to run the command in. - Optional domain-scoped secrets for allowlisted domains. + - `call_id: string` - - `domain: string` + The unique ID of the local shell tool call generated by the model. - The domain associated with the secret. + - `status: "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the local shell call. - The name of the secret to inject for the domain. + - `"in_progress"` - - `value: string` + - `"completed"` - The secret value to inject for the domain. + - `"incomplete"` - - `type: "code_interpreter"` + - `type: "local_shell_call"` - The type of the code interpreter tool. Always `code_interpreter`. + The type of the local shell call. Always `local_shell_call`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that produced this item. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `programmatic_tool_calling: object { type }` + - `local_shell_call_output: object { id, output, type, 2 more }` - - `image_generation: object { type, action, background, 9 more }` + The output of a local shell tool call. - A tool that generates images using the GPT image models. + - `id: string` - - `type: "image_generation"` + The unique ID of the local shell tool call generated by the model. - The type of the image generation tool. Always `image_generation`. + - `output: string` - - `action: optional "generate" or "edit" or "auto"` + A JSON string of the output of the local shell tool call. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: "local_shell_call_output"` - - `"generate"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"edit"` + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `background: optional "transparent" or "opaque" or "auto"` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - `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. + - `status: optional "in_progress" or "completed" or "incomplete"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"transparent"` + - `"in_progress"` - - `"opaque"` + - `"completed"` - - `"auto"` + - `"incomplete"` - - `input_fidelity: optional "high" or "low"` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - 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`. + A tool call that executes one or more shell commands in a managed environment. - - `"high"` + - `id: string` - - `"low"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `input_image_mask: optional object { file_id, image_url }` + - `action: object { commands, max_output_length, timeout_ms }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The shell commands and limits that describe how to run the tool call. - - `file_id: optional string` + - `commands: array of string` - File ID for the mask image. + - `max_output_length: number` - - `image_url: optional string` + Optional maximum number of characters to return from each command. - Base64-encoded mask image. + - `timeout_ms: number` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + Optional timeout in milliseconds for the commands. - The image generation model to use. Default: `gpt-image-1`. + - `call_id: string` - - `"gpt-image-1"` + The unique ID of the shell tool call generated by the model. - - `"gpt-image-1-mini"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `"gpt-image-2"` + Represents the use of a local environment to perform shell actions. - - `"gpt-image-2-2026-04-21"` + - `beta_response_local_environment: object { type }` - - `"gpt-image-1.5"` + Represents the use of a local environment to perform shell actions. - - `"chatgpt-image-latest"` + - `type: "local"` - - `moderation: optional "auto" or "low"` + The environment type. Always `local`. - Moderation level for the generated image. Default: `auto`. + - `beta_response_container_reference: object { container_id, type }` - - `"auto"` + Represents a container created with /v1/containers. - - `"low"` + - `container_id: string` - - `output_compression: optional number` + - `type: "container_reference"` - Compression level for the output image. Default: 100. + The environment type. Always `container_reference`. - - `output_format: optional "png" or "webp" or "jpeg"` + - `status: "in_progress" or "completed" or "incomplete"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"png"` + - `"in_progress"` - - `"webp"` + - `"completed"` - - `"jpeg"` + - `"incomplete"` - - `partial_images: optional number` + - `type: "shell_call"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The type of the item. Always `shell_call`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `agent: optional object { agent_name }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `caller: optional object { type } or object { caller_id, type }` - - `"auto"` + The execution context that produced this tool call. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `direct: object { type }` - 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`. + - `program: object { caller_id, type }` - - `"1024x1024"` + - `caller_id: string` - - `"1024x1536"` + The call ID of the program item that produced this tool call. - - `"1536x1024"` + - `type: "program"` - - `"auto"` + - `created_by: optional string` - - `local_shell: object { type }` + The ID of the entity that created this tool call. - A tool that allows the model to execute shell commands in a local environment. + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The output of a shell tool call that was emitted. - A tool that allows the model to execute shell commands. + - `id: string` - - `type: "shell"` + The unique ID of the shell call output. Populated when this item is returned via API. - The type of the shell tool. Always `shell`. + - `call_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the shell tool call generated by the model. - The tool invocation context(s). + - `max_output_length: number` - - `"direct"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `"programmatic"` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + An array of shell call output contents - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `outcome: object { type } or object { exit_code, type }` - - `type: "container_auto"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - Automatically creates a container for this request + - `timeout: object { type }` - - `file_ids: optional array of string` + Indicates that the shell call exceeded its configured time limit. - An optional list of uploaded files to make available to your code. + - `exit: object { exit_code, type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Indicates that the shell commands finished and returned an exit code. - The memory limit for the container. + - `exit_code: number` - - `"1g"` + Exit code from the shell process. - - `"4g"` + - `type: "exit"` - - `"16g"` + The outcome type. Always `exit`. - - `"64g"` + - `stderr: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The standard error output that was captured. - Network access policy for the container. + - `stdout: string` - - `beta_container_network_policy_disabled: object { type }` + The standard output that was captured. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `created_by: optional string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The identifier of the actor that created the item. - An optional list of skills referenced by id or inline data. + - `status: "in_progress" or "completed" or "incomplete"` - - `beta_skill_reference: object { skill_id, type, version }` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `skill_id: string` + - `"in_progress"` - The ID of the referenced skill. + - `"completed"` - - `type: "skill_reference"` + - `"incomplete"` - References a skill created with the /v1/skills endpoint. + - `type: "shell_call_output"` - - `version: optional string` + The type of the shell call output. Always `shell_call_output`. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `agent: optional object { agent_name }` - - `beta_inline_skill: object { description, name, source, type }` + The agent that produced this item. - - `description: string` + - `agent_name: string` - The description of the skill. + The canonical name of the agent that produced this item. - - `name: string` + - `caller: optional object { type } or object { caller_id, type }` - The name of the skill. + The execution context that produced this tool call. - - `source: object { data, media_type, type }` + - `direct: object { type }` - Inline skill payload + - `program: object { caller_id, type }` - - `data: string` + - `caller_id: string` - Base64-encoded skill zip bundle. + The call ID of the program item that produced this tool call. - - `media_type: "application/zip"` + - `type: "program"` - The media type of the inline skill payload. Must be `application/zip`. + - `created_by: optional string` - - `type: "base64"` + The identifier of the actor that created the item. - The type of the inline skill source. Must be `base64`. + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `type: "inline"` + A tool call that applies file diffs by creating, deleting, or updating files. - Defines an inline skill for this request. + - `id: string` - - `beta_local_environment: object { type, skills }` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `type: "local"` + - `call_id: string` - Use a local computer environment. + The unique ID of the apply patch tool call generated by the model. - - `skills: optional array of BetaLocalSkill` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - An optional list of skills. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `description: string` + - `create_file: object { diff, path, type }` - The description of the skill. + Instruction describing how to create a file via the apply_patch tool. - - `name: string` + - `diff: string` - The name of the skill. + Diff to apply. - `path: string` - The path to the directory containing the skill. + Path of the file to create. - - `beta_container_reference: object { container_id, type }` + - `type: "create_file"` - - `container_id: string` + Create a new file with the provided diff. - The ID of the referenced container. + - `delete_file: object { path, type }` - - `type: "container_reference"` + Instruction describing how to delete a file via the apply_patch tool. - References a container created with the /v1/containers endpoint + - `path: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Path of the file to delete. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "delete_file"` - - `name: string` + Delete the specified file. - The name of the custom tool, used to identify it in tool calls. + - `update_file: object { diff, path, type }` - - `type: "custom"` + Instruction describing how to update a file via the apply_patch tool. - The type of the custom tool. Always `custom`. + - `diff: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Diff to apply. - The tool invocation context(s). + - `path: string` - - `"direct"` + Path of the file to update. - - `"programmatic"` + - `type: "update_file"` - - `defer_loading: optional boolean` + Update an existing file with the provided diff. - Whether this tool should be deferred and discovered via tool search. + - `status: "in_progress" or "completed"` - - `description: optional string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Optional description of the custom tool, used to provide more context. + - `"in_progress"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"completed"` - The input format for the custom tool. Default is unconstrained text. + - `type: "apply_patch_call"` - - `text: object { type }` + The type of the item. Always `apply_patch_call`. - Unconstrained free-form text. + - `agent: optional object { agent_name }` - - `grammar: object { definition, syntax, type }` + The agent that produced this item. - A grammar defined by the user. + - `agent_name: string` - - `definition: string` + The canonical name of the agent that produced this item. - The grammar definition. + - `caller: optional object { type } or object { caller_id, type }` - - `syntax: "lark" or "regex"` + The execution context that produced this tool call. - The syntax of the grammar definition. One of `lark` or `regex`. + - `direct: object { type }` - - `"lark"` + - `program: object { caller_id, type }` - - `"regex"` + - `caller_id: string` - - `type: "grammar"` + The call ID of the program item that produced this tool call. - Grammar format. Always `grammar`. + - `type: "program"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `created_by: optional string` - Groups function/custom tools under a shared namespace. + The ID of the entity that created this tool call. - - `description: string` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - A description of the namespace shown to the model. + The output emitted by an apply patch tool call. - - `name: string` + - `id: string` - The namespace name used in tool calls (for example, `crm`). + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `call_id: string` - The function/custom tools available inside this namespace. + The unique ID of the apply patch tool call generated by the model. - - `function: object { name, type, allowed_callers, 5 more }` + - `status: "completed" or "failed"` - - `name: string` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: "function"` + - `"completed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"failed"` - The tool invocation context(s). + - `type: "apply_patch_call_output"` - - `"direct"` + The type of the item. Always `apply_patch_call_output`. - - `"programmatic"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that produced this item. - Whether this function should be deferred and discovered via tool search. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - - `output_schema: optional map[unknown]` + - `caller: optional object { type } or object { caller_id, type }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The execution context that produced this tool call. - - `parameters: optional unknown` + - `direct: object { type }` - - `strict: optional boolean` + - `program: object { caller_id, type }` - 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. + - `caller_id: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The call ID of the program item that produced this tool call. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "program"` - - `name: string` + - `created_by: optional string` - The name of the custom tool, used to identify it in tool calls. + The ID of the entity that created this tool call output. - - `type: "custom"` + - `output: optional string` - The type of the custom tool. Always `custom`. + Optional textual output returned by the apply patch tool. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `mcp_call: object { id, arguments, name, 7 more }` - The tool invocation context(s). + An invocation of a tool on an MCP server. - - `defer_loading: optional boolean` + - `id: string` - Whether this tool should be deferred and discovered via tool search. + The unique ID of the tool call. - - `description: optional string` + - `arguments: string` - Optional description of the custom tool, used to provide more context. + A JSON string of the arguments passed to the tool. - - `format: optional object { type } or object { definition, syntax, type }` + - `name: string` - The input format for the custom tool. Default is unconstrained text. + The name of the tool that was run. - - `type: "namespace"` + - `server_label: string` - The type of the tool. Always `namespace`. + The label of the MCP server running the tool. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `type: "mcp_call"` - Hosted or BYOT tool search configuration for deferred tools. + The type of the item. Always `mcp_call`. - - `type: "tool_search"` + - `agent: optional object { agent_name }` - The type of the tool. Always `tool_search`. + The agent that produced this item. - - `description: optional string` + - `agent_name: string` - Description shown to the model for a client-executed tool search tool. + The canonical name of the agent that produced this item. - - `execution: optional "server" or "client"` + - `approval_request_id: optional string` - Whether tool search is executed by the server or by the client. + 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. - - `"server"` + - `error: optional string` - - `"client"` + The error from the tool call, if any. - - `parameters: optional unknown` + - `output: optional string` - Parameter schema for a client-executed tool search tool. + The output from the tool call. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - 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). + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"in_progress"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"completed"` - - `"web_search_preview"` + - `"incomplete"` - - `"web_search_preview_2025_03_11"` + - `"calling"` - - `search_content_types: optional array of "text" or "image"` + - `"failed"` - - `"text"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `"image"` + A list of tools available on an MCP server. - - `search_context_size: optional "low" or "medium" or "high"` + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. - 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. + - `input_schema: unknown` - - `"low"` + The JSON schema describing the tool's input. - - `"medium"` + - `name: string` - - `"high"` + The name of the tool. - - `user_location: optional object { type, city, country, 2 more }` + - `annotations: optional unknown` - The user's location. + Additional annotations about the tool. - - `type: "approximate"` + - `description: optional string` - The type of location approximation. Always `approximate`. + The description of the tool. - - `city: optional string` + - `type: "mcp_list_tools"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the item. Always `mcp_list_tools`. - - `country: optional string` + - `agent: optional object { agent_name }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The agent that produced this item. - - `region: optional string` + - `agent_name: string` - Free text input for the region of the user, e.g. `California`. + The canonical name of the agent that produced this item. - - `timezone: optional string` + - `error: optional string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Error message if the server could not list tools. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - Allows the assistant to create, delete, or update files using unified diffs. + A request for human approval of a tool invocation. - - `type: "apply_patch"` + - `id: string` - The type of the tool. Always `apply_patch`. + The unique ID of the approval request. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `arguments: string` - The tool invocation context(s). + A JSON string of arguments for the tool. - - `"direct"` + - `name: string` - - `"programmatic"` + The name of the tool to run. - - `type: "tool_search_output"` + - `server_label: string` - The item type. Always `tool_search_output`. + The label of the MCP server making the request. - - `id: optional string` + - `type: "mcp_approval_request"` - The unique ID of this tool search output. + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` @@ -51963,907 +62231,999 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - The unique ID of the tool search call generated by the model. + A response to an MCP approval request. - - `execution: optional "server" or "client"` + - `id: string` - Whether tool search was executed by the server or by the client. + The unique ID of the approval response - - `"server"` + - `approval_request_id: string` - - `"client"` + The ID of the approval request being answered. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `approve: boolean` - The status of the tool search output. + Whether the request was approved. - - `"in_progress"` + - `type: "mcp_approval_response"` - - `"completed"` + The type of the item. Always `mcp_approval_response`. - - `"incomplete"` + - `agent: optional object { agent_name }` - - `additional_tools: object { role, tools, type, 2 more }` + The agent that produced this item. - - `role: "developer"` + - `agent_name: string` - The role that provided the additional tools. Only `developer` is supported. + The canonical name of the agent that produced this item. - - `tools: array of BetaTool` + - `reason: optional string` - A list of additional tools made available at this item. + Optional reason for the decision. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - 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). + A call to a custom tool created by the model. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `call_id: string` - 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). + An identifier used to map this custom tool call to a tool call output. - - `beta_computer_tool: object { type }` + - `input: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The input for the custom tool call generated by the model. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `name: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The name of the custom tool being called. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `type: "custom_tool_call"` - 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). + The type of the custom tool call. Always `custom_tool_call`. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `id: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The unique ID of the custom tool call in the OpenAI platform. - - `code_interpreter: object { container, type, allowed_callers }` + - `agent: optional object { agent_name }` - A tool that runs Python code to help generate a response to a prompt. + The agent that produced this item. - - `programmatic_tool_calling: object { type }` + - `caller: optional object { type } or object { caller_id, type }` - - `image_generation: object { type, action, background, 9 more }` + The execution context that produced this tool call. - A tool that generates images using the GPT image models. + - `namespace: optional string` - - `local_shell: object { type }` + The namespace of the custom tool being called. - A tool that allows the model to execute shell commands in a local environment. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The output of a custom tool call from your code, being sent back to the model. - A tool that allows the model to execute shell commands. + - `id: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The unique ID of the custom tool call output item. - 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) + - `status: "in_progress" or "completed" or "incomplete"` - - `beta_namespace_tool: object { description, name, tools, type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Groups function/custom tools under a shared namespace. + - `"in_progress"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `"completed"` - Hosted or BYOT tool search configuration for deferred tools. + - `"incomplete"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `created_by: optional string` - 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). + The identifier of the actor that created the item. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `parallel_tool_calls: boolean` - Allows the assistant to create, delete, or update files using unified diffs. + Whether to allow the model to run tool calls in parallel. - - `type: "additional_tools"` + - `temperature: number` - The item type. Always `additional_tools`. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `id: optional string` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The unique ID of this additional tools item. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `agent: optional object { agent_name }` + - `beta_tool_choice_options: "none" or "auto" or "required"` - The agent that produced this item. + Controls which (if any) tool is called by the model. - - `agent_name: string` + `none` means the model will not call any tool and instead generates a message. - The canonical name of the agent that produced this item. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + `required` means the model must call one or more tools. - 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). + - `"none"` - - `id: string` + - `"auto"` - The unique identifier of the reasoning content. + - `"required"` - - `summary: array of object { text, type }` + - `beta_tool_choice_allowed: object { mode, tools, type }` - Reasoning summary content. + Constrains the tools available to the model to a pre-defined set. - - `text: string` + - `mode: "auto" or "required"` - A summary of the reasoning output from the model so far. + Constrains the tools available to the model to a pre-defined set. - - `type: "summary_text"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The type of the object. Always `summary_text`. + `required` requires the model to call one or more of the allowed tools. - - `type: "reasoning"` + - `"auto"` - The type of the object. Always `reasoning`. + - `"required"` - - `agent: optional object { agent_name }` + - `tools: array of map[unknown]` - The agent that produced this item. + A list of tool definitions that the model should be allowed to call. - - `agent_name: string` + For the Responses API, the list of tool definitions might look like: - The canonical name of the agent that produced this item. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `content: optional array of object { text, type }` + - `type: "allowed_tools"` - Reasoning text content. + Allowed tool configuration type. Always `allowed_tools`. - - `text: string` + - `beta_tool_choice_types: object { type }` - The reasoning text from the model. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `type: "reasoning_text"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - The type of the reasoning text. Always `reasoning_text`. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `encrypted_content: optional string` + Allowed values are: - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"file_search"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"web_search_preview"` - - `"in_progress"` + - `"computer"` - - `"completed"` + - `"computer_use_preview"` - - `"incomplete"` + - `"computer_use"` - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `"web_search_preview_2025_03_11"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"image_generation"` - - `encrypted_content: string` + - `"code_interpreter"` - The encrypted content of the compaction summary. + - `beta_tool_choice_function: object { name, type }` - - `type: "compaction"` + Use this option to force the model to call a specific function. - The type of the item. Always `compaction`. + - `name: string` - - `id: optional string` + The name of the function to call. - The ID of the compaction item. + - `type: "function"` - - `agent: optional object { agent_name }` + For function calling, the type is always `function`. - The agent that produced this item. + - `beta_tool_choice_mcp: object { server_label, type, name }` - - `agent_name: string` + Use this option to force the model to call a specific tool on a remote MCP server. - The canonical name of the agent that produced this item. + - `server_label: string` - - `image_generation_call: object { id, result, status, 2 more }` + The label of the MCP server to use. - An image generation request made by the model. + - `type: "mcp"` - - `id: string` + For MCP tools, the type is always `mcp`. - The unique ID of the image generation call. + - `name: optional string` - - `result: string` + The name of the tool to call on the server. - The generated image encoded in base64. + - `beta_tool_choice_custom: object { name, type }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + Use this option to force the model to call a specific custom tool. - The status of the image generation call. + - `name: string` - - `"in_progress"` + The name of the custom tool to call. - - `"completed"` + - `type: "custom"` - - `"generating"` + For custom tool calling, the type is always `custom`. - - `"failed"` + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - - `type: "image_generation_call"` + - `beta_tool_choice_apply_patch: object { type }` - The type of the image generation call. Always `image_generation_call`. + Forces the model to call the apply_patch tool when executing a tool call. - - `agent: optional object { agent_name }` + - `type: "apply_patch"` - The agent that produced this item. + The tool to call. Always `apply_patch`. - - `agent_name: string` + - `beta_tool_choice_shell: object { type }` - The canonical name of the agent that produced this item. + Forces the model to call the shell tool when a tool call is required. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `type: "shell"` - A tool call to run code. + The tool to call. Always `shell`. - - `id: string` + - `tools: array of BetaTool` - The unique ID of the code interpreter tool call. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `code: string` + We support the following categories of tools: - The code to run, or null if not available. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `container_id: string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The ID of the container used to run the code. + 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). - - `outputs: array of object { logs, type } or object { type, url }` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + 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). - - `logs: object { logs, type }` + - `beta_computer_tool: object { type }` - The logs output from the code interpreter. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `logs: string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The logs output from the code interpreter. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "logs"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the output. Always `logs`. + 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). - - `image: object { type, url }` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The image output from the code interpreter. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `type: "image"` + - `code_interpreter: object { container, type, allowed_callers }` - The type of the output. Always `image`. + A tool that runs Python code to help generate a response to a prompt. - - `url: string` + - `programmatic_tool_calling: object { type }` - The URL of the image output from the code interpreter. + - `image_generation: object { type, action, background, 9 more }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + A tool that generates images using the GPT image models. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `local_shell: object { type }` - - `"in_progress"` + A tool that allows the model to execute shell commands in a local environment. - - `"completed"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"incomplete"` + A tool that allows the model to execute shell commands. - - `"interpreting"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"failed"` + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: "code_interpreter_call"` + - `beta_namespace_tool: object { description, name, tools, type }` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Groups function/custom tools under a shared namespace. - - `agent: optional object { agent_name }` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The agent that produced this item. + Hosted or BYOT tool search configuration for deferred tools. - - `agent_name: string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The canonical name of the agent that produced this item. + 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). - - `local_shell_call: object { id, action, call_id, 3 more }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - A tool call to run a command on the local shell. + Allows the assistant to create, delete, or update files using unified diffs. - - `id: string` + - `top_p: number` - The unique ID of the local shell call. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `action: object { command, env, type, 3 more }` + We generally recommend altering this or `temperature` but not both. - Execute a shell command on the server. + - `background: optional boolean` - - `command: array of string` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The command to run. + - `completed_at: optional number` - - `env: map[string]` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - Environment variables to set for the command. + - `conversation: optional object { id }` - - `type: "exec"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The type of the local shell action. Always `exec`. + - `id: string` - - `timeout_ms: optional number` + The unique ID of the conversation that this response was associated with. - Optional timeout in milliseconds for the command. + - `max_output_tokens: optional number` - - `user: optional string` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - Optional user to run the command as. + - `max_tool_calls: optional number` - - `working_directory: optional string` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - Optional working directory to run the command in. + - `moderation: optional object { input, output }` - - `call_id: string` + Moderation results for the response input and output, if moderated completions were requested. - The unique ID of the local shell tool call generated by the model. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `status: "in_progress" or "completed" or "incomplete"` + Moderation for the response input. - The status of the local shell call. + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `"in_progress"` + A moderation result produced for the response input or output. - - `"completed"` + - `categories: map[boolean]` - - `"incomplete"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `type: "local_shell_call"` + - `category_applied_input_types: map[array of "text" or "image"]` - The type of the local shell call. Always `local_shell_call`. + Which modalities of input are reflected by the score for each category. - - `agent: optional object { agent_name }` + - `"text"` - The agent that produced this item. + - `"image"` - - `agent_name: string` + - `category_scores: map[number]` - The canonical name of the agent that produced this item. + A dictionary of moderation categories to scores. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `flagged: boolean` - The output of a local shell tool call. + A boolean indicating whether the content was flagged by any category. - - `id: string` + - `model: string` - The unique ID of the local shell tool call generated by the model. + The moderation model that produced this result. - - `output: string` + - `type: "moderation_result"` - A JSON string of the output of the local shell tool call. + The object type, which was always `moderation_result` for successful moderation results. - - `type: "local_shell_call_output"` + - `error: object { code, message, type }` - The type of the local shell tool call output. Always `local_shell_call_output`. + An error produced while attempting moderation for the response input or output. - - `agent: optional object { agent_name }` + - `code: string` - The agent that produced this item. + The error code. - - `agent_name: string` + - `message: string` - The canonical name of the agent that produced this item. + The error message. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "error"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The object type, which was always `error` for moderation failures. - - `"in_progress"` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"completed"` + Moderation for the response output. - - `"incomplete"` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `shell_call: object { action, call_id, type, 5 more }` + A moderation result produced for the response input or output. - A tool representing a request to execute one or more shell commands. + - `categories: map[boolean]` - - `action: object { commands, max_output_length, timeout_ms }` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The shell commands and limits that describe how to run the tool call. + - `category_applied_input_types: map[array of "text" or "image"]` - - `commands: array of string` + Which modalities of input are reflected by the score for each category. - Ordered shell commands for the execution environment to run. + - `"text"` - - `max_output_length: optional number` + - `"image"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `category_scores: map[number]` - - `timeout_ms: optional number` + A dictionary of moderation categories to scores. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `flagged: boolean` - - `call_id: string` + A boolean indicating whether the content was flagged by any category. - The unique ID of the shell tool call generated by the model. + - `model: string` - - `type: "shell_call"` + The moderation model that produced this result. - The type of the item. Always `shell_call`. + - `type: "moderation_result"` - - `id: optional string` + The object type, which was always `moderation_result` for successful moderation results. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `error: object { code, message, type }` - - `agent: optional object { agent_name }` + An error produced while attempting moderation for the response input or output. - The agent that produced this item. + - `code: string` - - `agent_name: string` + The error code. - The canonical name of the agent that produced this item. + - `message: string` - - `caller: optional object { type } or object { caller_id, type }` + The error message. - The execution context that produced this tool call. + - `type: "error"` - - `direct: object { type }` + The object type, which was always `error` for moderation failures. - - `program: object { caller_id, type }` + - `previous_response_id: optional string` - - `caller_id: string` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The call ID of the program item that produced this tool call. + - `prompt: optional object { id, variables, version }` - - `type: "program"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The caller type. Always `program`. + - `id: string` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + The unique identifier of the prompt template to use. - The environment to execute the shell commands in. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `beta_local_environment: object { type, skills }` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `beta_container_reference: object { container_id, type }` + - `union_member_0: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + A text input to the model. - - `"in_progress"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"completed"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"incomplete"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `shell_call_output: object { call_id, output, type, 5 more }` + A file input to the model. - The streamed output items emitted by a shell tool call. + - `version: optional string` - - `call_id: string` + Optional version of the prompt template. - The unique ID of the shell tool call generated by the model. + - `prompt_cache_key: optional string` - - `output: array of BetaResponseFunctionShellCallOutputContent` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `prompt_cache_options: optional object { mode, ttl }` - - `outcome: object { type } or object { exit_code, type }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The exit or timeout outcome associated with this shell call. + - `mode: "implicit" or "explicit"` - - `timeout: object { type }` + Whether implicit prompt-cache breakpoints were enabled. - Indicates that the shell call exceeded its configured time limit. + - `"implicit"` - - `exit: object { exit_code, type }` + - `"explicit"` - Indicates that the shell commands finished and returned an exit code. + - `ttl: "30m"` - - `exit_code: number` + The minimum lifetime applied to each cache breakpoint. - The exit code returned by the shell process. + - `"30m"` - - `type: "exit"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The outcome type. Always `exit`. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `stderr: string` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - Captured stderr output for the shell call. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `stdout: string` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - Captured stdout output for the shell call. + - `"in_memory"` - - `type: "shell_call_output"` + - `"24h"` - The type of the item. Always `shell_call_output`. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `id: optional string` + **gpt-5 and o-series models only** - The unique ID of the shell tool call output. Populated when this item is returned via API. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `agent: optional object { agent_name }` + - `context: optional "auto" or "current_turn" or "all_turns"` - The agent that produced this item. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"current_turn"` - - `caller: optional object { type } or object { caller_id, type }` + - `"all_turns"` - The execution context that produced this tool call. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `direct: object { type }` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `program: object { caller_id, type }` + - `"none"` - - `caller_id: string` + - `"minimal"` - The call ID of the program item that produced this tool call. + - `"low"` - - `type: "program"` + - `"medium"` - The caller type. Always `program`. + - `"high"` - - `max_output_length: optional number` + - `"xhigh"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"max"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The status of the shell call output. + **Deprecated:** use `summary` instead. - - `"in_progress"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"concise"` - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `"detailed"` - A tool call representing a request to create, delete, or update files using diff patches. + - `mode: optional string or "standard" or "pro"` - - `call_id: string` + Controls the reasoning execution mode for the request. - The unique ID of the apply patch tool call generated by the model. + When returned on a response, this is the effective execution mode. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"standard"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"pro"` - - `create_file: object { diff, path, type }` + - `summary: optional "auto" or "concise" or "detailed"` - Instruction for creating a new file via the apply_patch tool. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `diff: string` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Unified diff content to apply when creating the file. + - `"auto"` - - `path: string` + - `"concise"` - Path of the file to create relative to the workspace root. + - `"detailed"` - - `type: "create_file"` + - `safety_identifier: optional string` - The operation type. Always `create_file`. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `delete_file: object { path, type }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - Instruction for deleting an existing file via the apply_patch tool. + Specifies the processing type used for serving the request. - - `path: string` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - Path of the file to delete relative to the workspace root. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `type: "delete_file"` + - `"auto"` - The operation type. Always `delete_file`. + - `"default"` - - `update_file: object { diff, path, type }` + - `"flex"` - Instruction for updating an existing file via the apply_patch tool. + - `"scale"` - - `diff: string` + - `"priority"` - Unified diff content to apply to the existing file. + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `path: string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - Path of the file to update relative to the workspace root. + - `"completed"` - - `type: "update_file"` + - `"failed"` - The operation type. Always `update_file`. + - `"in_progress"` - - `status: "in_progress" or "completed"` + - `"cancelled"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"queued"` - - `"in_progress"` + - `"incomplete"` - - `"completed"` + - `text: optional object { format, verbosity }` - - `type: "apply_patch_call"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The type of the item. Always `apply_patch_call`. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `id: optional string` + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + An object specifying the format that the model must output. - - `agent: optional object { agent_name }` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The agent that produced this item. + The default format is `{ "type": "text" }` with no additional options. - - `agent_name: string` + **Not recommended for gpt-4o and newer models:** - The canonical name of the agent that produced this item. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `caller: optional object { type } or object { caller_id, type }` + - `text: object { type }` - The execution context that produced this tool call. + Default response format. Used to generate text responses. - - `direct: object { type }` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - - `program: object { caller_id, type }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `caller_id: string` + - `name: string` - The call ID of the program item that produced this tool call. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `type: "program"` + - `schema: map[unknown]` - The caller type. Always `program`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `type: "json_schema"` - The streamed output emitted by an apply patch tool call. + The type of response format being defined. Always `json_schema`. - - `call_id: string` + - `description: optional string` - The unique ID of the apply patch tool call generated by the model. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `status: "completed" or "failed"` + - `strict: optional boolean` - The status of the apply patch tool call output. One of `completed` or `failed`. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"completed"` + - `json_object: object { type }` - - `"failed"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `type: "apply_patch_call_output"` + - `verbosity: optional "low" or "medium" or "high"` - The type of the item. Always `apply_patch_call_output`. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `id: optional string` + - `"low"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"medium"` - - `agent: optional object { agent_name }` + - `"high"` - The agent that produced this item. + - `top_logprobs: optional number` - - `agent_name: string` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The canonical name of the agent that produced this item. + - `truncation: optional "auto" or "disabled"` - - `caller: optional object { type } or object { caller_id, type }` + The truncation strategy to use for the model response. - The execution context that produced this tool call. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `direct: object { type }` + - `"auto"` - - `program: object { caller_id, type }` + - `"disabled"` - - `caller_id: string` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - The call ID of the program item that produced this tool call. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `type: "program"` + - `input_tokens: number` - The caller type. Always `program`. + The number of input tokens. - - `output: optional string` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + A detailed breakdown of the input tokens. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `cache_write_tokens: number` - A list of tools available on an MCP server. + The number of input tokens that were written to the cache. - - `id: string` + - `cached_tokens: number` - The unique ID of the list. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `server_label: string` + - `output_tokens: number` - The label of the MCP server. + The number of output tokens. - - `tools: array of object { input_schema, name, annotations, description }` + - `output_tokens_details: object { reasoning_tokens }` - The tools available on the server. + A detailed breakdown of the output tokens. - - `input_schema: unknown` + - `reasoning_tokens: number` - The JSON schema describing the tool's input. + The number of reasoning tokens. - - `name: string` + - `total_tokens: number` - The name of the tool. + The total number of tokens used. - - `annotations: optional unknown` + - `user: optional string` - Additional annotations about the tool. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `description: optional string` + - `sequence_number: number` - The description of the tool. + The sequence number of this event. - - `type: "mcp_list_tools"` + - `type: "response.in_progress"` - The type of the item. Always `mcp_list_tools`. + The type of the event. Always `response.in_progress`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `error: optional string` - - Error message if the server could not list tools. - - - `mcp_approval_request: object { id, arguments, name, 3 more }` - - A request for human approval of a tool invocation. - - - `id: string` - - The unique ID of the approval request. - - - `arguments: string` +### Beta Response Includable - A JSON string of arguments for the tool. +- `beta_response_includable: "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more` - - `name: string` + Specify additional output data to include in the model response. Currently supported values are: - The name of the tool to run. + - `web_search_call.results`: Include the search results of the web search tool call. + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - `server_label: string` + - `"file_search_call.results"` - The label of the MCP server making the request. + - `"web_search_call.results"` - - `type: "mcp_approval_request"` + - `"web_search_call.action.sources"` - The type of the item. Always `mcp_approval_request`. + - `"message.input_image.image_url"` - - `agent: optional object { agent_name }` + - `"computer_call_output.output.image_url"` - The agent that produced this item. + - `"code_interpreter_call.outputs"` - - `agent_name: string` + - `"reasoning.encrypted_content"` - The canonical name of the agent that produced this item. + - `"message.output_text.logprobs"` - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` +### Beta Response Incomplete Event - A response to an MCP approval request. +- `beta_response_incomplete_event: object { response, sequence_number, type, agent }` - - `approval_request_id: string` + An event that is emitted when a response finishes as incomplete. - The ID of the approval request being answered. + - `response: object { id, created_at, error, 31 more }` - - `approve: boolean` + The response that was incomplete. - Whether the request was approved. + - `id: string` - - `type: "mcp_approval_response"` + Unique identifier for this Response. - The type of the item. Always `mcp_approval_response`. + - `created_at: number` - - `id: optional string` + Unix timestamp (in seconds) of when this Response was created. - The unique ID of the approval response + - `error: object { code, message }` - - `agent: optional object { agent_name }` + An error object returned when the model fails to generate a Response. - The agent that produced this item. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - - `agent_name: string` + The error code for the response. - The canonical name of the agent that produced this item. + - `"server_error"` - - `reason: optional string` + - `"rate_limit_exceeded"` - Optional reason for the decision. + - `"invalid_prompt"` - - `mcp_call: object { id, arguments, name, 7 more }` + - `"bio_policy"` - An invocation of a tool on an MCP server. + - `"vector_store_timeout"` - - `id: string` + - `"invalid_image"` - The unique ID of the tool call. + - `"invalid_image_format"` - - `arguments: string` + - `"invalid_base64_image"` - A JSON string of the arguments passed to the tool. + - `"invalid_image_url"` - - `name: string` + - `"image_too_large"` - The name of the tool that was run. + - `"image_too_small"` - - `server_label: string` + - `"image_parse_error"` - The label of the MCP server running the tool. + - `"image_content_policy_violation"` - - `type: "mcp_call"` + - `"invalid_image_mode"` - The type of the item. Always `mcp_call`. + - `"image_file_too_large"` - - `agent: optional object { agent_name }` + - `"unsupported_image_media_type"` - The agent that produced this item. + - `"empty_image_file"` - - `agent_name: string` + - `"failed_to_download_image"` - The canonical name of the agent that produced this item. + - `"image_file_not_found"` - - `approval_request_id: optional string` + - `message: string` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + A human-readable description of the error. - - `error: optional string` + - `incomplete_details: object { reason }` - The error from the tool call, if any. + Details about why the response is incomplete. - - `output: optional string` + - `reason: optional "max_output_tokens" or "content_filter"` - The output from the tool call. + The reason why the response is incomplete. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"max_output_tokens"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"content_filter"` - - `"in_progress"` + - `instructions: string or array of BetaResponseInputItem` - - `"completed"` + A system (or developer) message inserted into the model's context. - - `"incomplete"` + When using 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. - - `"calling"` + - `union_member_0: string` - - `"failed"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `Input item list: array of BetaResponseInputItem` - The output of a custom tool call from your code, being sent back to the model. + A list of one or many input items to the model, containing + different content types. - - `call_id: string` + - `beta_easy_input_message: object { content, role, phase, type }` - The call ID, used to map this custom tool call output to a custom tool call. + 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. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `content: string or BetaResponseInputMessageContentList` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `string output: string` + - `Text input: string` - A string of the output of the custom tool call. + A text input to the model. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - Text, image, or file output of the custom tool call. + A list of one or many input items to the model, containing different content + types. - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` @@ -52881,6 +63241,10 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -52889,6 +63253,14 @@ openai beta:responses compact \ The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + - `type: "input_image"` The type of the input item. Always `input_image`. @@ -52905,6 +63277,10 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. @@ -52917,6 +63293,12 @@ openai beta:responses compact \ The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `"auto"` + + - `"low"` + + - `"high"` + - `file_data: optional string` The content of the file to be sent to the model. @@ -52937,61 +63319,71 @@ openai beta:responses compact \ 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. - - `type: "custom_tool_call_output"` + - `mode: "explicit"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The breakpoint mode. Always `explicit`. - - `id: optional string` + - `role: "user" or "assistant" or "system" or "developer"` - The unique ID of the custom tool call output in the OpenAI platform. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `agent: optional object { agent_name }` + - `"user"` - The agent that produced this item. + - `"assistant"` - - `agent_name: string` + - `"system"` - The canonical name of the agent that produced this item. + - `"developer"` - - `caller: optional object { type } or object { caller_id, type }` + - `phase: optional "commentary" or "final_answer"` - The execution context that produced this tool call. + 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. - - `direct: object { type }` + - `"commentary"` - - `program: object { caller_id, type }` + - `"final_answer"` - - `caller_id: string` + - `type: optional "message"` - The call ID of the program item that produced this tool call. + The type of the message input. Always `message`. - - `type: "program"` + - `"message"` - The caller type. Always `program`. + - `message: object { content, role, agent, 2 more }` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + 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. - A call to a custom tool created by the model. + - `content: array of BetaResponseInputContent` - - `call_id: string` + A list of one or many input items to the model, containing different content + types. - An identifier used to map this custom tool call to a tool call output. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `input: string` + A text input to the model. - The input for the custom tool call generated by the model. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `name: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The name of the custom tool being called. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `type: "custom_tool_call"` + A file input to the model. - The type of the custom tool call. Always `custom_tool_call`. + - `role: "user" or "system" or "developer"` - - `id: optional string` + The role of the message input. One of `user`, `system`, or `developer`. - The unique ID of the custom tool call in the OpenAI platform. + - `"user"` + + - `"system"` + + - `"developer"` - `agent: optional object { agent_name }` @@ -53001,117 +63393,185 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - The execution context that produced this tool call. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `direct: object { type }` + - `"in_progress"` - - `program: object { caller_id, type }` + - `"completed"` - - `caller_id: string` + - `"incomplete"` - The call ID of the program item that produced this tool call. + - `type: optional "message"` - - `type: "program"` + The type of the message input. Always set to `message`. - - `namespace: optional string` + - `"message"` - The namespace of the custom tool being called. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `compaction_trigger: object { type, agent }` + An output message from the model. - Compacts the current context. Must be the final input item. + - `id: string` - - `type: "compaction_trigger"` + The unique ID of the output message. - The type of the item. Always `compaction_trigger`. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `agent: optional object { agent_name }` + The content of the output message. - The agent that produced this item. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `agent_name: string` + A text output from the model. - The canonical name of the agent that produced this item. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `item_reference: object { id, agent, type }` + The annotations of the text output. - An internal identifier for an item to reference. + - `file_citation: object { file_id, filename, index, type }` - - `id: string` + A citation to a file. - The ID of the item to reference. + - `file_id: string` - - `agent: optional object { agent_name }` + The ID of the file. - The agent that produced this item. + - `filename: string` - - `agent_name: string` + The filename of the file cited. - The canonical name of the agent that produced this item. + - `index: number` - - `type: optional "item_reference"` + The index of the file in the list of files. - The type of item to reference. Always `item_reference`. + - `type: "file_citation"` - - `"item_reference"` + The type of the file citation. Always `file_citation`. - - `program: object { id, call_id, code, 3 more }` + - `url_citation: object { end_index, start_index, title, 2 more }` - - `id: string` + A citation for a web resource used to generate a model response. - The unique ID of this program item. + - `end_index: number` - - `call_id: string` + The index of the last character of the URL citation in the message. - The stable call ID of the program item. + - `start_index: number` - - `code: string` + The index of the first character of the URL citation in the message. - The JavaScript source executed by programmatic tool calling. + - `title: string` - - `fingerprint: string` + The title of the web resource. - Opaque program replay fingerprint that must be round-tripped. + - `type: "url_citation"` - - `type: "program"` + The type of the URL citation. Always `url_citation`. - The item type. Always `program`. + - `url: string` - - `agent: optional object { agent_name }` + The URL of the web resource. - The agent that produced this item. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `agent_name: string` + A citation for a container file used to generate a model response. - The canonical name of the agent that produced this item. + - `container_id: string` - - `program_output: object { id, call_id, result, 3 more }` + The ID of the container file. - - `id: string` + - `end_index: number` - The unique ID of this program output item. + The index of the last character of the container file citation in the message. - - `call_id: string` + - `file_id: string` - The call ID of the program item. + The ID of the file. - - `result: string` + - `filename: string` - The result produced by the program item. + The filename of the container file cited. - - `status: "completed" or "incomplete"` + - `start_index: number` - The terminal status of the program output. + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` + - `type: "message"` - The item type. Always `program_output`. + The type of the output message. Always `message`. - `agent: optional object { agent_name }` @@ -53121,533 +63581,539 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `metadata: map[string]` + - `phase: optional "commentary" or "final_answer"` - 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. + 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. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"commentary"` - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `"final_answer"` - Model ID used to generate the response, like `gpt-4o` 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. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `"gpt-5.6-sol"` + 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. - - `"gpt-5.6-terra"` + - `id: string` - - `"gpt-5.6-luna"` + The unique ID of the file search tool call. - - `"gpt-5.4"` + - `queries: array of string` - - `"gpt-5.4-mini"` + The queries used to search for files. - - `"gpt-5.4-nano"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"gpt-5.4-mini-2026-03-17"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"gpt-5.4-nano-2026-03-17"` + - `"in_progress"` - - `"gpt-5.3-chat-latest"` + - `"searching"` - - `"gpt-5.2"` + - `"completed"` - - `"gpt-5.2-2025-12-11"` + - `"incomplete"` - - `"gpt-5.2-chat-latest"` + - `"failed"` - - `"gpt-5.2-pro"` + - `type: "file_search_call"` - - `"gpt-5.2-pro-2025-12-11"` + The type of the file search tool call. Always `file_search_call`. - - `"gpt-5.1"` + - `agent: optional object { agent_name }` - - `"gpt-5.1-2025-11-13"` + The agent that produced this item. - - `"gpt-5.1-codex"` + - `agent_name: string` - - `"gpt-5.1-mini"` + The canonical name of the agent that produced this item. - - `"gpt-5.1-chat-latest"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"gpt-5"` + The results of the file search tool call. - - `"gpt-5-mini"` + - `attributes: optional map[string or number or boolean]` - - `"gpt-5-nano"` + 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. - - `"gpt-5-2025-08-07"` + - `union_member_0: string` - - `"gpt-5-mini-2025-08-07"` + - `union_member_1: number` - - `"gpt-5-nano-2025-08-07"` + - `union_member_2: boolean` - - `"gpt-5-chat-latest"` + - `file_id: optional string` - - `"gpt-4.1"` + The unique ID of the file. - - `"gpt-4.1-mini"` + - `filename: optional string` - - `"gpt-4.1-nano"` + The name of the file. - - `"gpt-4.1-2025-04-14"` + - `score: optional number` - - `"gpt-4.1-mini-2025-04-14"` + The relevance score of the file - a value between 0 and 1. - - `"gpt-4.1-nano-2025-04-14"` + - `text: optional string` - - `"o4-mini"` + The text that was retrieved from the file. - - `"o4-mini-2025-04-16"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `"o3"` + 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. - - `"o3-2025-04-16"` + - `id: string` - - `"o3-mini"` + The unique ID of the computer call. - - `"o3-mini-2025-01-31"` + - `call_id: string` - - `"o1"` + An identifier used when responding to the tool call with output. - - `"o1-2024-12-17"` + - `pending_safety_checks: array of object { id, code, message }` - - `"o1-preview"` + The pending safety checks for the computer call. - - `"o1-preview-2024-09-12"` + - `id: string` - - `"o1-mini"` + The ID of the pending safety check. - - `"o1-mini-2024-09-12"` + - `code: optional string` - - `"gpt-4o"` + The type of the pending safety check. - - `"gpt-4o-2024-11-20"` + - `message: optional string` - - `"gpt-4o-2024-08-06"` + Details about the pending safety check. - - `"gpt-4o-2024-05-13"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"gpt-4o-audio-preview"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"gpt-4o-audio-preview-2024-10-01"` + - `"in_progress"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `"completed"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `"incomplete"` - - `"gpt-4o-mini-audio-preview"` + - `type: "computer_call"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The type of the computer call. Always `computer_call`. - - `"gpt-4o-search-preview"` + - `"computer_call"` - - `"gpt-4o-mini-search-preview"` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `"gpt-4o-search-preview-2025-03-11"` + A click action. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `click: object { button, type, x, 2 more }` - - `"chatgpt-4o-latest"` + A click action. - - `"codex-mini-latest"` + - `button: "left" or "right" or "wheel" or 2 more` - - `"gpt-4o-mini"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"gpt-4o-mini-2024-07-18"` + - `"left"` - - `"gpt-4-turbo"` + - `"right"` - - `"gpt-4-turbo-2024-04-09"` + - `"wheel"` - - `"gpt-4-0125-preview"` + - `"back"` - - `"gpt-4-turbo-preview"` + - `"forward"` - - `"gpt-4-1106-preview"` + - `type: "click"` - - `"gpt-4-vision-preview"` + Specifies the event type. For a click action, this property is always `click`. - - `"gpt-4"` + - `x: number` - - `"gpt-4-0314"` + The x-coordinate where the click occurred. - - `"gpt-4-0613"` + - `y: number` - - `"gpt-4-32k"` + The y-coordinate where the click occurred. - - `"gpt-4-32k-0314"` + - `keys: optional array of string` - - `"gpt-4-32k-0613"` + The keys being held while clicking. - - `"gpt-3.5-turbo"` + - `double_click: object { keys, type, x, y }` - - `"gpt-3.5-turbo-16k"` + A double click action. - - `"gpt-3.5-turbo-0301"` + - `keys: array of string` - - `"gpt-3.5-turbo-0613"` + The keys being held while double-clicking. - - `"gpt-3.5-turbo-1106"` + - `type: "double_click"` - - `"gpt-3.5-turbo-0125"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"gpt-3.5-turbo-16k-0613"` + - `x: number` - - `"o1-pro"` + The x-coordinate where the double click occurred. - - `"o1-pro-2025-03-19"` + - `y: number` - - `"o3-pro"` + The y-coordinate where the double click occurred. - - `"o3-pro-2025-06-10"` + - `drag: object { path, type, keys }` - - `"o3-deep-research"` + A drag action. - - `"o3-deep-research-2025-06-26"` + - `path: array of object { x, y }` - - `"o4-mini-deep-research"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"o4-mini-deep-research-2025-06-26"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"computer-use-preview"` + - `x: number` - - `"computer-use-preview-2025-03-11"` + The x-coordinate. - - `"gpt-5-codex"` + - `y: number` - - `"gpt-5-pro"` + The y-coordinate. - - `"gpt-5-pro-2025-10-06"` + - `type: "drag"` - - `"gpt-5.1-codex-max"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `object: "response"` + - `keys: optional array of string` - The object type of this resource - always set to `response`. + The keys being held while dragging the mouse. - - `output: array of BetaResponseOutputItem` + - `keypress: object { keys, type }` - An array of content items generated by the model. + A collection of keypresses the model would like to perform. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `keys: array of string` - - `beta_response_output_message: object { id, content, role, 4 more }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - An output message from the model. + - `type: "keypress"` - - `id: string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The unique ID of the output message. + - `move: object { type, x, y, keys }` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + A mouse move action. - The content of the output message. + - `type: "move"` - - `role: "assistant"` + Specifies the event type. For a move action, this property is always set to `move`. - The role of the output message. Always `assistant`. + - `x: number` - - `status: "in_progress" or "completed" or "incomplete"` + The x-coordinate to move to. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `y: number` - - `type: "message"` + The y-coordinate to move to. - The type of the output message. Always `message`. + - `keys: optional array of string` - - `agent: optional object { agent_name }` + The keys being held while moving the mouse. - The agent that produced this item. + - `screenshot: object { type }` - - `phase: optional "commentary"` + A screenshot action. - 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. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + A scroll action. - 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. + - `scroll_x: number` - - `id: string` + The horizontal scroll distance. - The unique ID of the file search tool call. + - `scroll_y: number` - - `queries: array of string` + The vertical scroll distance. - The queries used to search for files. + - `type: "scroll"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `x: number` - - `type: "file_search_call"` + The x-coordinate where the scroll occurred. - The type of the file search tool call. Always `file_search_call`. + - `y: number` - - `agent: optional object { agent_name }` + The y-coordinate where the scroll occurred. - The agent that produced this item. + - `keys: optional array of string` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The keys being held while scrolling. - The results of the file search tool call. + - `type: object { text, type }` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + An action to type in text. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `text: string` - - `arguments: string` + The text to type. - A JSON string of the arguments to pass to the function. + - `type: "type"` - - `call_id: string` + Specifies the event type. For a type action, this property is always set to `type`. - The unique ID of the function tool call generated by the model. + - `wait: object { type }` - - `name: string` + A wait action. - The name of the function to run. + - `actions: optional array of BetaComputerAction` - - `type: "function_call"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the function tool call. Always `function_call`. + - `click: object { button, type, x, 2 more }` - - `id: optional string` + A click action. - The unique ID of the function tool call. + - `double_click: object { keys, type, x, y }` - - `agent: optional object { agent_name }` + A double click action. - The agent that produced this item. + - `drag: object { path, type, keys }` - - `caller: optional object { type } or object { caller_id, type }` + A drag action. - The execution context that produced this tool call. + - `keypress: object { keys, type }` - - `namespace: optional string` + A collection of keypresses the model would like to perform. - The namespace of the function to run. + - `move: object { type, x, y, keys }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A mouse move action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `screenshot: object { type }` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + A screenshot action. - - `id: string` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The unique ID of the function call tool output. + A scroll action. - - `call_id: string` + - `type: object { text, type }` - The unique ID of the function tool call generated by the model. + An action to type in text. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `wait: object { type }` - The output from the function call generated by your code. - Can be a string or an list of output content. + A wait action. - - `string output: string` + - `agent: optional object { agent_name }` - A string of the output of the function call. + The agent that produced this item. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `agent_name: string` - Text, image, or file output of the function call. + The canonical name of the agent that produced this item. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `computer_call_output: object { call_id, output, type, 4 more }` - A text input to the model. + The output of a computer tool call. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `call_id: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The ID of the computer tool call that produced the output. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `output: object { type, file_id, image_url }` - A file input to the model. + A computer screenshot image used with the computer use tool. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "computer_screenshot"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"in_progress"` + - `file_id: optional string` - - `"completed"` + The identifier of an uploaded file that contains the screenshot. - - `"incomplete"` + - `image_url: optional string` - - `type: "function_call_output"` + The URL of the screenshot image. - The type of the function tool call output. Always `function_call_output`. + - `type: "computer_call_output"` - - `agent: optional object { agent_name }` + The type of the computer tool call output. Always `computer_call_output`. - The agent that produced this item. + - `id: optional string` - - `agent_name: string` + The ID of the computer tool call output. - The canonical name of the agent that produced this item. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `caller: optional object { type } or object { caller_id, type }` + The safety checks reported by the API that have been acknowledged by the developer. - The execution context that produced this tool call. + - `id: string` - - `direct: object { type }` + The ID of the pending safety check. - - `program: object { caller_id, type }` + - `code: optional string` - - `caller_id: string` + The type of the pending safety check. - The call ID of the program item that produced this tool call. + - `message: optional string` - - `type: "program"` + Details about the pending safety check. - The caller type. Always `program`. + - `agent: optional object { agent_name }` - - `created_by: optional string` + The agent that produced this item. - The identifier of the actor that created the item. + - `agent_name: string` - - `agent_message: object { id, author, content, 3 more }` + The canonical name of the agent that produced this item. - - `id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The unique ID of the agent message. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `author: string` + - `"in_progress"` - The sending agent identity. + - `"completed"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"incomplete"` - Encrypted content sent between agents. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + 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. - A text input to the model. + - `id: string` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + The unique ID of the web search tool call. - A text output from the model. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `text: object { text, type }` + 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). - A text content. + - `search: object { type, queries, query, sources }` - - `text: string` + Action type "search" - Performs a web search query. - - `type: "text"` + - `type: "search"` - - `summary_text: object { text, type }` + The action type. - A summary text from the model. + - `queries: optional array of string` - - `text: string` + The search queries. - A summary of the reasoning output from the model so far. + - `query: optional string` - - `type: "summary_text"` + The search query. - The type of the object. Always `summary_text`. + - `sources: optional array of object { type, url }` - - `reasoning_text: object { text, type }` + The sources used in the search. - Reasoning text from the model. + - `type: "url"` - - `text: string` + The type of source. Always `url`. - The reasoning text from the model. + - `url: string` - - `type: "reasoning_text"` + The URL of the source. - The type of the reasoning text. Always `reasoning_text`. + - `open_page: object { type, url }` - - `beta_response_output_refusal: object { refusal, type }` + Action type "open_page" - Opens a specific URL from search results. - A refusal from the model. + - `type: "open_page"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The action type. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `url: optional string` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + The URL opened by the model. - A screenshot of a computer. + - `find_in_page: object { pattern, type, url }` - - `detail: "low" or "high" or "auto" or "original"` + Action type "find_in_page": Searches for a pattern within a loaded page. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `pattern: string` - - `"low"` + The pattern or text to search for within the page. - - `"high"` + - `type: "find_in_page"` - - `"auto"` + The action type. - - `"original"` + - `url: string` - - `file_id: string` + The URL of the page searched for the pattern. - The identifier of an uploaded file that contains the screenshot. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `image_url: string` + The status of the web search tool call. - The URL of the screenshot image. + - `"in_progress"` - - `type: "computer_screenshot"` + - `"searching"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"completed"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"failed"` - 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. + - `type: "web_search_call"` - - `mode: "explicit"` + The type of the web search tool call. Always `web_search_call`. - The breakpoint mode. Always `explicit`. + - `agent: optional object { agent_name }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The agent that produced this item. - A file input to the model. + - `agent_name: string` - - `encrypted_content: object { encrypted_content, type }` + The canonical name of the agent that produced this item. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `encrypted_content: string` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Opaque encrypted content. + - `arguments: string` - - `type: "encrypted_content"` + A JSON string of the arguments to pass to the function. - The type of the input item. Always `encrypted_content`. + - `call_id: string` - - `recipient: string` + The unique ID of the function tool call generated by the model. - The destination agent identity. + - `name: string` - - `type: "agent_message"` + The name of the function to run. - The type of the item. Always `agent_message`. + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `id: optional string` + + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -53657,300 +64123,312 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - - `id: string` + The execution context that produced this tool call. - The unique ID of the multi-agent call item. + - `direct: object { type }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `program: object { caller_id, type }` - The multi-agent action to execute. + - `caller_id: string` - - `"spawn_agent"` + The call ID of the program item that produced this tool call. - - `"interrupt_agent"` + - `type: "program"` - - `"list_agents"` + - `namespace: optional string` - - `"send_message"` + The namespace of the function to run. - - `"followup_task"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"wait_agent"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `arguments: string` + - `"in_progress"` - The JSON string of arguments generated for the action. + - `"completed"` + + - `"incomplete"` + + - `function_call_output: object { call_id, output, type, 4 more }` + + The output of a function tool call. - `call_id: string` - The unique ID linking this call to its output. + The unique ID of the function tool call generated by the model. - - `type: "multi_agent_call"` + - `output: string or BetaResponseFunctionCallOutputItemList` - The type of the multi-agent call. Always `multi_agent_call`. + Text, image, or file output of the function tool call. - - `agent: optional object { agent_name }` + - `union_member_0: string` - The agent that produced this item. + A JSON string of the output of the function tool call. - - `agent_name: string` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - The canonical name of the agent that produced this item. + An array of content outputs (text, image, file) for the function tool call. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `id: string` + A text input to the model. - The unique ID of the multi-agent call output item. + - `text: string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The text input to the model. - The multi-agent action that produced this result. + - `type: "input_text"` - - `"spawn_agent"` + The type of the input item. Always `input_text`. - - `"interrupt_agent"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"list_agents"` + 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. - - `"send_message"` + - `mode: "explicit"` - - `"followup_task"` + The breakpoint mode. Always `explicit`. - - `"wait_agent"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `call_id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The unique ID of the multi-agent call. + - `type: "input_image"` - - `output: array of BetaResponseOutputText` + The type of the input item. Always `input_image`. - Text output returned by the multi-agent action. + - `detail: optional "low" or "high" or "auto" or "original"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The annotations of the text output. + - `"low"` - - `text: string` + - `"high"` - The text output from the model. + - `"auto"` - - `type: "output_text"` + - `"original"` - The type of the output text. Always `output_text`. + - `file_id: optional string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The ID of the file to be sent to the model. - - `type: "multi_agent_call_output"` + - `image_url: optional string` - The type of the multi-agent result. Always `multi_agent_call_output`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent: optional object { agent_name }` + - `prompt_cache_breakpoint: optional object { mode }` - The agent that produced this item. + 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. - - `agent_name: string` + - `mode: "explicit"` - The canonical name of the agent that produced this item. + The breakpoint mode. Always `explicit`. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - 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. + A file input to the model. - - `id: string` + - `type: "input_file"` - The unique ID of the web search tool call. + The type of the input item. Always `input_file`. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `detail: optional "auto" or "low" or "high"` - 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). + 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`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"auto"` - The status of the web search tool call. + - `"low"` - - `type: "web_search_call"` + - `"high"` - The type of the web search tool call. Always `web_search_call`. + - `file_data: optional string` - - `agent: optional object { agent_name }` + The base64-encoded data of the file to be sent to the model. - The agent that produced this item. + - `file_id: optional string` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + The ID of the file to be sent to the model. - 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. + - `file_url: optional string` - - `id: string` + The URL of the file to be sent to the model. - The unique ID of the computer call. + - `filename: optional string` - - `call_id: string` + The name of the file to be sent to the model. - An identifier used when responding to the tool call with output. + - `prompt_cache_breakpoint: optional object { mode }` - - `pending_safety_checks: array of object { id, code, message }` + 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. - The pending safety checks for the computer call. + - `mode: "explicit"` - - `status: "in_progress" or "completed" or "incomplete"` + The breakpoint mode. Always `explicit`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "function_call_output"` - - `type: "computer_call"` + The type of the function tool call output. Always `function_call_output`. - The type of the computer call. Always `computer_call`. + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `direct: object { type }` - A click action. + - `program: object { caller_id, type }` - - `actions: optional array of BetaComputerAction` + - `caller_id: string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The call ID of the program item that produced this tool call. - - `agent: optional object { agent_name }` + - `type: "program"` - The agent that produced this item. + The caller type. Always `program`. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The unique ID of the computer call tool output. + - `"in_progress"` - - `call_id: string` + - `"completed"` - The ID of the computer tool call that produced the output. + - `"incomplete"` - - `output: object { type, file_id, image_url }` + - `agent_message: object { author, content, recipient, 3 more }` - A computer screenshot image used with the computer use tool. + A message routed between agents. - - `type: "computer_screenshot"` + - `author: string` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The sending agent identity. - - `file_id: optional string` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - The identifier of an uploaded file that contains the screenshot. + Plaintext, image, or encrypted content sent between agents. - - `image_url: optional string` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - The URL of the screenshot image. + A text input to the model. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `text: string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The text input to the model. - - `"completed"` + - `type: "input_text"` - - `"incomplete"` + The type of the input item. Always `input_text`. - - `"failed"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"in_progress"` + 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. - - `type: "computer_call_output"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The type of the computer tool call output. Always `computer_call_output`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "input_image"` - The safety checks reported by the API that have been acknowledged by the - developer. + The type of the input item. Always `input_image`. - - `id: string` + - `detail: optional "low" or "high" or "auto" or "original"` - The ID of the pending safety check. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `code: optional string` + - `file_id: optional string` - The type of the pending safety check. + The ID of the file to be sent to the model. - - `message: optional string` + - `image_url: optional string` - Details about the pending safety check. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent: optional object { agent_name }` + - `prompt_cache_breakpoint: optional object { mode }` - The agent that produced this item. + 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. - - `agent_name: string` + - `encrypted_content: object { encrypted_content, type }` - The canonical name of the agent that produced this item. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `created_by: optional string` + - `encrypted_content: string` - The identifier of the actor that created the item. + Opaque encrypted content. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `type: "encrypted_content"` - 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). + The type of the input item. Always `encrypted_content`. - - `id: string` + - `recipient: string` - The unique identifier of the reasoning content. + The destination agent identity. - - `summary: array of object { text, type }` + - `type: "agent_message"` - Reasoning summary content. + The item type. Always `agent_message`. - - `type: "reasoning"` + - `id: optional string` - The type of the object. Always `reasoning`. + The unique ID of this agent message item. - `agent: optional object { agent_name }` The agent that produced this item. - - `content: optional array of object { text, type }` + - `agent_name: string` - Reasoning text content. + The canonical name of the agent that produced this item. - - `encrypted_content: optional string` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + The multi-agent action that was executed. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"spawn_agent"` - - `program: object { id, call_id, code, 3 more }` + - `"interrupt_agent"` - - `id: string` + - `"list_agents"` - The unique ID of the program item. + - `"send_message"` - - `call_id: string` + - `"followup_task"` - The stable call ID of the program item. + - `"wait_agent"` - - `code: string` + - `arguments: string` - The JavaScript source executed by programmatic tool calling. + The action arguments as a JSON string. - - `fingerprint: string` + - `call_id: string` - Opaque program replay fingerprint that must be round-tripped. + The unique ID linking this call to its output. - - `type: "program"` + - `type: "multi_agent_call"` - The type of the item. Always `program`. + The item type. Always `multi_agent_call`. + + - `id: optional string` + + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -53960,1241 +64438,1261 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `program_output: object { id, call_id, result, 3 more }` + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - `id: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The unique ID of the program output item. + The multi-agent action that produced this result. - - `call_id: string` + - `"spawn_agent"` - The call ID of the program item. + - `"interrupt_agent"` - - `result: string` + - `"list_agents"` - The result produced by the program item. + - `"send_message"` - - `status: "completed" or "incomplete"` + - `"followup_task"` - The terminal status of the program output item. + - `"wait_agent"` - - `"completed"` + - `call_id: string` - - `"incomplete"` + The unique ID of the multi-agent call. - - `type: "program_output"` + - `output: array of object { text, type, annotations }` - The type of the item. Always `program_output`. + Text output returned by the multi-agent action. - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The text content. - - `agent_name: string` + - `type: "output_text"` - The canonical name of the agent that produced this item. + The content type. Always `output_text`. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `id: string` + Citations associated with the text content. - The unique ID of the tool search call item. + - `union_member_0: array of object { file_id, filename, index, type }` - - `arguments: unknown` + - `file_id: string` - Arguments used for the tool search call. + The ID of the file. - - `call_id: string` + - `filename: string` - The unique ID of the tool search call generated by the model. + The filename of the file cited. - - `execution: "server" or "client"` + - `index: number` - Whether tool search was executed by the server or by the client. + The index of the file in the list of files. - - `"server"` + - `type: "file_citation"` - - `"client"` + The citation type. Always `file_citation`. - - `status: "in_progress" or "completed" or "incomplete"` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - The status of the tool search call item that was recorded. + - `end_index: number` - - `"in_progress"` + The index of the last character of the citation in the message. - - `"completed"` + - `start_index: number` - - `"incomplete"` + The index of the first character of the citation in the message. - - `type: "tool_search_call"` + - `title: string` - The type of the item. Always `tool_search_call`. + The title of the cited resource. - - `agent: optional object { agent_name }` + - `type: "url_citation"` - The agent that produced this item. + The citation type. Always `url_citation`. - - `agent_name: string` + - `url: string` - The canonical name of the agent that produced this item. + The URL of the cited resource. - - `created_by: optional string` + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - The identifier of the actor that created the item. + - `container_id: string` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + The ID of the container. - - `id: string` + - `end_index: number` - The unique ID of the tool search output item. + The index of the last character of the citation in the message. - - `call_id: string` + - `file_id: string` - The unique ID of the tool search call generated by the model. + The ID of the container file. - - `execution: "server" or "client"` + - `filename: string` - Whether tool search was executed by the server or by the client. + The filename of the container file cited. - - `"server"` + - `start_index: number` - - `"client"` + The index of the first character of the citation in the message. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "container_file_citation"` - The status of the tool search output item that was recorded. + The citation type. Always `container_file_citation`. - - `"in_progress"` + - `type: "multi_agent_call_output"` - - `"completed"` + The item type. Always `multi_agent_call_output`. - - `"incomplete"` + - `id: optional string` - - `tools: array of BetaTool` + The unique ID of this multi-agent call output. - The loaded tool definitions returned by tool search. + - `agent: optional object { agent_name }` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The agent that produced this item. - 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). + - `agent_name: string` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The canonical name of the agent that produced this item. - 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). + - `tool_search_call: object { arguments, type, id, 4 more }` - - `beta_computer_tool: object { type }` + - `arguments: unknown` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The arguments supplied to the tool search call. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `type: "tool_search_call"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The item type. Always `tool_search_call`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `id: optional string` - 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). + The unique ID of this tool search call. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `agent: optional object { agent_name }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The agent that produced this item. - - `code_interpreter: object { container, type, allowed_callers }` + - `agent_name: string` - A tool that runs Python code to help generate a response to a prompt. + The canonical name of the agent that produced this item. - - `programmatic_tool_calling: object { type }` + - `call_id: optional string` - - `image_generation: object { type, action, background, 9 more }` + The unique ID of the tool search call generated by the model. - A tool that generates images using the GPT image models. + - `execution: optional "server" or "client"` - - `local_shell: object { type }` + Whether tool search was executed by the server or by the client. - A tool that allows the model to execute shell commands in a local environment. + - `"server"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `"client"` - A tool that allows the model to execute shell commands. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The status of the tool search call. - 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) + - `"in_progress"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `"completed"` - Groups function/custom tools under a shared namespace. + - `"incomplete"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - Hosted or BYOT tool search configuration for deferred tools. + - `tools: array of BetaTool` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The loaded tool definitions returned by the tool search output. - 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). + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `beta_apply_patch_tool: object { type, allowed_callers }` + 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). - Allows the assistant to create, delete, or update files using unified diffs. + - `name: string` - - `type: "tool_search_output"` + The name of the function to call. - The type of the item. Always `tool_search_output`. + - `parameters: map[unknown]` - - `agent: optional object { agent_name }` + A JSON schema object describing the parameters of the function. - The agent that produced this item. + - `strict: boolean` - - `agent_name: string` + Whether strict parameter validation is enforced for this function tool. - The canonical name of the agent that produced this item. + - `type: "function"` - - `created_by: optional string` + The type of the function tool. Always `function`. - The identifier of the actor that created the item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `additional_tools: object { id, role, tools, 2 more }` + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique ID of the additional tools item. + - `"programmatic"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `defer_loading: optional boolean` - The role that provided the additional tools. + Whether this function is deferred and loaded via tool search. - - `"unknown"` + - `description: optional string` - - `"user"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"assistant"` + - `output_schema: optional map[unknown]` - - `"system"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"critic"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"discriminator"` + 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). - - `"developer"` + - `type: "file_search"` - - `"tool"` + The type of the file search tool. Always `file_search`. - - `tools: array of BetaTool` + - `vector_store_ids: array of string` - The additional tool definitions made available at this item. + The IDs of the vector stores to search. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `filters: optional object { key, type, value } or object { filters, type }` - 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). + A filter to apply. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `Comparison Filter: object { key, type, value }` - 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). + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `beta_computer_tool: object { type }` + - `key: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The key to compare against the value. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `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 - 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). + - `"eq"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `"ne"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"gt"` - - `code_interpreter: object { container, type, allowed_callers }` + - `"gte"` - A tool that runs Python code to help generate a response to a prompt. + - `"lt"` - - `programmatic_tool_calling: object { type }` + - `"lte"` - - `image_generation: object { type, action, background, 9 more }` + - `"in"` - A tool that generates images using the GPT image models. + - `"nin"` - - `local_shell: object { type }` + - `value: string or number or boolean or array of string or number` - A tool that allows the model to execute shell commands in a local environment. + The value to compare against the attribute key; supports string, number, or boolean types. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `union_member_0: string` - A tool that allows the model to execute shell commands. + - `union_member_1: number` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `union_member_2: boolean` - 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) + - `union_member_3: array of string or number` - - `beta_namespace_tool: object { description, name, tools, type }` + - `union_member_0: string` - Groups function/custom tools under a shared namespace. + - `union_member_1: number` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `Compound Filter: object { filters, type }` - Hosted or BYOT tool search configuration for deferred tools. + Combine multiple filters using `and` or `or`. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `filters: array of object { key, type, value } or unknown` - 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). + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `Comparison Filter: object { key, type, value }` - Allows the assistant to create, delete, or update files using unified diffs. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "additional_tools"` + - `key: string` - The type of the item. Always `additional_tools`. + The key to compare against the value. - - `agent: optional object { agent_name }` + - `type: "eq" or "ne" or "gt" or 5 more` - The agent that produced this item. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent_name: string` + - `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 - The canonical name of the agent that produced this item. + - `"eq"` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `"ne"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"gt"` - - `id: string` + - `"gte"` - The unique ID of the compaction item. + - `"lt"` - - `encrypted_content: string` + - `"lte"` - The encrypted content that was produced by compaction. + - `"in"` - - `type: "compaction"` + - `"nin"` - The type of the item. Always `compaction`. + - `value: string or number or boolean or array of string or number` - - `agent: optional object { agent_name }` + The value to compare against the attribute key; supports string, number, or boolean types. - The agent that produced this item. + - `union_member_0: string` - - `agent_name: string` + - `union_member_1: number` - The canonical name of the agent that produced this item. + - `union_member_2: boolean` - - `created_by: optional string` + - `union_member_3: array of string or number` - The identifier of the actor that created the item. + - `union_member_0: string` - - `image_generation_call: object { id, result, status, 2 more }` + - `union_member_1: number` - An image generation request made by the model. + - `union_member_1: unknown` - - `id: string` + - `type: "and" or "or"` - The unique ID of the image generation call. + Type of operation: `and` or `or`. - - `result: string` + - `"and"` - The generated image encoded in base64. + - `"or"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `max_num_results: optional number` - The status of the image generation call. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"in_progress"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"completed"` + Ranking options for search. - - `"generating"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"failed"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: "image_generation_call"` + - `embedding_weight: number` - The type of the image generation call. Always `image_generation_call`. + The weight of the embedding in the reciprocal ranking fusion. - - `agent: optional object { agent_name }` + - `text_weight: number` - The agent that produced this item. + The weight of the text in the reciprocal ranking fusion. - - `agent_name: string` + - `ranker: optional "auto" or "default-2024-11-15"` - The canonical name of the agent that produced this item. + The ranker to use for the file search. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `"auto"` - A tool call to run code. + - `"default-2024-11-15"` - - `id: string` + - `score_threshold: optional number` - The unique ID of the code interpreter tool call. + 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. - - `code: string` + - `beta_computer_tool: object { type }` - The code to run, or null if not available. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `container_id: string` + - `type: "computer"` - The ID of the container used to run the code. + The type of the computer tool. Always `computer`. - - `outputs: array of object { logs, type } or object { type, url }` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `display_height: number` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The height of the computer display. - - `type: "code_interpreter_call"` + - `display_width: number` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The width of the computer display. - - `agent: optional object { agent_name }` + - `environment: "windows" or "mac" or "linux" or 2 more` - The agent that produced this item. + The type of computer environment to control. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `"windows"` - A tool call to run a command on the local shell. + - `"mac"` - - `id: string` + - `"linux"` - The unique ID of the local shell call. + - `"ubuntu"` - - `action: object { command, env, type, 3 more }` + - `"browser"` - Execute a shell command on the server. + - `type: "computer_use_preview"` - - `command: array of string` + The type of the computer use tool. Always `computer_use_preview`. - The command to run. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `env: map[string]` + 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). - Environment variables to set for the command. + - `type: "web_search" or "web_search_2025_08_26"` - - `type: "exec"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The type of the local shell action. Always `exec`. + - `"web_search"` - - `timeout_ms: optional number` + - `"web_search_2025_08_26"` - Optional timeout in milliseconds for the command. + - `filters: optional object { allowed_domains }` - - `user: optional string` + Filters for the search. - Optional user to run the command as. + - `allowed_domains: optional array of string` - - `working_directory: optional string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Optional working directory to run the command in. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `call_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The unique ID of the local shell tool call generated by the model. + 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. - - `status: "in_progress" or "completed" or "incomplete"` + - `"low"` - The status of the local shell call. + - `"medium"` - - `"in_progress"` + - `"high"` - - `"completed"` + - `user_location: optional object { city, country, region, 2 more }` - - `"incomplete"` + The approximate location of the user. - - `type: "local_shell_call"` + - `city: optional string` - The type of the local shell call. Always `local_shell_call`. + Free text input for the city of the user, e.g. `San Francisco`. - - `agent: optional object { agent_name }` + - `country: optional string` - The agent that produced this item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `agent_name: string` + - `region: optional string` - The canonical name of the agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `timezone: optional string` - The output of a local shell tool call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `id: string` + - `type: optional "approximate"` - The unique ID of the local shell tool call generated by the model. + The type of location approximation. Always `approximate`. - - `output: string` + - `"approximate"` - A JSON string of the output of the local shell tool call. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `type: "local_shell_call_output"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The type of the local shell tool call output. Always `local_shell_call_output`. + - `server_label: string` - - `agent: optional object { agent_name }` + A label for this MCP server, used to identify it in tool calls. - The agent that produced this item. + - `type: "mcp"` - - `agent_name: string` + The type of the MCP tool. Always `mcp`. - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The tool invocation context(s). - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"incomplete"` + List of allowed tool names or a filter object. - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `MCP allowed tools: array of string` - A tool call that executes one or more shell commands in a managed environment. + A string array of allowed tool names - - `id: string` + - `MCP tool filter: object { read_only, tool_names }` - The unique ID of the shell tool call. Populated when this item is returned via API. + A filter object to specify which tools are allowed. - - `action: object { commands, max_output_length, timeout_ms }` + - `read_only: optional boolean` - The shell commands and limits that describe how to run the tool call. + 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. - - `commands: array of string` + - `tool_names: optional array of string` - - `max_output_length: number` + List of allowed tool names. - Optional maximum number of characters to return from each command. + - `authorization: optional string` - - `timeout_ms: number` + 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 timeout in milliseconds for the commands. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `call_id: string` + 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). - The unique ID of the shell tool call generated by the model. + Currently supported `connector_id` values are: - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - 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` - Represents the use of a local environment to perform shell actions. + - `"connector_dropbox"` - - `beta_response_local_environment: object { type }` + - `"connector_gmail"` - Represents the use of a local environment to perform shell actions. + - `"connector_googlecalendar"` - - `type: "local"` + - `"connector_googledrive"` - The environment type. Always `local`. + - `"connector_microsoftteams"` - - `beta_response_container_reference: object { container_id, type }` + - `"connector_outlookcalendar"` - Represents a container created with /v1/containers. + - `"connector_outlookemail"` - - `container_id: string` + - `"connector_sharepoint"` - - `type: "container_reference"` + - `defer_loading: optional boolean` - The environment type. Always `container_reference`. + Whether this MCP tool is deferred and discovered via tool search. - - `status: "in_progress" or "completed" or "incomplete"` + - `headers: optional map[string]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"in_progress"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"completed"` + Specify which of the MCP server's tools require approval. - - `"incomplete"` + - `MCP tool approval filter: object { always, never }` - - `type: "shell_call"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The type of the item. Always `shell_call`. + - `always: optional object { read_only, tool_names }` - - `agent: optional object { agent_name }` + A filter object to specify which tools are allowed. - The agent that produced this item. + - `read_only: optional boolean` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `tool_names: optional array of string` - - `caller: optional object { type } or object { caller_id, type }` + List of allowed tool names. - The execution context that produced this tool call. + - `never: optional object { read_only, tool_names }` - - `direct: object { type }` + A filter object to specify which tools are allowed. - - `program: object { caller_id, type }` + - `read_only: optional boolean` - - `caller_id: string` + 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. - The call ID of the program item that produced this tool call. + - `tool_names: optional array of string` - - `type: "program"` + List of allowed tool names. - - `created_by: optional string` + - `MCP tool approval setting: "always" or "never"` - The ID of the entity that created this tool call. + 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. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `"always"` - The output of a shell tool call that was emitted. + - `"never"` - - `id: string` + - `server_description: optional string` - The unique ID of the shell call output. Populated when this item is returned via API. + Optional description of the MCP server, used to provide more context. - - `call_id: string` + - `server_url: optional string` - The unique ID of the shell tool call generated by the model. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `max_output_length: number` + - `tunnel_id: optional string` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + 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. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `code_interpreter: object { container, type, allowed_callers }` - An array of shell call output contents + A tool that runs Python code to help generate a response to a prompt. - - `outcome: object { type } or object { exit_code, type }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + 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. - - `timeout: object { type }` + - `union_member_0: string` - Indicates that the shell call exceeded its configured time limit. + The container ID. - - `exit: object { exit_code, type }` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - Indicates that the shell commands finished and returned an exit code. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `exit_code: number` + - `type: "auto"` - Exit code from the shell process. + Always `auto`. - - `type: "exit"` + - `file_ids: optional array of string` - The outcome type. Always `exit`. + An optional list of uploaded files to make available to your code. - - `stderr: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The standard error output that was captured. + The memory limit for the code interpreter container. - - `stdout: string` + - `"1g"` - The standard output that was captured. + - `"4g"` - - `created_by: optional string` + - `"16g"` - The identifier of the actor that created the item. + - `"64g"` - - `status: "in_progress" or "completed" or "incomplete"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Network access policy for the container. - - `"in_progress"` + - `beta_container_network_policy_disabled: object { type }` - - `"completed"` + - `type: "disabled"` - - `"incomplete"` + Disable outbound network access. Always `disabled`. - - `type: "shell_call_output"` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The type of the shell call output. Always `shell_call_output`. + - `allowed_domains: array of string` - - `agent: optional object { agent_name }` + A list of allowed domains when type is `allowlist`. - The agent that produced this item. + - `type: "allowlist"` - - `agent_name: string` + Allow outbound network access only to specified domains. Always `allowlist`. - The canonical name of the agent that produced this item. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `caller: optional object { type } or object { caller_id, type }` + Optional domain-scoped secrets for allowlisted domains. - The execution context that produced this tool call. + - `domain: string` - - `direct: object { type }` + The domain associated with the secret. - - `program: object { caller_id, type }` + - `name: string` - - `caller_id: string` + The name of the secret to inject for the domain. - The call ID of the program item that produced this tool call. + - `value: string` - - `type: "program"` + The secret value to inject for the domain. - - `created_by: optional string` + - `type: "code_interpreter"` - The identifier of the actor that created the item. + The type of the code interpreter tool. Always `code_interpreter`. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A tool call that applies file diffs by creating, deleting, or updating files. + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"programmatic"` - - `call_id: string` + - `programmatic_tool_calling: object { type }` - The unique ID of the apply patch tool call generated by the model. + - `image_generation: object { type, action, background, 9 more }` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + A tool that generates images using the GPT image models. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `type: "image_generation"` - - `create_file: object { diff, path, type }` + The type of the image generation tool. Always `image_generation`. - Instruction describing how to create a file via the apply_patch tool. + - `action: optional "generate" or "edit" or "auto"` - - `diff: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - Diff to apply. + - `"generate"` - - `path: string` + - `"edit"` - Path of the file to create. + - `"auto"` - - `type: "create_file"` + - `background: optional "transparent" or "opaque" or "auto"` - Create a new file with the provided diff. + 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. - - `delete_file: object { path, type }` + `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. - Instruction describing how to delete a file via the apply_patch tool. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `path: string` + - `"transparent"` - Path of the file to delete. + - `"opaque"` - - `type: "delete_file"` + - `"auto"` - Delete the specified file. + - `input_fidelity: optional "high" or "low"` - - `update_file: object { diff, path, type }` + 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`. - Instruction describing how to update a file via the apply_patch tool. + - `"high"` - - `diff: string` + - `"low"` - Diff to apply. + - `input_image_mask: optional object { file_id, image_url }` - - `path: string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Path of the file to update. + - `file_id: optional string` - - `type: "update_file"` + File ID for the mask image. - Update an existing file with the provided diff. + - `image_url: optional string` - - `status: "in_progress" or "completed"` + Base64-encoded mask image. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `"in_progress"` + The image generation model to use. Default: `gpt-image-1`. - - `"completed"` + - `"gpt-image-1"` - - `type: "apply_patch_call"` + - `"gpt-image-1-mini"` - The type of the item. Always `apply_patch_call`. + - `"gpt-image-2"` - - `agent: optional object { agent_name }` + - `"gpt-image-2-2026-04-21"` - The agent that produced this item. + - `"gpt-image-1.5"` - - `agent_name: string` + - `"chatgpt-image-latest"` - The canonical name of the agent that produced this item. + - `moderation: optional "auto" or "low"` - - `caller: optional object { type } or object { caller_id, type }` + Moderation level for the generated image. Default: `auto`. - The execution context that produced this tool call. + - `"auto"` - - `direct: object { type }` + - `"low"` - - `program: object { caller_id, type }` + - `output_compression: optional number` - - `caller_id: string` + Compression level for the output image. Default: 100. - The call ID of the program item that produced this tool call. + - `output_format: optional "png" or "webp" or "jpeg"` - - `type: "program"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `created_by: optional string` + - `"png"` - The ID of the entity that created this tool call. + - `"webp"` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `"jpeg"` - The output emitted by an apply patch tool call. + - `partial_images: optional number` - - `id: string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `call_id: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The unique ID of the apply patch tool call generated by the model. + - `"low"` - - `status: "completed" or "failed"` + - `"medium"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"high"` - - `"completed"` + - `"auto"` - - `"failed"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "apply_patch_call_output"` + 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`. - The type of the item. Always `apply_patch_call_output`. + - `"1024x1024"` - - `agent: optional object { agent_name }` + - `"1024x1536"` - The agent that produced this item. + - `"1536x1024"` - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `local_shell: object { type }` - - `caller: optional object { type } or object { caller_id, type }` + A tool that allows the model to execute shell commands in a local environment. - The execution context that produced this tool call. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `direct: object { type }` + A tool that allows the model to execute shell commands. - - `program: object { caller_id, type }` + - `type: "shell"` - - `caller_id: string` + The type of the shell tool. Always `shell`. - The call ID of the program item that produced this tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "program"` + The tool invocation context(s). - - `created_by: optional string` + - `"direct"` - The ID of the entity that created this tool call output. + - `"programmatic"` - - `output: optional string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - Optional textual output returned by the apply patch tool. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `mcp_call: object { id, arguments, name, 7 more }` + - `type: "container_auto"` - An invocation of a tool on an MCP server. + Automatically creates a container for this request - - `id: string` + - `file_ids: optional array of string` - The unique ID of the tool call. + An optional list of uploaded files to make available to your code. - - `arguments: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - A JSON string of the arguments passed to the tool. + The memory limit for the container. - - `name: string` + - `"1g"` - The name of the tool that was run. + - `"4g"` - - `server_label: string` + - `"16g"` - The label of the MCP server running the tool. + - `"64g"` - - `type: "mcp_call"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The type of the item. Always `mcp_call`. + Network access policy for the container. - - `agent: optional object { agent_name }` + - `beta_container_network_policy_disabled: object { type }` - The agent that produced this item. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `agent_name: string` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The canonical name of the agent that produced this item. + An optional list of skills referenced by id or inline data. - - `approval_request_id: optional string` + - `beta_skill_reference: object { skill_id, type, version }` - 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. + - `skill_id: string` - - `error: optional string` + The ID of the referenced skill. - The error from the tool call, if any. + - `type: "skill_reference"` - - `output: optional string` + References a skill created with the /v1/skills endpoint. - The output from the tool call. + - `version: optional string` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `beta_inline_skill: object { description, name, source, type }` - - `"in_progress"` + - `description: string` - - `"completed"` + The description of the skill. - - `"incomplete"` + - `name: string` - - `"calling"` + The name of the skill. - - `"failed"` + - `source: object { data, media_type, type }` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + Inline skill payload - A list of tools available on an MCP server. + - `data: string` - - `id: string` + Base64-encoded skill zip bundle. - The unique ID of the list. + - `media_type: "application/zip"` - - `server_label: string` + The media type of the inline skill payload. Must be `application/zip`. - The label of the MCP server. + - `type: "base64"` - - `tools: array of object { input_schema, name, annotations, description }` + The type of the inline skill source. Must be `base64`. - The tools available on the server. + - `type: "inline"` - - `input_schema: unknown` + Defines an inline skill for this request. - The JSON schema describing the tool's input. + - `beta_local_environment: object { type, skills }` - - `name: string` + - `type: "local"` - The name of the tool. + Use a local computer environment. - - `annotations: optional unknown` + - `skills: optional array of BetaLocalSkill` - Additional annotations about the tool. + An optional list of skills. - - `description: optional string` + - `description: string` - The description of the tool. + The description of the skill. - - `type: "mcp_list_tools"` + - `name: string` - The type of the item. Always `mcp_list_tools`. + The name of the skill. - - `agent: optional object { agent_name }` + - `path: string` - The agent that produced this item. + The path to the directory containing the skill. - - `agent_name: string` + - `beta_container_reference: object { container_id, type }` - The canonical name of the agent that produced this item. + - `container_id: string` - - `error: optional string` + The ID of the referenced container. - Error message if the server could not list tools. + - `type: "container_reference"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + References a container created with the /v1/containers endpoint - A request for human approval of a tool invocation. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `id: string` + 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) - The unique ID of the approval request. + - `name: string` - - `arguments: string` + The name of the custom tool, used to identify it in tool calls. - A JSON string of arguments for the tool. + - `type: "custom"` - - `name: string` + The type of the custom tool. Always `custom`. - The name of the tool to run. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `server_label: string` + The tool invocation context(s). - The label of the MCP server making the request. + - `"direct"` - - `type: "mcp_approval_request"` + - `"programmatic"` - The type of the item. Always `mcp_approval_request`. + - `defer_loading: optional boolean` - - `agent: optional object { agent_name }` + Whether this tool should be deferred and discovered via tool search. - The agent that produced this item. + - `description: optional string` - - `agent_name: string` + Optional description of the custom tool, used to provide more context. - The canonical name of the agent that produced this item. + - `format: optional object { type } or object { definition, syntax, type }` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + The input format for the custom tool. Default is unconstrained text. - A response to an MCP approval request. + - `text: object { type }` - - `id: string` + Unconstrained free-form text. - The unique ID of the approval response + - `grammar: object { definition, syntax, type }` - - `approval_request_id: string` + A grammar defined by the user. - The ID of the approval request being answered. + - `definition: string` - - `approve: boolean` + The grammar definition. - Whether the request was approved. + - `syntax: "lark" or "regex"` - - `type: "mcp_approval_response"` + The syntax of the grammar definition. One of `lark` or `regex`. - The type of the item. Always `mcp_approval_response`. + - `"lark"` - - `agent: optional object { agent_name }` + - `"regex"` - The agent that produced this item. + - `type: "grammar"` - - `agent_name: string` + Grammar format. Always `grammar`. - The canonical name of the agent that produced this item. + - `beta_namespace_tool: object { description, name, tools, type }` - - `reason: optional string` + Groups function/custom tools under a shared namespace. - Optional reason for the decision. + - `description: string` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + A description of the namespace shown to the model. - A call to a custom tool created by the model. + - `name: string` - - `call_id: string` + The namespace name used in tool calls (for example, `crm`). - An identifier used to map this custom tool call to a tool call output. + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `input: string` + The function/custom tools available inside this namespace. - The input for the custom tool call generated by the model. + - `function: object { name, type, allowed_callers, 5 more }` - `name: string` - The name of the custom tool being called. + - `type: "function"` - - `type: "custom_tool_call"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the custom tool call. Always `custom_tool_call`. + The tool invocation context(s). - - `id: optional string` + - `"direct"` - The unique ID of the custom tool call in the OpenAI platform. + - `"programmatic"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that produced this item. + Whether this function should be deferred and discovered via tool search. - - `caller: optional object { type } or object { caller_id, type }` + - `description: optional string` - The execution context that produced this tool call. + - `output_schema: optional map[unknown]` - - `namespace: optional string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The namespace of the custom tool being called. + - `parameters: optional unknown` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `strict: optional boolean` - The output of a custom tool call from your code, being sent back to the model. + 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. - - `id: string` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The unique ID of the custom tool call output item. + 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) - - `status: "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the custom tool, used to identify it in tool calls. - - `"in_progress"` + - `type: "custom"` - - `"completed"` + The type of the custom tool. Always `custom`. - - `"incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `created_by: optional string` + The tool invocation context(s). - The identifier of the actor that created the item. + - `defer_loading: optional boolean` - - `parallel_tool_calls: boolean` + Whether this tool should be deferred and discovered via tool search. - Whether to allow the model to run tool calls in parallel. + - `description: optional string` - - `temperature: number` + Optional description of the custom tool, used to provide more context. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `format: optional object { type } or object { definition, syntax, type }` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The input format for the custom tool. Default is unconstrained text. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `type: "namespace"` - - `beta_tool_choice_options: "none" or "auto" or "required"` + The type of the tool. Always `namespace`. - Controls which (if any) tool is called by the model. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - `none` means the model will not call any tool and instead generates a message. + Hosted or BYOT tool search configuration for deferred tools. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `type: "tool_search"` - `required` means the model must call one or more tools. + The type of the tool. Always `tool_search`. - - `"none"` + - `description: optional string` - - `"auto"` + Description shown to the model for a client-executed tool search tool. - - `"required"` + - `execution: optional "server" or "client"` - - `beta_tool_choice_allowed: object { mode, tools, type }` + Whether tool search is executed by the server or by the client. - Constrains the tools available to the model to a pre-defined set. + - `"server"` - - `mode: "auto" or "required"` + - `"client"` - Constrains the tools available to the model to a pre-defined set. + - `parameters: optional unknown` - `auto` allows the model to pick from among the allowed tools and generate a - message. + Parameter schema for a client-executed tool search tool. - `required` requires the model to call one or more of the allowed tools. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"auto"` + 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). - - `"required"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `tools: array of map[unknown]` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A list of tool definitions that the model should be allowed to call. + - `"web_search_preview"` - For the Responses API, the list of tool definitions might look like: + - `"web_search_preview_2025_03_11"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `search_content_types: optional array of "text" or "image"` - - `type: "allowed_tools"` + - `"text"` - Allowed tool configuration type. Always `allowed_tools`. + - `"image"` - - `beta_tool_choice_types: object { type }` + - `search_context_size: optional "low" or "medium" or "high"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + 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. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `"low"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `"medium"` - Allowed values are: + - `"high"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `user_location: optional object { type, city, country, 2 more }` - - `"file_search"` + The user's location. - - `"web_search_preview"` + - `type: "approximate"` - - `"computer"` + The type of location approximation. Always `approximate`. - - `"computer_use_preview"` + - `city: optional string` - - `"computer_use"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"web_search_preview_2025_03_11"` + - `country: optional string` - - `"image_generation"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"code_interpreter"` + - `region: optional string` - - `beta_tool_choice_function: object { name, type }` + Free text input for the region of the user, e.g. `California`. - Use this option to force the model to call a specific function. + - `timezone: optional string` - - `name: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The name of the function to call. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `type: "function"` + Allows the assistant to create, delete, or update files using unified diffs. - For function calling, the type is always `function`. + - `type: "apply_patch"` - - `beta_tool_choice_mcp: object { server_label, type, name }` + The type of the tool. Always `apply_patch`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `server_label: string` + The tool invocation context(s). - The label of the MCP server to use. + - `"direct"` - - `type: "mcp"` + - `"programmatic"` - For MCP tools, the type is always `mcp`. + - `type: "tool_search_output"` - - `name: optional string` + The item type. Always `tool_search_output`. - The name of the tool to call on the server. + - `id: optional string` - - `beta_tool_choice_custom: object { name, type }` + The unique ID of this tool search output. - Use this option to force the model to call a specific custom tool. + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The name of the custom tool to call. + - `agent_name: string` - - `type: "custom"` + The canonical name of the agent that produced this item. - For custom tool calling, the type is always `custom`. + - `call_id: optional string` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + The unique ID of the tool search call generated by the model. - - `beta_tool_choice_apply_patch: object { type }` + - `execution: optional "server" or "client"` - Forces the model to call the apply_patch tool when executing a tool call. + Whether tool search was executed by the server or by the client. - - `type: "apply_patch"` + - `"server"` - The tool to call. Always `apply_patch`. + - `"client"` - - `beta_tool_choice_shell: object { type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Forces the model to call the shell tool when a tool call is required. + The status of the tool search output. - - `type: "shell"` + - `"in_progress"` - The tool to call. Always `shell`. + - `"completed"` - - `tools: array of BetaTool` + - `"incomplete"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `additional_tools: object { role, tools, type, 2 more }` - We support the following categories of tools: + - `role: "developer"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The role that provided the additional tools. Only `developer` is supported. + + - `tools: array of BetaTool` + + A list of additional tools made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -55260,770 +65758,691 @@ openai beta:responses compact \ Allows the assistant to create, delete, or update files using unified diffs. - - `top_p: number` - - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. - - We generally recommend altering this or `temperature` but not both. - - - `background: optional boolean` - - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `type: "additional_tools"` - - `completed_at: optional number` + The item type. Always `additional_tools`. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `id: optional string` - - `conversation: optional object { id }` + The unique ID of this additional tools item. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - The unique ID of the conversation that this response was associated with. + - `agent_name: string` - - `max_output_tokens: optional number` + The canonical name of the agent that produced this item. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `max_tool_calls: optional number` + 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). - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `id: string` - - `moderation: optional object { input, output }` + The unique identifier of the reasoning content. - Moderation results for the response input and output, if moderated completions were requested. + - `summary: array of object { text, type }` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + Reasoning summary content. - Moderation for the response input. + - `text: string` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + A summary of the reasoning output from the model so far. - A moderation result produced for the response input or output. + - `type: "summary_text"` - - `categories: map[boolean]` + The type of the object. Always `summary_text`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `type: "reasoning"` - - `category_applied_input_types: map[array of "text" or "image"]` + The type of the object. Always `reasoning`. - Which modalities of input are reflected by the score for each category. + - `agent: optional object { agent_name }` - - `"text"` + The agent that produced this item. - - `"image"` + - `agent_name: string` - - `category_scores: map[number]` + The canonical name of the agent that produced this item. - A dictionary of moderation categories to scores. + - `content: optional array of object { text, type }` - - `flagged: boolean` + Reasoning text content. - A boolean indicating whether the content was flagged by any category. + - `text: string` - - `model: string` + The reasoning text from the model. - The moderation model that produced this result. + - `type: "reasoning_text"` - - `type: "moderation_result"` + The type of the reasoning text. Always `reasoning_text`. - The object type, which was always `moderation_result` for successful moderation results. + - `encrypted_content: optional string` - - `error: object { code, message, type }` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - An error produced while attempting moderation for the response input or output. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `code: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The error code. + - `"in_progress"` - - `message: string` + - `"completed"` - The error message. + - `"incomplete"` - - `type: "error"` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - The object type, which was always `error` for moderation failures. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `encrypted_content: string` - Moderation for the response output. + The encrypted content of the compaction summary. - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `type: "compaction"` - A moderation result produced for the response input or output. + The type of the item. Always `compaction`. - - `categories: map[boolean]` + - `id: optional string` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The ID of the compaction item. - - `category_applied_input_types: map[array of "text" or "image"]` + - `agent: optional object { agent_name }` - Which modalities of input are reflected by the score for each category. + The agent that produced this item. - - `"text"` + - `agent_name: string` - - `"image"` + The canonical name of the agent that produced this item. - - `category_scores: map[number]` + - `image_generation_call: object { id, result, status, 2 more }` - A dictionary of moderation categories to scores. + An image generation request made by the model. - - `flagged: boolean` + - `id: string` - A boolean indicating whether the content was flagged by any category. + The unique ID of the image generation call. - - `model: string` + - `result: string` - The moderation model that produced this result. + The generated image encoded in base64. - - `type: "moderation_result"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The object type, which was always `moderation_result` for successful moderation results. + The status of the image generation call. - - `error: object { code, message, type }` + - `"in_progress"` - An error produced while attempting moderation for the response input or output. + - `"completed"` - - `code: string` + - `"generating"` - The error code. + - `"failed"` - - `message: string` + - `type: "image_generation_call"` - The error message. + The type of the image generation call. Always `image_generation_call`. - - `type: "error"` + - `agent: optional object { agent_name }` - The object type, which was always `error` for moderation failures. + The agent that produced this item. - - `previous_response_id: optional string` + - `agent_name: string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The canonical name of the agent that produced this item. - - `prompt: optional object { id, variables, version }` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + A tool call to run code. - `id: string` - The unique identifier of the prompt template to use. - - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The unique ID of the code interpreter tool call. - - `union_member_0: string` + - `code: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The code to run, or null if not available. - A text input to the model. + - `container_id: string` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The ID of the container used to run the code. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `outputs: array of object { logs, type } or object { type, url }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - A file input to the model. + - `logs: object { logs, type }` - - `version: optional string` + The logs output from the code interpreter. - Optional version of the prompt template. + - `logs: string` - - `prompt_cache_key: optional string` + The logs output from the code interpreter. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `type: "logs"` - - `prompt_cache_options: optional object { mode, ttl }` + The type of the output. Always `logs`. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `image: object { type, url }` - - `mode: "implicit" or "explicit"` + The image output from the code interpreter. - Whether implicit prompt-cache breakpoints were enabled. + - `type: "image"` - - `"implicit"` + The type of the output. Always `image`. - - `"explicit"` + - `url: string` - - `ttl: "30m"` + The URL of the image output from the code interpreter. - The minimum lifetime applied to each cache breakpoint. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"30m"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"in_progress"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"completed"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `"incomplete"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"interpreting"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"failed"` - - `"in_memory"` + - `type: "code_interpreter_call"` - - `"24h"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `agent: optional object { agent_name }` - **gpt-5 and o-series models only** + The agent that produced this item. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `agent_name: string` - - `context: optional "auto" or "current_turn" or "all_turns"` + The canonical name of the agent that produced this item. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `"auto"` + A tool call to run a command on the local shell. - - `"current_turn"` + - `id: string` - - `"all_turns"` + The unique ID of the local shell call. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `action: object { command, env, type, 3 more }` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + Execute a shell command on the server. - - `"none"` + - `command: array of string` - - `"minimal"` + The command to run. - - `"low"` + - `env: map[string]` - - `"medium"` + Environment variables to set for the command. - - `"high"` + - `type: "exec"` - - `"xhigh"` + The type of the local shell action. Always `exec`. - - `"max"` + - `timeout_ms: optional number` - - `generate_summary: optional "auto" or "concise" or "detailed"` + Optional timeout in milliseconds for the command. - **Deprecated:** use `summary` instead. + - `user: optional string` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + Optional user to run the command as. - - `"auto"` + - `working_directory: optional string` - - `"concise"` + Optional working directory to run the command in. - - `"detailed"` + - `call_id: string` - - `mode: optional string or "standard" or "pro"` + The unique ID of the local shell tool call generated by the model. - Controls the reasoning execution mode for the request. + - `status: "in_progress" or "completed" or "incomplete"` - When returned on a response, this is the effective execution mode. + The status of the local shell call. - - `"standard"` + - `"in_progress"` - - `"pro"` + - `"completed"` - - `summary: optional "auto" or "concise" or "detailed"` + - `"incomplete"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `type: "local_shell_call"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The type of the local shell call. Always `local_shell_call`. - - `"auto"` + - `agent: optional object { agent_name }` - - `"concise"` + The agent that produced this item. - - `"detailed"` + - `agent_name: string` - - `safety_identifier: optional string` + The canonical name of the agent that produced this item. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `local_shell_call_output: object { id, output, type, 2 more }` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The output of a local shell tool call. - Specifies the processing type used for serving the request. + - `id: string` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The unique ID of the local shell tool call generated by the model. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `output: string` - - `"auto"` + A JSON string of the output of the local shell tool call. - - `"default"` + - `type: "local_shell_call_output"` - - `"flex"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"scale"` + - `agent: optional object { agent_name }` - - `"priority"` + The agent that produced this item. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `agent_name: string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The canonical name of the agent that produced this item. - - `"completed"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"failed"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - - `"cancelled"` - - - `"queued"` + - `"completed"` - `"incomplete"` - - `text: optional object { format, verbosity }` + - `shell_call: object { action, call_id, type, 5 more }` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + A tool representing a request to execute one or more shell commands. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `action: object { commands, max_output_length, timeout_ms }` - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + The shell commands and limits that describe how to run the tool call. - An object specifying the format that the model must output. + - `commands: array of string` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + Ordered shell commands for the execution environment to run. - The default format is `{ "type": "text" }` with no additional options. + - `max_output_length: optional number` - **Not recommended for gpt-4o and newer models:** + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `timeout_ms: optional number` - - `text: object { type }` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - Default response format. Used to generate text responses. + - `call_id: string` - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + The unique ID of the shell tool call generated by the model. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "shell_call"` - - `name: string` + The type of the item. Always `shell_call`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `id: optional string` - - `schema: map[unknown]` + The unique ID of the shell tool call. Populated when this item is returned via API. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `agent: optional object { agent_name }` - - `type: "json_schema"` + The agent that produced this item. - The type of response format being defined. Always `json_schema`. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `caller: optional object { type } or object { caller_id, type }` - - `strict: optional boolean` + The execution context that produced this tool call. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `direct: object { type }` - - `json_object: object { type }` + - `program: object { caller_id, type }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `caller_id: string` - - `verbosity: optional "low" or "medium" or "high"` + The call ID of the program item that produced this tool call. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `type: "program"` - - `"low"` + The caller type. Always `program`. - - `"medium"` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `"high"` + The environment to execute the shell commands in. - - `top_logprobs: optional number` + - `beta_local_environment: object { type, skills }` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `beta_container_reference: object { container_id, type }` - - `truncation: optional "auto" or "disabled"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The truncation strategy to use for the model response. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"disabled"` + - `"incomplete"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `shell_call_output: object { call_id, output, type, 5 more }` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The streamed output items emitted by a shell tool call. - - `input_tokens: number` + - `call_id: string` - The number of input tokens. + The unique ID of the shell tool call generated by the model. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `output: array of BetaResponseFunctionShellCallOutputContent` - A detailed breakdown of the input tokens. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `cache_write_tokens: number` + - `outcome: object { type } or object { exit_code, type }` - The number of input tokens that were written to the cache. + The exit or timeout outcome associated with this shell call. - - `cached_tokens: number` + - `timeout: object { type }` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + Indicates that the shell call exceeded its configured time limit. - - `output_tokens: number` + - `exit: object { exit_code, type }` - The number of output tokens. + Indicates that the shell commands finished and returned an exit code. - - `output_tokens_details: object { reasoning_tokens }` + - `exit_code: number` - A detailed breakdown of the output tokens. + The exit code returned by the shell process. - - `reasoning_tokens: number` + - `type: "exit"` - The number of reasoning tokens. + The outcome type. Always `exit`. - - `total_tokens: number` + - `stderr: string` - The total number of tokens used. + Captured stderr output for the shell call. - - `user: optional string` + - `stdout: string` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Captured stdout output for the shell call. - - `sequence_number: number` + - `type: "shell_call_output"` - The sequence number for this event. + The type of the item. Always `shell_call_output`. - - `type: "response.completed"` + - `id: optional string` - The type of the event. Always `response.completed`. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Computer Tool Call + - `caller: optional object { type } or object { caller_id, type }` -- `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + The execution context that produced this tool call. - 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. + - `direct: object { type }` - - `id: string` + - `program: object { caller_id, type }` - The unique ID of the computer call. + - `caller_id: string` - - `call_id: string` + The call ID of the program item that produced this tool call. - An identifier used when responding to the tool call with output. + - `type: "program"` - - `pending_safety_checks: array of object { id, code, message }` + The caller type. Always `program`. - The pending safety checks for the computer call. + - `max_output_length: optional number` - - `id: string` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The ID of the pending safety check. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `code: optional string` + The status of the shell call output. - The type of the pending safety check. + - `"in_progress"` - - `message: optional string` + - `"completed"` - Details about the pending safety check. + - `"incomplete"` - - `status: "in_progress" or "completed" or "incomplete"` + - `apply_patch_call: object { call_id, operation, status, 4 more }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool call representing a request to create, delete, or update files using diff patches. - - `"in_progress"` + - `call_id: string` - - `"completed"` + The unique ID of the apply patch tool call generated by the model. - - `"incomplete"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `type: "computer_call"` + The specific create, delete, or update instruction for the apply_patch tool call. - The type of the computer call. Always `computer_call`. + - `create_file: object { diff, path, type }` - - `"computer_call"` + Instruction for creating a new file via the apply_patch tool. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `diff: string` - A click action. + Unified diff content to apply when creating the file. - - `click: object { button, type, x, 2 more }` + - `path: string` - A click action. + Path of the file to create relative to the workspace root. - - `button: "left" or "right" or "wheel" or 2 more` + - `type: "create_file"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The operation type. Always `create_file`. - - `"left"` + - `delete_file: object { path, type }` - - `"right"` + Instruction for deleting an existing file via the apply_patch tool. - - `"wheel"` + - `path: string` - - `"back"` + Path of the file to delete relative to the workspace root. - - `"forward"` + - `type: "delete_file"` - - `type: "click"` + The operation type. Always `delete_file`. - Specifies the event type. For a click action, this property is always `click`. + - `update_file: object { diff, path, type }` - - `x: number` + Instruction for updating an existing file via the apply_patch tool. - The x-coordinate where the click occurred. + - `diff: string` - - `y: number` + Unified diff content to apply to the existing file. - The y-coordinate where the click occurred. + - `path: string` - - `keys: optional array of string` + Path of the file to update relative to the workspace root. - The keys being held while clicking. + - `type: "update_file"` - - `double_click: object { keys, type, x, y }` + The operation type. Always `update_file`. - A double click action. + - `status: "in_progress" or "completed"` - - `keys: array of string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The keys being held while double-clicking. + - `"in_progress"` - - `type: "double_click"` + - `"completed"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `type: "apply_patch_call"` - - `x: number` + The type of the item. Always `apply_patch_call`. - The x-coordinate where the double click occurred. + - `id: optional string` - - `y: number` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The y-coordinate where the double click occurred. + - `agent: optional object { agent_name }` - - `drag: object { path, type, keys }` + The agent that produced this item. - A drag action. + - `agent_name: string` - - `path: array of object { x, y }` + The canonical name of the agent that produced this item. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `caller: optional object { type } or object { caller_id, type }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The execution context that produced this tool call. - - `x: number` + - `direct: object { type }` - The x-coordinate. + - `program: object { caller_id, type }` - - `y: number` + - `caller_id: string` - The y-coordinate. + The call ID of the program item that produced this tool call. - - `type: "drag"` + - `type: "program"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The caller type. Always `program`. - - `keys: optional array of string` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The keys being held while dragging the mouse. + The streamed output emitted by an apply patch tool call. - - `keypress: object { keys, type }` + - `call_id: string` - A collection of keypresses the model would like to perform. + The unique ID of the apply patch tool call generated by the model. - - `keys: array of string` + - `status: "completed" or "failed"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: "keypress"` + - `"completed"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"failed"` - - `move: object { type, x, y, keys }` + - `type: "apply_patch_call_output"` - A mouse move action. + The type of the item. Always `apply_patch_call_output`. - - `type: "move"` + - `id: optional string` - Specifies the event type. For a move action, this property is always set to `move`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `x: number` + - `agent: optional object { agent_name }` - The x-coordinate to move to. + The agent that produced this item. - - `y: number` + - `agent_name: string` - The y-coordinate to move to. + The canonical name of the agent that produced this item. - - `keys: optional array of string` + - `caller: optional object { type } or object { caller_id, type }` - The keys being held while moving the mouse. + The execution context that produced this tool call. - - `screenshot: object { type }` + - `direct: object { type }` - A screenshot action. + - `program: object { caller_id, type }` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `caller_id: string` - A scroll action. + The call ID of the program item that produced this tool call. - - `scroll_x: number` + - `type: "program"` - The horizontal scroll distance. + The caller type. Always `program`. - - `scroll_y: number` + - `output: optional string` - The vertical scroll distance. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `type: "scroll"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + A list of tools available on an MCP server. - - `x: number` + - `id: string` - The x-coordinate where the scroll occurred. + The unique ID of the list. - - `y: number` + - `server_label: string` - The y-coordinate where the scroll occurred. + The label of the MCP server. - - `keys: optional array of string` + - `tools: array of object { input_schema, name, annotations, description }` - The keys being held while scrolling. + The tools available on the server. - - `type: object { text, type }` + - `input_schema: unknown` - An action to type in text. + The JSON schema describing the tool's input. - - `text: string` + - `name: string` - The text to type. + The name of the tool. - - `type: "type"` + - `annotations: optional unknown` - Specifies the event type. For a type action, this property is always set to `type`. + Additional annotations about the tool. - - `wait: object { type }` + - `description: optional string` - A wait action. + The description of the tool. - - `actions: optional array of BetaComputerAction` + - `type: "mcp_list_tools"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The type of the item. Always `mcp_list_tools`. - - `click: object { button, type, x, 2 more }` + - `agent: optional object { agent_name }` - A click action. + The agent that produced this item. - - `double_click: object { keys, type, x, y }` + - `agent_name: string` - A double click action. + The canonical name of the agent that produced this item. - - `drag: object { path, type, keys }` + - `error: optional string` - A drag action. + Error message if the server could not list tools. - - `keypress: object { keys, type }` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - A collection of keypresses the model would like to perform. + A request for human approval of a tool invocation. - - `move: object { type, x, y, keys }` + - `id: string` - A mouse move action. + The unique ID of the approval request. - - `screenshot: object { type }` + - `arguments: string` - A screenshot action. + A JSON string of arguments for the tool. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `name: string` - A scroll action. + The name of the tool to run. - - `type: object { text, type }` + - `server_label: string` - An action to type in text. + The label of the MCP server making the request. - - `wait: object { type }` + - `type: "mcp_approval_request"` - A wait action. + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` @@ -56033,68 +66452,61 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Computer Tool Call Output Item - -- `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - - `id: string` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - The unique ID of the computer call tool output. + A response to an MCP approval request. - - `call_id: string` + - `approval_request_id: string` - The ID of the computer tool call that produced the output. + The ID of the approval request being answered. - - `output: object { type, file_id, image_url }` + - `approve: boolean` - A computer screenshot image used with the computer use tool. + Whether the request was approved. - - `type: "computer_screenshot"` + - `type: "mcp_approval_response"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The type of the item. Always `mcp_approval_response`. - - `file_id: optional string` + - `id: optional string` - The identifier of an uploaded file that contains the screenshot. + The unique ID of the approval response - - `image_url: optional string` + - `agent: optional object { agent_name }` - The URL of the screenshot image. + The agent that produced this item. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `agent_name: string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The canonical name of the agent that produced this item. - - `"completed"` + - `reason: optional string` - - `"incomplete"` + Optional reason for the decision. - - `"failed"` + - `mcp_call: object { id, arguments, name, 7 more }` - - `"in_progress"` + An invocation of a tool on an MCP server. - - `type: "computer_call_output"` + - `id: string` - The type of the computer tool call output. Always `computer_call_output`. + The unique ID of the tool call. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `arguments: string` - The safety checks reported by the API that have been acknowledged by the - developer. + A JSON string of the arguments passed to the tool. - - `id: string` + - `name: string` - The ID of the pending safety check. + The name of the tool that was run. - - `code: optional string` + - `server_label: string` - The type of the pending safety check. + The label of the MCP server running the tool. - - `message: optional string` + - `type: "mcp_call"` - Details about the pending safety check. + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` @@ -56104,46 +66516,53 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `approval_request_id: optional string` - The identifier of the actor that created the item. + 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. -### Beta Response Computer Tool Call Output Screenshot + - `error: optional string` -- `beta_response_computer_tool_call_output_screenshot: object { type, file_id, image_url }` + The error from the tool call, if any. - A computer screenshot image used with the computer use tool. + - `output: optional string` - - `type: "computer_screenshot"` + The output from the tool call. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `file_id: optional string` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The identifier of an uploaded file that contains the screenshot. + - `"in_progress"` - - `image_url: optional string` + - `"completed"` - The URL of the screenshot image. + - `"incomplete"` -### Beta Response Container Reference + - `"calling"` -- `beta_response_container_reference: object { container_id, type }` + - `"failed"` - Represents a container created with /v1/containers. + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `container_id: string` + The output of a custom tool call from your code, being sent back to the model. - - `type: "container_reference"` + - `call_id: string` - The environment type. Always `container_reference`. + The call ID, used to map this custom tool call output to a custom tool call. -### Beta Response Content + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` -- `beta_response_content: BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile or 3 more` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Multi-modal input and output contents. + - `string output: string` + + A string of the output of the custom tool call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the custom tool call. - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` @@ -56161,10 +66580,6 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -56173,14 +66588,6 @@ openai beta:responses compact \ The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - `type: "input_image"` The type of the input item. Always `input_image`. @@ -56197,10 +66604,6 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. @@ -56213,12 +66616,6 @@ openai beta:responses compact \ The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"auto"` - - - `"low"` - - - `"high"` - - `file_data: optional string` The content of the file to be sent to the model. @@ -56239,983 +66636,1088 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` + - `type: "custom_tool_call_output"` - The breakpoint mode. Always `explicit`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `id: optional string` - A text output from the model. + The unique ID of the custom tool call output in the OpenAI platform. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `agent: optional object { agent_name }` - The annotations of the text output. + The agent that produced this item. - - `file_citation: object { file_id, filename, index, type }` + - `agent_name: string` - A citation to a file. + The canonical name of the agent that produced this item. - - `file_id: string` + - `caller: optional object { type } or object { caller_id, type }` - The ID of the file. + The execution context that produced this tool call. - - `filename: string` + - `direct: object { type }` - The filename of the file cited. + - `program: object { caller_id, type }` - - `index: number` + - `caller_id: string` - The index of the file in the list of files. + The call ID of the program item that produced this tool call. - - `type: "file_citation"` + - `type: "program"` - The type of the file citation. Always `file_citation`. + The caller type. Always `program`. - - `url_citation: object { end_index, start_index, title, 2 more }` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - A citation for a web resource used to generate a model response. + A call to a custom tool created by the model. - - `end_index: number` + - `call_id: string` - The index of the last character of the URL citation in the message. + An identifier used to map this custom tool call to a tool call output. - - `start_index: number` + - `input: string` - The index of the first character of the URL citation in the message. + The input for the custom tool call generated by the model. - - `title: string` + - `name: string` - The title of the web resource. + The name of the custom tool being called. - - `type: "url_citation"` + - `type: "custom_tool_call"` - The type of the URL citation. Always `url_citation`. + The type of the custom tool call. Always `custom_tool_call`. - - `url: string` + - `id: optional string` - The URL of the web resource. + The unique ID of the custom tool call in the OpenAI platform. - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `agent: optional object { agent_name }` - A citation for a container file used to generate a model response. + The agent that produced this item. - - `container_id: string` + - `agent_name: string` - The ID of the container file. + The canonical name of the agent that produced this item. - - `end_index: number` + - `caller: optional object { type } or object { caller_id, type }` - The index of the last character of the container file citation in the message. + The execution context that produced this tool call. - - `file_id: string` + - `direct: object { type }` - The ID of the file. + - `program: object { caller_id, type }` - - `filename: string` + - `caller_id: string` - The filename of the container file cited. + The call ID of the program item that produced this tool call. - - `start_index: number` + - `type: "program"` - The index of the first character of the container file citation in the message. + - `namespace: optional string` - - `type: "container_file_citation"` + The namespace of the custom tool being called. - The type of the container file citation. Always `container_file_citation`. + - `compaction_trigger: object { type, agent }` - - `file_path: object { file_id, index, type }` + Compacts the current context. Must be the final input item. - A path to a file. + - `type: "compaction_trigger"` - - `file_id: string` + The type of the item. Always `compaction_trigger`. - The ID of the file. + - `agent: optional object { agent_name }` - - `index: number` + The agent that produced this item. - The index of the file in the list of files. + - `agent_name: string` - - `type: "file_path"` + The canonical name of the agent that produced this item. - The type of the file path. Always `file_path`. + - `item_reference: object { id, agent, type }` - - `text: string` + An internal identifier for an item to reference. - The text output from the model. + - `id: string` - - `type: "output_text"` + The ID of the item to reference. - The type of the output text. Always `output_text`. + - `agent: optional object { agent_name }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The agent that produced this item. - - `token: string` + - `agent_name: string` - - `bytes: array of number` + The canonical name of the agent that produced this item. - - `logprob: number` + - `type: optional "item_reference"` - - `top_logprobs: array of object { token, bytes, logprob }` + The type of item to reference. Always `item_reference`. - - `token: string` + - `"item_reference"` - - `bytes: array of number` + - `program: object { id, call_id, code, 3 more }` - - `logprob: number` + - `id: string` - - `beta_response_output_refusal: object { refusal, type }` + The unique ID of this program item. - A refusal from the model. + - `call_id: string` - - `refusal: string` + The stable call ID of the program item. - The refusal explanation from the model. + - `code: string` - - `type: "refusal"` + The JavaScript source executed by programmatic tool calling. - The type of the refusal. Always `refusal`. + - `fingerprint: string` - - `Reasoning text: object { text, type }` + Opaque program replay fingerprint that must be round-tripped. - Reasoning text from the model. + - `type: "program"` - - `text: string` + The item type. Always `program`. - The reasoning text from the model. + - `agent: optional object { agent_name }` - - `type: "reasoning_text"` + The agent that produced this item. - The type of the reasoning text. Always `reasoning_text`. + - `agent_name: string` -### Beta Response Content Part Added Event + The canonical name of the agent that produced this item. -- `beta_response_content_part_added_event: object { content_index, item_id, output_index, 4 more }` + - `program_output: object { id, call_id, result, 3 more }` - Emitted when a new content part is added. + - `id: string` - - `content_index: number` + The unique ID of this program output item. - The index of the content part that was added. + - `call_id: string` - - `item_id: string` + The call ID of the program item. - The ID of the output item that the content part was added to. + - `result: string` - - `output_index: number` + The result produced by the program item. - The index of the output item that the content part was added to. + - `status: "completed" or "incomplete"` - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + The terminal status of the program output. - The content part that was added. + - `"completed"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"incomplete"` - A text output from the model. + - `type: "program_output"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The item type. Always `program_output`. - The annotations of the text output. + - `agent: optional object { agent_name }` - - `file_citation: object { file_id, filename, index, type }` + The agent that produced this item. - A citation to a file. + - `agent_name: string` - - `file_id: string` + The canonical name of the agent that produced this item. - The ID of the file. + - `metadata: map[string]` - - `filename: string` + 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. - The filename of the file cited. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `index: number` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The index of the file in the list of files. + Model ID used to generate the response, like `gpt-4o` 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. - - `type: "file_citation"` + - `"gpt-5.6-sol"` - The type of the file citation. Always `file_citation`. + - `"gpt-5.6-terra"` - - `url_citation: object { end_index, start_index, title, 2 more }` + - `"gpt-5.6-luna"` - A citation for a web resource used to generate a model response. + - `"gpt-5.4"` - - `end_index: number` + - `"gpt-5.4-mini"` - The index of the last character of the URL citation in the message. + - `"gpt-5.4-nano"` - - `start_index: number` + - `"gpt-5.4-mini-2026-03-17"` - The index of the first character of the URL citation in the message. + - `"gpt-5.4-nano-2026-03-17"` - - `title: string` + - `"gpt-5.3-chat-latest"` - The title of the web resource. + - `"gpt-5.2"` - - `type: "url_citation"` + - `"gpt-5.2-2025-12-11"` - The type of the URL citation. Always `url_citation`. + - `"gpt-5.2-chat-latest"` - - `url: string` + - `"gpt-5.2-pro"` - The URL of the web resource. + - `"gpt-5.2-pro-2025-12-11"` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `"gpt-5.1"` - A citation for a container file used to generate a model response. + - `"gpt-5.1-2025-11-13"` - - `container_id: string` + - `"gpt-5.1-codex"` - The ID of the container file. + - `"gpt-5.1-mini"` - - `end_index: number` + - `"gpt-5.1-chat-latest"` - The index of the last character of the container file citation in the message. + - `"gpt-5"` - - `file_id: string` + - `"gpt-5-mini"` - The ID of the file. + - `"gpt-5-nano"` - - `filename: string` + - `"gpt-5-2025-08-07"` - The filename of the container file cited. + - `"gpt-5-mini-2025-08-07"` - - `start_index: number` + - `"gpt-5-nano-2025-08-07"` - The index of the first character of the container file citation in the message. + - `"gpt-5-chat-latest"` - - `type: "container_file_citation"` + - `"gpt-4.1"` - The type of the container file citation. Always `container_file_citation`. + - `"gpt-4.1-mini"` - - `file_path: object { file_id, index, type }` + - `"gpt-4.1-nano"` - A path to a file. + - `"gpt-4.1-2025-04-14"` - - `file_id: string` + - `"gpt-4.1-mini-2025-04-14"` - The ID of the file. + - `"gpt-4.1-nano-2025-04-14"` - - `index: number` + - `"o4-mini"` - The index of the file in the list of files. + - `"o4-mini-2025-04-16"` - - `type: "file_path"` + - `"o3"` - The type of the file path. Always `file_path`. + - `"o3-2025-04-16"` - - `text: string` + - `"o3-mini"` - The text output from the model. + - `"o3-mini-2025-01-31"` - - `type: "output_text"` + - `"o1"` - The type of the output text. Always `output_text`. + - `"o1-2024-12-17"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"o1-preview"` - - `token: string` + - `"o1-preview-2024-09-12"` - - `bytes: array of number` + - `"o1-mini"` - - `logprob: number` + - `"o1-mini-2024-09-12"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"gpt-4o"` - - `token: string` + - `"gpt-4o-2024-11-20"` - - `bytes: array of number` + - `"gpt-4o-2024-08-06"` - - `logprob: number` + - `"gpt-4o-2024-05-13"` - - `beta_response_output_refusal: object { refusal, type }` + - `"gpt-4o-audio-preview"` - A refusal from the model. + - `"gpt-4o-audio-preview-2024-10-01"` - - `refusal: string` + - `"gpt-4o-audio-preview-2024-12-17"` - The refusal explanation from the model. + - `"gpt-4o-audio-preview-2025-06-03"` - - `type: "refusal"` + - `"gpt-4o-mini-audio-preview"` - The type of the refusal. Always `refusal`. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `reasoning_text: object { text, type }` + - `"gpt-4o-search-preview"` - Reasoning text from the model. + - `"gpt-4o-mini-search-preview"` - - `text: string` + - `"gpt-4o-search-preview-2025-03-11"` - The reasoning text from the model. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `type: "reasoning_text"` + - `"chatgpt-4o-latest"` - The type of the reasoning text. Always `reasoning_text`. + - `"codex-mini-latest"` - - `sequence_number: number` + - `"gpt-4o-mini"` - The sequence number of this event. + - `"gpt-4o-mini-2024-07-18"` - - `type: "response.content_part.added"` + - `"gpt-4-turbo"` - The type of the event. Always `response.content_part.added`. + - `"gpt-4-turbo-2024-04-09"` - - `agent: optional object { agent_name }` + - `"gpt-4-0125-preview"` - The agent that owns this multi-agent streaming event. + - `"gpt-4-turbo-preview"` - - `agent_name: string` + - `"gpt-4-1106-preview"` - The canonical name of the agent that produced this item. + - `"gpt-4-vision-preview"` -### Beta Response Content Part Done Event + - `"gpt-4"` -- `beta_response_content_part_done_event: object { content_index, item_id, output_index, 4 more }` + - `"gpt-4-0314"` - Emitted when a content part is done. + - `"gpt-4-0613"` - - `content_index: number` + - `"gpt-4-32k"` - The index of the content part that is done. + - `"gpt-4-32k-0314"` - - `item_id: string` + - `"gpt-4-32k-0613"` - The ID of the output item that the content part was added to. + - `"gpt-3.5-turbo"` - - `output_index: number` + - `"gpt-3.5-turbo-16k"` - The index of the output item that the content part was added to. + - `"gpt-3.5-turbo-0301"` - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `"gpt-3.5-turbo-0613"` - The content part that is done. + - `"gpt-3.5-turbo-1106"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"gpt-3.5-turbo-0125"` - A text output from the model. + - `"gpt-3.5-turbo-16k-0613"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"o1-pro"` - The annotations of the text output. + - `"o1-pro-2025-03-19"` - - `file_citation: object { file_id, filename, index, type }` + - `"o3-pro"` - A citation to a file. + - `"o3-pro-2025-06-10"` - - `file_id: string` + - `"o3-deep-research"` - The ID of the file. + - `"o3-deep-research-2025-06-26"` - - `filename: string` + - `"o4-mini-deep-research"` - The filename of the file cited. + - `"o4-mini-deep-research-2025-06-26"` - - `index: number` + - `"computer-use-preview"` - The index of the file in the list of files. + - `"computer-use-preview-2025-03-11"` - - `type: "file_citation"` + - `"gpt-5-codex"` - The type of the file citation. Always `file_citation`. + - `"gpt-5-pro"` - - `url_citation: object { end_index, start_index, title, 2 more }` + - `"gpt-5-pro-2025-10-06"` - A citation for a web resource used to generate a model response. + - `"gpt-5.1-codex-max"` - - `end_index: number` + - `object: "response"` - The index of the last character of the URL citation in the message. + The object type of this resource - always set to `response`. - - `start_index: number` + - `output: array of BetaResponseOutputItem` - The index of the first character of the URL citation in the message. + An array of content items generated by the model. - - `title: string` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - The title of the web resource. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `type: "url_citation"` + An output message from the model. - The type of the URL citation. Always `url_citation`. + - `id: string` - - `url: string` + The unique ID of the output message. - The URL of the web resource. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + The content of the output message. - A citation for a container file used to generate a model response. + - `role: "assistant"` - - `container_id: string` + The role of the output message. Always `assistant`. - The ID of the container file. + - `status: "in_progress" or "completed" or "incomplete"` - - `end_index: number` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The index of the last character of the container file citation in the message. + - `type: "message"` - - `file_id: string` + The type of the output message. Always `message`. - The ID of the file. + - `agent: optional object { agent_name }` - - `filename: string` + The agent that produced this item. - The filename of the container file cited. + - `phase: optional "commentary" or "final_answer"` - - `start_index: number` + 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. - The index of the first character of the container file citation in the message. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `type: "container_file_citation"` + 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. - The type of the container file citation. Always `container_file_citation`. + - `id: string` - - `file_path: object { file_id, index, type }` + The unique ID of the file search tool call. - A path to a file. + - `queries: array of string` - - `file_id: string` + The queries used to search for files. - The ID of the file. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `index: number` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The index of the file in the list of files. + - `type: "file_search_call"` - - `type: "file_path"` + The type of the file search tool call. Always `file_search_call`. - The type of the file path. Always `file_path`. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The text output from the model. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `type: "output_text"` + The results of the file search tool call. - The type of the output text. Always `output_text`. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `token: string` + - `arguments: string` - - `bytes: array of number` + A JSON string of the arguments to pass to the function. - - `logprob: number` + - `call_id: string` - - `top_logprobs: array of object { token, bytes, logprob }` + The unique ID of the function tool call generated by the model. - - `token: string` + - `name: string` - - `bytes: array of number` + The name of the function to run. - - `logprob: number` + - `type: "function_call"` - - `beta_response_output_refusal: object { refusal, type }` + The type of the function tool call. Always `function_call`. - A refusal from the model. + - `id: optional string` - - `refusal: string` + The unique ID of the function tool call. - The refusal explanation from the model. + - `agent: optional object { agent_name }` - - `type: "refusal"` + The agent that produced this item. - The type of the refusal. Always `refusal`. + - `caller: optional object { type } or object { caller_id, type }` - - `reasoning_text: object { text, type }` + The execution context that produced this tool call. - Reasoning text from the model. + - `namespace: optional string` - - `text: string` + The namespace of the function to run. - The reasoning text from the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "reasoning_text"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the reasoning text. Always `reasoning_text`. + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `sequence_number: number` + - `id: string` - The sequence number of this event. + The unique ID of the function call tool output. - - `type: "response.content_part.done"` + - `call_id: string` - The type of the event. Always `response.content_part.done`. + The unique ID of the function tool call generated by the model. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `string output: string` + + A string of the output of the function call. + + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the function call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Conversation Param + - `caller: optional object { type } or object { caller_id, type }` -- `beta_response_conversation_param: object { id }` + The execution context that produced this tool call. - The conversation that this response belongs to. + - `direct: object { type }` - - `id: string` + - `program: object { caller_id, type }` - The unique ID of the conversation. + - `caller_id: string` -### Beta Response Created Event + The call ID of the program item that produced this tool call. -- `beta_response_created_event: object { response, sequence_number, type, agent }` + - `type: "program"` - An event that is emitted when a response is created. + The caller type. Always `program`. - - `response: object { id, created_at, error, 31 more }` + - `created_by: optional string` - The response that was created. + The identifier of the actor that created the item. + + - `agent_message: object { id, author, content, 3 more }` - `id: string` - Unique identifier for this Response. + The unique ID of the agent message. - - `created_at: number` + - `author: string` - Unix timestamp (in seconds) of when this Response was created. + The sending agent identity. - - `error: object { code, message }` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - An error object returned when the model fails to generate a Response. + Encrypted content sent between agents. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The error code for the response. + A text input to the model. - - `"server_error"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `"rate_limit_exceeded"` + A text output from the model. - - `"invalid_prompt"` + - `text: object { text, type }` - - `"bio_policy"` + A text content. - - `"vector_store_timeout"` + - `text: string` - - `"invalid_image"` + - `type: "text"` - - `"invalid_image_format"` + - `summary_text: object { text, type }` - - `"invalid_base64_image"` + A summary text from the model. - - `"invalid_image_url"` + - `text: string` - - `"image_too_large"` + A summary of the reasoning output from the model so far. - - `"image_too_small"` + - `type: "summary_text"` - - `"image_parse_error"` + The type of the object. Always `summary_text`. - - `"image_content_policy_violation"` + - `reasoning_text: object { text, type }` - - `"invalid_image_mode"` + Reasoning text from the model. - - `"image_file_too_large"` + - `text: string` - - `"unsupported_image_media_type"` + The reasoning text from the model. - - `"empty_image_file"` + - `type: "reasoning_text"` - - `"failed_to_download_image"` + The type of the reasoning text. Always `reasoning_text`. - - `"image_file_not_found"` + - `beta_response_output_refusal: object { refusal, type }` - - `message: string` + A refusal from the model. - A human-readable description of the error. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `incomplete_details: object { reason }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Details about why the response is incomplete. + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - - `reason: optional "max_output_tokens" or "content_filter"` + A screenshot of a computer. - The reason why the response is incomplete. + - `detail: "low" or "high" or "auto" or "original"` - - `"max_output_tokens"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"content_filter"` + - `"low"` - - `instructions: string or array of BetaResponseInputItem` + - `"high"` - A system (or developer) message inserted into the model's context. + - `"auto"` - When using 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. + - `"original"` - - `union_member_0: string` + - `file_id: string` - A text input to the model, equivalent to a text input with the - `developer` role. + The identifier of an uploaded file that contains the screenshot. - - `Input item list: array of BetaResponseInputItem` + - `image_url: string` - A list of one or many input items to the model, containing - different content types. + The URL of the screenshot image. - - `beta_easy_input_message: object { content, role, phase, type }` + - `type: "computer_screenshot"` - 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. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `content: string or BetaResponseInputMessageContentList` + - `prompt_cache_breakpoint: optional object { mode }` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + 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. - - `Text input: string` + - `mode: "explicit"` - A text input to the model. + The breakpoint mode. Always `explicit`. - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - A list of one or many input items to the model, containing different content - types. + A file input to the model. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `encrypted_content: object { encrypted_content, type }` - A text input to the model. + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { id, action, arguments, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action to execute. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. - - `text: string` + - `call_id: string` - The text input to the model. + The unique ID linking this call to its output. - - `type: "input_text"` + - `type: "multi_agent_call"` - The type of the input item. Always `input_text`. + The type of the multi-agent call. Always `multi_agent_call`. - - `prompt_cache_breakpoint: optional object { mode }` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - - `mode: "explicit"` + - `agent_name: string` - The breakpoint mode. Always `explicit`. + The canonical name of the agent that produced this item. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `id: string` - - `detail: "low" or "high" or "auto" or "original"` + The unique ID of the multi-agent call output item. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"low"` + The multi-agent action that produced this result. - - `"high"` + - `"spawn_agent"` - - `"auto"` + - `"interrupt_agent"` - - `"original"` + - `"list_agents"` - - `type: "input_image"` + - `"send_message"` - The type of the input item. Always `input_image`. + - `"followup_task"` - - `file_id: optional string` + - `"wait_agent"` - The ID of the file to be sent to the model. + - `call_id: string` - - `image_url: optional string` + The unique ID of the multi-agent call. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `output: array of BetaResponseOutputText` - - `prompt_cache_breakpoint: optional object { mode }` + Text output returned by the multi-agent action. - 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. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `mode: "explicit"` + The annotations of the text output. - The breakpoint mode. Always `explicit`. + - `text: string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The text output from the model. - A file input to the model. + - `type: "output_text"` - - `type: "input_file"` + The type of the output text. Always `output_text`. - The type of the input item. Always `input_file`. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `detail: optional "auto" or "low" or "high"` + - `type: "multi_agent_call_output"` - 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`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"auto"` + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `file_data: optional string` + The canonical name of the agent that produced this item. - The content of the file to be sent to the model. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `file_id: optional string` + 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. - The ID of the file to be sent to the model. + - `id: string` - - `file_url: optional string` + The unique ID of the web search tool call. - The URL of the file to be sent to the model. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `filename: optional string` + 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). - The name of the file to be sent to the model. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `prompt_cache_breakpoint: optional object { mode }` + The status of the web search tool call. - 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. + - `type: "web_search_call"` - - `mode: "explicit"` + The type of the web search tool call. Always `web_search_call`. - The breakpoint mode. Always `explicit`. + - `agent: optional object { agent_name }` - - `role: "user" or "assistant" or "system" or "developer"` + The agent that produced this item. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `"user"` + 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. - - `"assistant"` + - `id: string` - - `"system"` + The unique ID of the computer call. - - `"developer"` + - `call_id: string` - - `phase: optional "commentary"` + An identifier used when responding to the tool call with output. - 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. + - `pending_safety_checks: array of object { id, code, message }` - - `"commentary"` + The pending safety checks for the computer call. - - `type: optional "message"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the message input. Always `message`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"message"` + - `type: "computer_call"` - - `message: object { content, role, agent, 2 more }` + The type of the computer call. Always `computer_call`. - 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. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `content: array of BetaResponseInputContent` + A click action. - A list of one or many input items to the model, containing different content - types. + - `actions: optional array of BetaComputerAction` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - A text input to the model. + - `agent: optional object { agent_name }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The agent that produced this item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `id: string` - A file input to the model. + The unique ID of the computer call tool output. - - `role: "user" or "system" or "developer"` + - `call_id: string` - The role of the message input. One of `user`, `system`, or `developer`. + The ID of the computer tool call that produced the output. - - `"user"` + - `output: object { type, file_id, image_url }` - - `"system"` + A computer screenshot image used with the computer use tool. - - `"developer"` + - `type: "computer_screenshot"` - - `agent: optional object { agent_name }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The agent that produced this item. + - `file_id: optional string` - - `agent_name: string` + The identifier of an uploaded file that contains the screenshot. - The canonical name of the agent that produced this item. + - `image_url: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The URL of the screenshot image. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"in_progress"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - `"incomplete"` - - `type: optional "message"` + - `"failed"` - The type of the message input. Always set to `message`. + - `"in_progress"` - - `"message"` + - `type: "computer_call_output"` - - `beta_response_output_message: object { id, content, role, 4 more }` + The type of the computer tool call output. Always `computer_call_output`. - An output message from the model. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `id: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The unique ID of the output message. + - `id: string` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The ID of the pending safety check. - The content of the output message. + - `code: optional string` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + The type of the pending safety check. - A text output from the model. + - `message: optional string` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + Details about the pending safety check. - The annotations of the text output. + - `agent: optional object { agent_name }` - - `file_citation: object { file_id, filename, index, type }` + The agent that produced this item. - A citation to a file. + - `agent_name: string` - - `file_id: string` + The canonical name of the agent that produced this item. - The ID of the file. + - `created_by: optional string` - - `filename: string` + The identifier of the actor that created the item. - The filename of the file cited. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `index: number` + 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). - The index of the file in the list of files. + - `id: string` - - `type: "file_citation"` + The unique identifier of the reasoning content. - The type of the file citation. Always `file_citation`. + - `summary: array of object { text, type }` - - `url_citation: object { end_index, start_index, title, 2 more }` + Reasoning summary content. - A citation for a web resource used to generate a model response. + - `type: "reasoning"` - - `end_index: number` + The type of the object. Always `reasoning`. - The index of the last character of the URL citation in the message. + - `agent: optional object { agent_name }` - - `start_index: number` + The agent that produced this item. - The index of the first character of the URL citation in the message. + - `content: optional array of object { text, type }` - - `title: string` + Reasoning text content. - The title of the web resource. + - `encrypted_content: optional string` - - `type: "url_citation"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The type of the URL citation. Always `url_citation`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `url: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The URL of the web resource. + - `program: object { id, call_id, code, 3 more }` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `id: string` - A citation for a container file used to generate a model response. + The unique ID of the program item. - - `container_id: string` + - `call_id: string` - The ID of the container file. + The stable call ID of the program item. - - `end_index: number` + - `code: string` - The index of the last character of the container file citation in the message. + The JavaScript source executed by programmatic tool calling. - - `file_id: string` + - `fingerprint: string` - The ID of the file. + Opaque program replay fingerprint that must be round-tripped. - - `filename: string` + - `type: "program"` - The filename of the container file cited. + The type of the item. Always `program`. - - `start_index: number` + - `agent: optional object { agent_name }` - The index of the first character of the container file citation in the message. + The agent that produced this item. - - `type: "container_file_citation"` + - `agent_name: string` - The type of the container file citation. Always `container_file_citation`. + The canonical name of the agent that produced this item. - - `file_path: object { file_id, index, type }` + - `program_output: object { id, call_id, result, 3 more }` - A path to a file. + - `id: string` - - `file_id: string` + The unique ID of the program output item. - The ID of the file. + - `call_id: string` - - `index: number` + The call ID of the program item. - The index of the file in the list of files. + - `result: string` - - `type: "file_path"` + The result produced by the program item. - The type of the file path. Always `file_path`. + - `status: "completed" or "incomplete"` - - `text: string` + The terminal status of the program output item. - The text output from the model. + - `"completed"` - - `type: "output_text"` + - `"incomplete"` - The type of the output text. Always `output_text`. + - `type: "program_output"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The type of the item. Always `program_output`. - - `token: string` + - `agent: optional object { agent_name }` - - `bytes: array of number` + The agent that produced this item. - - `logprob: number` + - `agent_name: string` - - `top_logprobs: array of object { token, bytes, logprob }` + The canonical name of the agent that produced this item. - - `token: string` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `bytes: array of number` + - `id: string` - - `logprob: number` + The unique ID of the tool search call item. - - `beta_response_output_refusal: object { refusal, type }` + - `arguments: unknown` - A refusal from the model. + Arguments used for the tool search call. - - `refusal: string` + - `call_id: string` - The refusal explanation from the model. + The unique ID of the tool search call generated by the model. - - `type: "refusal"` + - `execution: "server" or "client"` - The type of the refusal. Always `refusal`. + Whether tool search was executed by the server or by the client. - - `role: "assistant"` + - `"server"` - The role of the output message. Always `assistant`. + - `"client"` - `status: "in_progress" or "completed" or "incomplete"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -57223,9 +67725,9 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "message"` + - `type: "tool_search_call"` - The type of the output message. Always `message`. + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -57235,400 +67737,402 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `created_by: optional string` - 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. + The identifier of the actor that created the item. - - `"commentary"` + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `id: string` - 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. + The unique ID of the tool search output item. - - `id: string` + - `call_id: string` - The unique ID of the file search tool call. + The unique ID of the tool search call generated by the model. - - `queries: array of string` + - `execution: "server" or "client"` - The queries used to search for files. + Whether tool search was executed by the server or by the client. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"server"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"client"` - - `"in_progress"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"searching"` + The status of the tool search output item that was recorded. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `"failed"` + - `tools: array of BetaTool` - - `type: "file_search_call"` + The loaded tool definitions returned by tool search. - The type of the file search tool call. Always `file_search_call`. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `agent: optional object { agent_name }` + 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). - The agent that produced this item. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `beta_computer_tool: object { type }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The results of the file search tool call. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `attributes: optional map[string or number or boolean]` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - 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. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `union_member_0: string` + 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). - - `union_member_1: number` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `union_member_2: boolean` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `file_id: optional string` + - `code_interpreter: object { container, type, allowed_callers }` - The unique ID of the file. + A tool that runs Python code to help generate a response to a prompt. - - `filename: optional string` + - `programmatic_tool_calling: object { type }` - The name of the file. + - `image_generation: object { type, action, background, 9 more }` - - `score: optional number` + A tool that generates images using the GPT image models. - The relevance score of the file - a value between 0 and 1. + - `local_shell: object { type }` - - `text: optional string` + A tool that allows the model to execute shell commands in a local environment. - The text that was retrieved from the file. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + A tool that allows the model to execute shell commands. - 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. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `id: string` + 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) - The unique ID of the computer call. + - `beta_namespace_tool: object { description, name, tools, type }` - - `call_id: string` + Groups function/custom tools under a shared namespace. - An identifier used when responding to the tool call with output. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `pending_safety_checks: array of object { id, code, message }` + Hosted or BYOT tool search configuration for deferred tools. - The pending safety checks for the computer call. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `id: string` + 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). - The ID of the pending safety check. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `code: optional string` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the pending safety check. + - `type: "tool_search_output"` - - `message: optional string` + The type of the item. Always `tool_search_output`. - Details about the pending safety check. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "completed" or "incomplete"` + The agent that produced this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `created_by: optional string` - - `"incomplete"` + The identifier of the actor that created the item. - - `type: "computer_call"` + - `additional_tools: object { id, role, tools, 2 more }` - The type of the computer call. Always `computer_call`. + - `id: string` - - `"computer_call"` + The unique ID of the additional tools item. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `role: "unknown" or "user" or "assistant" or 5 more` - A click action. + The role that provided the additional tools. - - `click: object { button, type, x, 2 more }` + - `"unknown"` - A click action. + - `"user"` - - `button: "left" or "right" or "wheel" or 2 more` + - `"assistant"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"system"` - - `"left"` + - `"critic"` - - `"right"` + - `"discriminator"` - - `"wheel"` + - `"developer"` - - `"back"` + - `"tool"` - - `"forward"` + - `tools: array of BetaTool` - - `type: "click"` + The additional tool definitions made available at this item. - Specifies the event type. For a click action, this property is always `click`. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `x: number` + 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). - The x-coordinate where the click occurred. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `y: number` + 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). - The y-coordinate where the click occurred. + - `beta_computer_tool: object { type }` - - `keys: optional array of string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The keys being held while clicking. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `double_click: object { keys, type, x, y }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A double click action. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `keys: array of string` + 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). - The keys being held while double-clicking. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `type: "double_click"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `code_interpreter: object { container, type, allowed_callers }` - - `x: number` + A tool that runs Python code to help generate a response to a prompt. - The x-coordinate where the double click occurred. + - `programmatic_tool_calling: object { type }` - - `y: number` + - `image_generation: object { type, action, background, 9 more }` - The y-coordinate where the double click occurred. + A tool that generates images using the GPT image models. - - `drag: object { path, type, keys }` + - `local_shell: object { type }` - A drag action. + A tool that allows the model to execute shell commands in a local environment. - - `path: array of object { x, y }` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + A tool that allows the model to execute shell commands. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `x: number` + 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) - The x-coordinate. + - `beta_namespace_tool: object { description, name, tools, type }` - - `y: number` + Groups function/custom tools under a shared namespace. - The y-coordinate. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `type: "drag"` + Hosted or BYOT tool search configuration for deferred tools. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `keys: optional array of string` + 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). - The keys being held while dragging the mouse. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `keypress: object { keys, type }` + Allows the assistant to create, delete, or update files using unified diffs. - A collection of keypresses the model would like to perform. + - `type: "additional_tools"` - - `keys: array of string` + The type of the item. Always `additional_tools`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `agent: optional object { agent_name }` - - `type: "keypress"` + The agent that produced this item. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `agent_name: string` - - `move: object { type, x, y, keys }` + The canonical name of the agent that produced this item. - A mouse move action. + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - `type: "move"` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - Specifies the event type. For a move action, this property is always set to `move`. + - `id: string` - - `x: number` + The unique ID of the compaction item. - The x-coordinate to move to. + - `encrypted_content: string` - - `y: number` + The encrypted content that was produced by compaction. - The y-coordinate to move to. + - `type: "compaction"` - - `keys: optional array of string` + The type of the item. Always `compaction`. - The keys being held while moving the mouse. + - `agent: optional object { agent_name }` - - `screenshot: object { type }` + The agent that produced this item. - A screenshot action. + - `agent_name: string` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + The canonical name of the agent that produced this item. - A scroll action. + - `created_by: optional string` - - `scroll_x: number` + The identifier of the actor that created the item. - The horizontal scroll distance. + - `image_generation_call: object { id, result, status, 2 more }` - - `scroll_y: number` + An image generation request made by the model. - The vertical scroll distance. + - `id: string` - - `type: "scroll"` + The unique ID of the image generation call. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `result: string` - - `x: number` + The generated image encoded in base64. - The x-coordinate where the scroll occurred. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `y: number` + The status of the image generation call. - The y-coordinate where the scroll occurred. + - `"in_progress"` - - `keys: optional array of string` + - `"completed"` - The keys being held while scrolling. + - `"generating"` - - `type: object { text, type }` + - `"failed"` - An action to type in text. + - `type: "image_generation_call"` - - `text: string` + The type of the image generation call. Always `image_generation_call`. - The text to type. + - `agent: optional object { agent_name }` - - `type: "type"` + The agent that produced this item. - Specifies the event type. For a type action, this property is always set to `type`. + - `agent_name: string` - - `wait: object { type }` + The canonical name of the agent that produced this item. - A wait action. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `actions: optional array of BetaComputerAction` + A tool call to run code. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `id: string` - - `click: object { button, type, x, 2 more }` + The unique ID of the code interpreter tool call. - A click action. + - `code: string` - - `double_click: object { keys, type, x, y }` + The code to run, or null if not available. - A double click action. + - `container_id: string` - - `drag: object { path, type, keys }` + The ID of the container used to run the code. - A drag action. + - `outputs: array of object { logs, type } or object { type, url }` - - `keypress: object { keys, type }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - A collection of keypresses the model would like to perform. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `move: object { type, x, y, keys }` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - A mouse move action. + - `type: "code_interpreter_call"` - - `screenshot: object { type }` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A screenshot action. + - `agent: optional object { agent_name }` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + The agent that produced this item. - A scroll action. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `type: object { text, type }` + A tool call to run a command on the local shell. - An action to type in text. + - `id: string` - - `wait: object { type }` + The unique ID of the local shell call. - A wait action. + - `action: object { command, env, type, 3 more }` - - `agent: optional object { agent_name }` + Execute a shell command on the server. - The agent that produced this item. + - `command: array of string` - - `agent_name: string` + The command to run. - The canonical name of the agent that produced this item. + - `env: map[string]` - - `computer_call_output: object { call_id, output, type, 4 more }` + Environment variables to set for the command. - The output of a computer tool call. + - `type: "exec"` - - `call_id: string` + The type of the local shell action. Always `exec`. - The ID of the computer tool call that produced the output. + - `timeout_ms: optional number` - - `output: object { type, file_id, image_url }` + Optional timeout in milliseconds for the command. - A computer screenshot image used with the computer use tool. + - `user: optional string` - - `type: "computer_screenshot"` + Optional user to run the command as. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `working_directory: optional string` - - `file_id: optional string` + Optional working directory to run the command in. - The identifier of an uploaded file that contains the screenshot. + - `call_id: string` - - `image_url: optional string` + The unique ID of the local shell tool call generated by the model. - The URL of the screenshot image. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "computer_call_output"` + The status of the local shell call. - The type of the computer tool call output. Always `computer_call_output`. + - `"in_progress"` - - `id: optional string` + - `"completed"` - The ID of the computer tool call output. + - `"incomplete"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "local_shell_call"` - The safety checks reported by the API that have been acknowledged by the developer. + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. - `id: string` - The ID of the pending safety check. + The unique ID of the local shell tool call generated by the model. - - `code: optional string` + - `output: string` - The type of the pending safety check. + A JSON string of the output of the local shell tool call. - - `message: optional string` + - `type: "local_shell_call_output"` - Details about the pending safety check. + The type of the local shell tool call output. Always `local_shell_call_output`. - `agent: optional object { agent_name }` @@ -57640,7 +68144,7 @@ openai beta:responses compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -57648,124 +68152,159 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - 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. + A tool call that executes one or more shell commands in a managed environment. - `id: string` - The unique ID of the web search tool call. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `action: object { commands, max_output_length, timeout_ms }` - 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). + The shell commands and limits that describe how to run the tool call. - - `search: object { type, queries, query, sources }` + - `commands: array of string` - Action type "search" - Performs a web search query. + - `max_output_length: number` - - `type: "search"` + Optional maximum number of characters to return from each command. - The action type. + - `timeout_ms: number` - - `queries: optional array of string` + Optional timeout in milliseconds for the commands. - The search queries. + - `call_id: string` - - `query: optional string` + The unique ID of the shell tool call generated by the model. - The search query. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `sources: optional array of object { type, url }` + Represents the use of a local environment to perform shell actions. - The sources used in the search. + - `beta_response_local_environment: object { type }` - - `type: "url"` + Represents the use of a local environment to perform shell actions. - The type of source. Always `url`. + - `type: "local"` - - `url: string` + The environment type. Always `local`. - The URL of the source. + - `beta_response_container_reference: object { container_id, type }` - - `open_page: object { type, url }` + Represents a container created with /v1/containers. - Action type "open_page" - Opens a specific URL from search results. + - `container_id: string` - - `type: "open_page"` + - `type: "container_reference"` - The action type. + The environment type. Always `container_reference`. - - `url: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The URL opened by the model. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `find_in_page: object { pattern, type, url }` + - `"in_progress"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"completed"` - - `pattern: string` + - `"incomplete"` - The pattern or text to search for within the page. + - `type: "shell_call"` - - `type: "find_in_page"` + The type of the item. Always `shell_call`. - The action type. + - `agent: optional object { agent_name }` - - `url: string` + The agent that produced this item. - The URL of the page searched for the pattern. + - `agent_name: string` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The canonical name of the agent that produced this item. - The status of the web search tool call. + - `caller: optional object { type } or object { caller_id, type }` - - `"in_progress"` + The execution context that produced this tool call. - - `"searching"` + - `direct: object { type }` - - `"completed"` + - `program: object { caller_id, type }` - - `"failed"` + - `caller_id: string` - - `type: "web_search_call"` + The call ID of the program item that produced this tool call. - The type of the web search tool call. Always `web_search_call`. + - `type: "program"` - - `agent: optional object { agent_name }` + - `created_by: optional string` - The agent that produced this item. + The ID of the entity that created this tool call. - - `agent_name: string` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - The canonical name of the agent that produced this item. + The output of a shell tool call that was emitted. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `id: string` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The unique ID of the shell call output. Populated when this item is returned via API. - - `arguments: string` + - `call_id: string` - A JSON string of the arguments to pass to the function. + The unique ID of the shell tool call generated by the model. - - `call_id: string` + - `max_output_length: number` - The unique ID of the function tool call generated by the model. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `name: string` + - `output: array of object { outcome, stderr, stdout, created_by }` - The name of the function to run. + An array of shell call output contents - - `type: "function_call"` + - `outcome: object { type } or object { exit_code, type }` - The type of the function tool call. Always `function_call`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `id: optional string` + - `timeout: object { type }` - The unique ID of the function tool call. + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + The standard error output that was captured. + + - `stdout: string` + + The standard output that was captured. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. - `agent: optional object { agent_name }` @@ -57789,146 +68328,131 @@ openai beta:responses compact \ - `type: "program"` - - `namespace: optional string` - - The namespace of the function to run. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `function_call_output: object { call_id, output, type, 4 more }` + - `id: string` - The output of a function tool call. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` - The unique ID of the function tool call generated by the model. - - - `output: string or BetaResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `union_member_0: string` - - A JSON string of the output of the function tool call. + The unique ID of the apply patch tool call generated by the model. - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - An array of content outputs (text, image, file) for the function tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `create_file: object { diff, path, type }` - A text input to the model. + Instruction describing how to create a file via the apply_patch tool. - - `text: string` + - `diff: string` - The text input to the model. + Diff to apply. - - `type: "input_text"` + - `path: string` - The type of the input item. Always `input_text`. + Path of the file to create. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "create_file"` - 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. + Create a new file with the provided diff. - - `mode: "explicit"` + - `delete_file: object { path, type }` - The breakpoint mode. Always `explicit`. + Instruction describing how to delete a file via the apply_patch tool. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `path: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + Path of the file to delete. - - `type: "input_image"` + - `type: "delete_file"` - The type of the input item. Always `input_image`. + Delete the specified file. - - `detail: optional "low" or "high" or "auto" or "original"` + - `update_file: object { diff, path, type }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Instruction describing how to update a file via the apply_patch tool. - - `"low"` + - `diff: string` - - `"high"` + Diff to apply. - - `"auto"` + - `path: string` - - `"original"` + Path of the file to update. - - `file_id: optional string` + - `type: "update_file"` - The ID of the file to be sent to the model. + Update an existing file with the provided diff. - - `image_url: optional string` + - `status: "in_progress" or "completed"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"in_progress"` - 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. + - `"completed"` - - `mode: "explicit"` + - `type: "apply_patch_call"` - The breakpoint mode. Always `explicit`. + The type of the item. Always `apply_patch_call`. - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `agent: optional object { agent_name }` - A file input to the model. + The agent that produced this item. - - `type: "input_file"` + - `agent_name: string` - The type of the input item. Always `input_file`. + The canonical name of the agent that produced this item. - - `detail: optional "auto" or "low" or "high"` + - `caller: optional object { type } or object { caller_id, type }` - 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`. + The execution context that produced this tool call. - - `"auto"` + - `direct: object { type }` - - `"low"` + - `program: object { caller_id, type }` - - `"high"` + - `caller_id: string` - - `file_data: optional string` + The call ID of the program item that produced this tool call. - The base64-encoded data of the file to be sent to the model. + - `type: "program"` - - `file_id: optional string` + - `created_by: optional string` - The ID of the file to be sent to the model. + The ID of the entity that created this tool call. - - `file_url: optional string` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - The URL of the file to be sent to the model. + The output emitted by an apply patch tool call. - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `prompt_cache_breakpoint: optional object { mode }` + - `call_id: string` - 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. + The unique ID of the apply patch tool call generated by the model. - - `mode: "explicit"` + - `status: "completed" or "failed"` - The breakpoint mode. Always `explicit`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `type: "function_call_output"` + - `"completed"` - The type of the function tool call output. Always `function_call_output`. + - `"failed"` - - `id: optional string` + - `type: "apply_patch_call_output"` - The unique ID of the function tool call output. Populated when this item is returned via API. + The type of the item. Always `apply_patch_call_output`. - `agent: optional object { agent_name }` @@ -57952,93 +68476,108 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. + - `created_by: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The ID of the entity that created this tool call output. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `output: optional string` - - `"in_progress"` + Optional textual output returned by the apply patch tool. - - `"completed"` + - `mcp_call: object { id, arguments, name, 7 more }` - - `"incomplete"` + An invocation of a tool on an MCP server. - - `agent_message: object { author, content, recipient, 3 more }` + - `id: string` - A message routed between agents. + The unique ID of the tool call. - - `author: string` + - `arguments: string` - The sending agent identity. + A JSON string of the arguments passed to the tool. - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `name: string` - Plaintext, image, or encrypted content sent between agents. + The name of the tool that was run. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `server_label: string` - A text input to the model. + The label of the MCP server running the tool. - - `text: string` + - `type: "mcp_call"` - The text input to the model. + The type of the item. Always `mcp_call`. - - `type: "input_text"` + - `agent: optional object { agent_name }` - The type of the input item. Always `input_text`. + The agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `approval_request_id: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + 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. - - `type: "input_image"` + - `error: optional string` - The type of the input item. Always `input_image`. + The error from the tool call, if any. - - `detail: optional "low" or "high" or "auto" or "original"` + - `output: optional string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The output from the tool call. - - `file_id: optional string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The ID of the file to be sent to the model. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `image_url: optional string` + - `"in_progress"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"completed"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"incomplete"` - 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. + - `"calling"` - - `encrypted_content: object { encrypted_content, type }` + - `"failed"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `encrypted_content: string` + A list of tools available on an MCP server. - Opaque encrypted content. + - `id: string` - - `type: "encrypted_content"` + The unique ID of the list. - The type of the input item. Always `encrypted_content`. + - `server_label: string` - - `recipient: string` + The label of the MCP server. - The destination agent identity. + - `tools: array of object { input_schema, name, annotations, description }` - - `type: "agent_message"` + The tools available on the server. - The item type. Always `agent_message`. + - `input_schema: unknown` - - `id: optional string` + The JSON schema describing the tool's input. - The unique ID of this agent message item. + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. - `agent: optional object { agent_name }` @@ -58048,39 +68587,33 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. - - - `"spawn_agent"` + - `error: optional string` - - `"interrupt_agent"` + Error message if the server could not list tools. - - `"list_agents"` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `"send_message"` + A request for human approval of a tool invocation. - - `"followup_task"` + - `id: string` - - `"wait_agent"` + The unique ID of the approval request. - `arguments: string` - The action arguments as a JSON string. + A JSON string of arguments for the tool. - - `call_id: string` + - `name: string` - The unique ID linking this call to its output. + The name of the tool to run. - - `type: "multi_agent_call"` + - `server_label: string` - The item type. Always `multi_agent_call`. + The label of the MCP server making the request. - - `id: optional string` + - `type: "mcp_approval_request"` - The unique ID of this multi-agent call. + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` @@ -58090,1213 +68623,1254 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - - `"spawn_agent"` + A response to an MCP approval request. - - `"interrupt_agent"` + - `id: string` - - `"list_agents"` + The unique ID of the approval response - - `"send_message"` + - `approval_request_id: string` - - `"followup_task"` + The ID of the approval request being answered. - - `"wait_agent"` + - `approve: boolean` - - `call_id: string` + Whether the request was approved. - The unique ID of the multi-agent call. + - `type: "mcp_approval_response"` - - `output: array of object { text, type, annotations }` + The type of the item. Always `mcp_approval_response`. - Text output returned by the multi-agent action. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The text content. + - `agent_name: string` - - `type: "output_text"` + The canonical name of the agent that produced this item. - The content type. Always `output_text`. + - `reason: optional string` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + Optional reason for the decision. - Citations associated with the text content. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `union_member_0: array of object { file_id, filename, index, type }` + A call to a custom tool created by the model. - - `file_id: string` + - `call_id: string` - The ID of the file. + An identifier used to map this custom tool call to a tool call output. - - `filename: string` + - `input: string` - The filename of the file cited. + The input for the custom tool call generated by the model. - - `index: number` + - `name: string` - The index of the file in the list of files. + The name of the custom tool being called. - - `type: "file_citation"` + - `type: "custom_tool_call"` - The citation type. Always `file_citation`. + The type of the custom tool call. Always `custom_tool_call`. - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + - `id: optional string` - - `end_index: number` + The unique ID of the custom tool call in the OpenAI platform. - The index of the last character of the citation in the message. + - `agent: optional object { agent_name }` - - `start_index: number` + The agent that produced this item. - The index of the first character of the citation in the message. + - `caller: optional object { type } or object { caller_id, type }` - - `title: string` + The execution context that produced this tool call. - The title of the cited resource. + - `namespace: optional string` - - `type: "url_citation"` + The namespace of the custom tool being called. - The citation type. Always `url_citation`. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `url: string` + The output of a custom tool call from your code, being sent back to the model. - The URL of the cited resource. + - `id: string` - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + The unique ID of the custom tool call output item. - - `container_id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The ID of the container. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `end_index: number` + - `"in_progress"` - The index of the last character of the citation in the message. + - `"completed"` - - `file_id: string` + - `"incomplete"` - The ID of the container file. + - `created_by: optional string` - - `filename: string` + The identifier of the actor that created the item. - The filename of the container file cited. + - `parallel_tool_calls: boolean` - - `start_index: number` + Whether to allow the model to run tool calls in parallel. - The index of the first character of the citation in the message. + - `temperature: number` - - `type: "container_file_citation"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The citation type. Always `container_file_citation`. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `type: "multi_agent_call_output"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The item type. Always `multi_agent_call_output`. + - `beta_tool_choice_options: "none" or "auto" or "required"` - - `id: optional string` + Controls which (if any) tool is called by the model. - The unique ID of this multi-agent call output. + `none` means the model will not call any tool and instead generates a message. - - `agent: optional object { agent_name }` + `auto` means the model can pick between generating a message or calling one or + more tools. - The agent that produced this item. + `required` means the model must call one or more tools. - - `agent_name: string` + - `"none"` - The canonical name of the agent that produced this item. + - `"auto"` - - `tool_search_call: object { arguments, type, id, 4 more }` + - `"required"` - - `arguments: unknown` + - `beta_tool_choice_allowed: object { mode, tools, type }` - The arguments supplied to the tool search call. + Constrains the tools available to the model to a pre-defined set. - - `type: "tool_search_call"` + - `mode: "auto" or "required"` - The item type. Always `tool_search_call`. + Constrains the tools available to the model to a pre-defined set. - - `id: optional string` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The unique ID of this tool search call. + `required` requires the model to call one or more of the allowed tools. - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"required"` - - `agent_name: string` + - `tools: array of map[unknown]` - The canonical name of the agent that produced this item. + A list of tool definitions that the model should be allowed to call. - - `call_id: optional string` + For the Responses API, the list of tool definitions might look like: - The unique ID of the tool search call generated by the model. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `execution: optional "server" or "client"` + - `type: "allowed_tools"` - Whether tool search was executed by the server or by the client. + Allowed tool configuration type. Always `allowed_tools`. - - `"server"` + - `beta_tool_choice_types: object { type }` - - `"client"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - The status of the tool search call. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `"in_progress"` + Allowed values are: - - `"completed"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"incomplete"` + - `"file_search"` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + - `"web_search_preview"` - - `tools: array of BetaTool` + - `"computer"` - The loaded tool definitions returned by the tool search output. + - `"computer_use_preview"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `"computer_use"` - 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). + - `"web_search_preview_2025_03_11"` - - `name: string` + - `"image_generation"` - The name of the function to call. + - `"code_interpreter"` - - `parameters: map[unknown]` + - `beta_tool_choice_function: object { name, type }` - A JSON schema object describing the parameters of the function. + Use this option to force the model to call a specific function. - - `strict: boolean` + - `name: string` - Whether strict parameter validation is enforced for this function tool. + The name of the function to call. - `type: "function"` - The type of the function tool. Always `function`. - - - `allowed_callers: optional array of "direct" or "programmatic"` + For function calling, the type is always `function`. - The tool invocation context(s). + - `beta_tool_choice_mcp: object { server_label, type, name }` - - `"direct"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `"programmatic"` + - `server_label: string` - - `defer_loading: optional boolean` + The label of the MCP server to use. - Whether this function is deferred and loaded via tool search. + - `type: "mcp"` - - `description: optional string` + For MCP tools, the type is always `mcp`. - A description of the function. Used by the model to determine whether or not to call the function. + - `name: optional string` - - `output_schema: optional map[unknown]` + The name of the tool to call on the server. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `beta_tool_choice_custom: object { name, type }` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + Use this option to force the model to call a specific custom tool. - 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). + - `name: string` - - `type: "file_search"` + The name of the custom tool to call. - The type of the file search tool. Always `file_search`. + - `type: "custom"` - - `vector_store_ids: array of string` + For custom tool calling, the type is always `custom`. - The IDs of the vector stores to search. + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - - `filters: optional object { key, type, value } or object { filters, type }` + - `beta_tool_choice_apply_patch: object { type }` - A filter to apply. + Forces the model to call the apply_patch tool when executing a tool call. - - `Comparison Filter: object { key, type, value }` + - `type: "apply_patch"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The tool to call. Always `apply_patch`. - - `key: string` + - `beta_tool_choice_shell: object { type }` - The key to compare against the value. + Forces the model to call the shell tool when a tool call is required. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "shell"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The tool to call. Always `shell`. - - `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 + - `tools: array of BetaTool` - - `"eq"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"ne"` + We support the following categories of tools: - - `"gt"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"gte"` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `"lt"` + 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). - - `"lte"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"in"` + 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). - - `"nin"` + - `beta_computer_tool: object { type }` - - `value: string or number or boolean or array of unknown` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The value to compare against the attribute key; supports string, number, or boolean types. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `union_member_0: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `union_member_1: number` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `union_member_2: boolean` + 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). - - `union_member_3: array of unknown` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `Compound Filter: object { filters, type }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Combine multiple filters using `and` or `or`. + - `code_interpreter: object { container, type, allowed_callers }` - - `filters: array of object { key, type, value } or unknown` + A tool that runs Python code to help generate a response to a prompt. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `programmatic_tool_calling: object { type }` - - `Comparison Filter: object { key, type, value }` + - `image_generation: object { type, action, background, 9 more }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A tool that generates images using the GPT image models. - - `key: string` + - `local_shell: object { type }` - The key to compare against the value. + A tool that allows the model to execute shell commands in a local environment. - - `type: "eq" or "ne" or "gt" or 5 more` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A tool that allows the model to execute shell commands. - - `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 + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"eq"` + 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) - - `"ne"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `"gt"` + Groups function/custom tools under a shared namespace. - - `"gte"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `"lt"` + Hosted or BYOT tool search configuration for deferred tools. - - `"lte"` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"in"` + 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). - - `"nin"` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `value: string or number or boolean or array of unknown` + Allows the assistant to create, delete, or update files using unified diffs. - The value to compare against the attribute key; supports string, number, or boolean types. + - `top_p: number` - - `union_member_0: string` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `union_member_1: number` + We generally recommend altering this or `temperature` but not both. - - `union_member_2: boolean` + - `background: optional boolean` - - `union_member_3: array of unknown` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `union_member_1: unknown` + - `completed_at: optional number` - - `type: "and" or "or"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - Type of operation: `and` or `or`. + - `conversation: optional object { id }` - - `"and"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `"or"` + - `id: string` - - `max_num_results: optional number` + The unique ID of the conversation that this response was associated with. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `max_output_tokens: optional number` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - Ranking options for search. + - `max_tool_calls: optional number` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `moderation: optional object { input, output }` - - `embedding_weight: number` + Moderation results for the response input and output, if moderated completions were requested. - The weight of the embedding in the reciprocal ranking fusion. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `text_weight: number` + Moderation for the response input. - The weight of the text in the reciprocal ranking fusion. + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `ranker: optional "auto" or "default-2024-11-15"` + A moderation result produced for the response input or output. - The ranker to use for the file search. + - `categories: map[boolean]` - - `"auto"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"default-2024-11-15"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `score_threshold: optional number` + Which modalities of input are reflected by the score for each category. - 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. + - `"text"` - - `beta_computer_tool: object { type }` + - `"image"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `category_scores: map[number]` - - `type: "computer"` + A dictionary of moderation categories to scores. - The type of the computer tool. Always `computer`. + - `flagged: boolean` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + A boolean indicating whether the content was flagged by any category. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `model: string` - - `display_height: number` + The moderation model that produced this result. - The height of the computer display. + - `type: "moderation_result"` - - `display_width: number` + The object type, which was always `moderation_result` for successful moderation results. - The width of the computer display. + - `error: object { code, message, type }` - - `environment: "windows" or "mac" or "linux" or 2 more` + An error produced while attempting moderation for the response input or output. - The type of computer environment to control. + - `code: string` - - `"windows"` + The error code. - - `"mac"` + - `message: string` - - `"linux"` + The error message. - - `"ubuntu"` + - `type: "error"` - - `"browser"` + The object type, which was always `error` for moderation failures. - - `type: "computer_use_preview"` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - The type of the computer use tool. Always `computer_use_preview`. + Moderation for the response output. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - 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). + A moderation result produced for the response input or output. - - `type: "web_search" or "web_search_2025_08_26"` + - `categories: map[boolean]` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"web_search"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"web_search_2025_08_26"` + Which modalities of input are reflected by the score for each category. - - `filters: optional object { allowed_domains }` + - `"text"` - Filters for the search. + - `"image"` - - `allowed_domains: optional array of string` + - `category_scores: map[number]` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A dictionary of moderation categories to scores. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `flagged: boolean` - - `search_context_size: optional "low" or "medium" or "high"` + A boolean indicating whether the content was flagged by any category. - 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. + - `model: string` - - `"low"` + The moderation model that produced this result. - - `"medium"` + - `type: "moderation_result"` - - `"high"` + The object type, which was always `moderation_result` for successful moderation results. - - `user_location: optional object { city, country, region, 2 more }` + - `error: object { code, message, type }` - The approximate location of the user. + An error produced while attempting moderation for the response input or output. - - `city: optional string` + - `code: string` - Free text input for the city of the user, e.g. `San Francisco`. + The error code. - - `country: optional string` + - `message: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The error message. - - `region: optional string` + - `type: "error"` - Free text input for the region of the user, e.g. `California`. + The object type, which was always `error` for moderation failures. - - `timezone: optional string` + - `previous_response_id: optional string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + 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`. - - `type: optional "approximate"` + - `prompt: optional object { id, variables, version }` - The type of location approximation. Always `approximate`. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `"approximate"` + - `id: string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The unique identifier of the prompt template to use. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `server_label: string` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - A label for this MCP server, used to identify it in tool calls. + - `union_member_0: string` - - `type: "mcp"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The type of the MCP tool. Always `mcp`. + A text input to the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The tool invocation context(s). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"direct"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"programmatic"` + A file input to the model. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `version: optional string` - List of allowed tool names or a filter object. + Optional version of the prompt template. - - `MCP allowed tools: array of string` + - `prompt_cache_key: optional string` - A string array of allowed tool names + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `MCP tool filter: object { read_only, tool_names }` + - `prompt_cache_options: optional object { mode, ttl }` - A filter object to specify which tools are allowed. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `read_only: optional boolean` + - `mode: "implicit" or "explicit"` - 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. + Whether implicit prompt-cache breakpoints were enabled. - - `tool_names: optional array of string` + - `"implicit"` - List of allowed tool names. + - `"explicit"` - - `authorization: optional string` + - `ttl: "30m"` - 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. + The minimum lifetime applied to each cache breakpoint. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"30m"` - 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). + - `prompt_cache_retention: optional "in_memory" or "24h"` - Currently supported `connector_id` values are: + Deprecated. Use `prompt_cache_options.ttl` instead. - - 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` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"connector_dropbox"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"connector_gmail"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `"connector_googlecalendar"` + - `"in_memory"` - - `"connector_googledrive"` + - `"24h"` - - `"connector_microsoftteams"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `"connector_outlookcalendar"` + **gpt-5 and o-series models only** - - `"connector_outlookemail"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `"connector_sharepoint"` + - `context: optional "auto" or "current_turn" or "all_turns"` - - `defer_loading: optional boolean` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - Whether this MCP tool is deferred and discovered via tool search. + - `"auto"` - - `headers: optional map[string]` + - `"current_turn"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"all_turns"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - Specify which of the MCP server's tools require approval. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `MCP tool approval filter: object { always, never }` + - `"none"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"minimal"` - - `always: optional object { read_only, tool_names }` + - `"low"` - A filter object to specify which tools are allowed. + - `"medium"` - - `read_only: optional boolean` + - `"high"` - 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. + - `"xhigh"` - - `tool_names: optional array of string` + - `"max"` - List of allowed tool names. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `never: optional object { read_only, tool_names }` + **Deprecated:** use `summary` instead. - A filter object to specify which tools are allowed. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `read_only: optional boolean` + - `"auto"` - 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. + - `"concise"` - - `tool_names: optional array of string` + - `"detailed"` - List of allowed tool names. + - `mode: optional string or "standard" or "pro"` - - `MCP tool approval setting: "always" or "never"` + Controls the reasoning execution mode for the request. - 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. + When returned on a response, this is the effective execution mode. - - `"always"` + - `"standard"` - - `"never"` + - `"pro"` - - `server_description: optional string` + - `summary: optional "auto" or "concise" or "detailed"` - Optional description of the MCP server, used to provide more context. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `server_url: optional string` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"auto"` - - `tunnel_id: optional string` + - `"concise"` - 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. + - `"detailed"` - - `code_interpreter: object { container, type, allowed_callers }` + - `safety_identifier: optional string` - A tool that runs Python code to help generate a response to a prompt. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - 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. + Specifies the processing type used for serving the request. - - `union_member_0: string` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The container ID. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + - `"auto"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"default"` - - `type: "auto"` + - `"flex"` - Always `auto`. + - `"scale"` - - `file_ids: optional array of string` + - `"priority"` - An optional list of uploaded files to make available to your code. + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The memory limit for the code interpreter container. + - `"completed"` - - `"1g"` + - `"failed"` - - `"4g"` + - `"in_progress"` - - `"16g"` + - `"cancelled"` - - `"64g"` + - `"queued"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"incomplete"` - Network access policy for the container. + - `text: optional object { format, verbosity }` - - `beta_container_network_policy_disabled: object { type }` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `type: "disabled"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - Disable outbound network access. Always `disabled`. + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + An object specifying the format that the model must output. - - `allowed_domains: array of string` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - A list of allowed domains when type is `allowlist`. + The default format is `{ "type": "text" }` with no additional options. - - `type: "allowlist"` + **Not recommended for gpt-4o and newer models:** - Allow outbound network access only to specified domains. Always `allowlist`. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `text: object { type }` - Optional domain-scoped secrets for allowlisted domains. + Default response format. Used to generate text responses. - - `domain: string` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - The domain associated with the secret. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - `name: string` - The name of the secret to inject for the domain. - - - `value: string` - - The secret value to inject for the domain. - - - `type: "code_interpreter"` - - The type of the code interpreter tool. Always `code_interpreter`. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `schema: map[unknown]` - The tool invocation context(s). + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"direct"` + - `type: "json_schema"` - - `"programmatic"` + The type of response format being defined. Always `json_schema`. - - `programmatic_tool_calling: object { type }` + - `description: optional string` - - `image_generation: object { type, action, background, 9 more }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - A tool that generates images using the GPT image models. + - `strict: optional boolean` - - `type: "image_generation"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The type of the image generation tool. Always `image_generation`. + - `json_object: object { type }` - - `action: optional "generate" or "edit" or "auto"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `verbosity: optional "low" or "medium" or "high"` - - `"generate"` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `"edit"` + - `"low"` - - `"auto"` + - `"medium"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"high"` - 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. + - `top_logprobs: optional number` - `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. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `truncation: optional "auto" or "disabled"` - - `"transparent"` + The truncation strategy to use for the model response. - - `"opaque"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - `"auto"` - - `input_fidelity: optional "high" or "low"` - - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - - `"high"` - - - `"low"` + - `"disabled"` - - `input_image_mask: optional object { file_id, image_url }` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `file_id: optional string` + - `input_tokens: number` - File ID for the mask image. + The number of input tokens. - - `image_url: optional string` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - Base64-encoded mask image. + A detailed breakdown of the input tokens. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `cache_write_tokens: number` - The image generation model to use. Default: `gpt-image-1`. + The number of input tokens that were written to the cache. - - `"gpt-image-1"` + - `cached_tokens: number` - - `"gpt-image-1-mini"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `"gpt-image-2"` + - `output_tokens: number` - - `"gpt-image-2-2026-04-21"` + The number of output tokens. - - `"gpt-image-1.5"` + - `output_tokens_details: object { reasoning_tokens }` - - `"chatgpt-image-latest"` + A detailed breakdown of the output tokens. - - `moderation: optional "auto" or "low"` + - `reasoning_tokens: number` - Moderation level for the generated image. Default: `auto`. + The number of reasoning tokens. - - `"auto"` + - `total_tokens: number` - - `"low"` + The total number of tokens used. - - `output_compression: optional number` + - `user: optional string` - Compression level for the output image. Default: 100. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `output_format: optional "png" or "webp" or "jpeg"` + - `sequence_number: number` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The sequence number of this event. - - `"png"` + - `type: "response.incomplete"` - - `"webp"` + The type of the event. Always `response.incomplete`. - - `"jpeg"` + - `agent: optional object { agent_name }` - - `partial_images: optional number` + The agent that owns this multi-agent streaming event. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `agent_name: string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The canonical name of the agent that produced this item. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. +### Beta Response Inject Created Event - - `"low"` +- `beta_response_inject_created_event: object { response_id, sequence_number, type, stream_id }` - - `"medium"` + Emitted when all injected input items were validated and committed to the + active response. - - `"high"` + - `response_id: string` - - `"auto"` + The ID of the response that accepted the input. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `sequence_number: number` - 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`. + The sequence number for this event. - - `"1024x1024"` + - `type: "response.inject.created"` - - `"1024x1536"` + The event discriminator. Always `response.inject.created`. - - `"1536x1024"` + - `stream_id: optional string` - - `"auto"` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `local_shell: object { type }` +### Beta Response Inject Event - A tool that allows the model to execute shell commands in a local environment. +- `beta_response_inject_event: object { input, response_id, type }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. - A tool that allows the model to execute shell commands. + - `input: array of BetaResponseInputItem` - - `type: "shell"` + Input items to inject into the active response. - The type of the shell tool. Always `shell`. + - `beta_easy_input_message: object { content, role, phase, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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. - The tool invocation context(s). + - `content: string or BetaResponseInputMessageContentList` - - `"direct"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"programmatic"` + - `Text input: string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + A text input to the model. - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - `type: "container_auto"` + A list of one or many input items to the model, containing different content + types. - Automatically creates a container for this request + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `file_ids: optional array of string` + A text input to the model. - An optional list of uploaded files to make available to your code. + - `text: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The text input to the model. - The memory limit for the container. + - `type: "input_text"` - - `"1g"` + The type of the input item. Always `input_text`. - - `"4g"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"16g"` + 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. - - `"64g"` + - `mode: "explicit"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The breakpoint mode. Always `explicit`. - Network access policy for the container. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `beta_container_network_policy_disabled: object { type }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `detail: "low" or "high" or "auto" or "original"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - An optional list of skills referenced by id or inline data. + - `"low"` - - `beta_skill_reference: object { skill_id, type, version }` + - `"high"` - - `skill_id: string` + - `"auto"` - The ID of the referenced skill. + - `"original"` - - `type: "skill_reference"` + - `type: "input_image"` - References a skill created with the /v1/skills endpoint. + The type of the input item. Always `input_image`. - - `version: optional string` + - `file_id: optional string` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The ID of the file to be sent to the model. - - `beta_inline_skill: object { description, name, source, type }` + - `image_url: optional string` - - `description: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The description of the skill. + - `prompt_cache_breakpoint: optional object { mode }` - - `name: string` + 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. - The name of the skill. + - `mode: "explicit"` - - `source: object { data, media_type, type }` + The breakpoint mode. Always `explicit`. - Inline skill payload + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `data: string` + A file input to the model. - Base64-encoded skill zip bundle. + - `type: "input_file"` - - `media_type: "application/zip"` + The type of the input item. Always `input_file`. - The media type of the inline skill payload. Must be `application/zip`. + - `detail: optional "auto" or "low" or "high"` - - `type: "base64"` + 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`. - The type of the inline skill source. Must be `base64`. + - `"auto"` - - `type: "inline"` + - `"low"` - Defines an inline skill for this request. + - `"high"` - - `beta_local_environment: object { type, skills }` + - `file_data: optional string` - - `type: "local"` + The content of the file to be sent to the model. - Use a local computer environment. + - `file_id: optional string` - - `skills: optional array of BetaLocalSkill` + The ID of the file to be sent to the model. - An optional list of skills. + - `file_url: optional string` - - `description: string` + The URL of the file to be sent to the model. - The description of the skill. + - `filename: optional string` - - `name: string` + The name of the file to be sent to the model. - The name of the skill. + - `prompt_cache_breakpoint: optional object { mode }` - - `path: string` + 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. - The path to the directory containing the skill. + - `mode: "explicit"` - - `beta_container_reference: object { container_id, type }` + The breakpoint mode. Always `explicit`. - - `container_id: string` + - `role: "user" or "assistant" or "system" or "developer"` - The ID of the referenced container. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `type: "container_reference"` + - `"user"` - References a container created with the /v1/containers endpoint + - `"assistant"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `"system"` - 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) + - `"developer"` - - `name: string` + - `phase: optional "commentary" or "final_answer"` - The name of the custom tool, used to identify it in tool calls. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `type: "custom"` + - `"commentary"` - The type of the custom tool. Always `custom`. + - `"final_answer"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: optional "message"` - The tool invocation context(s). + The type of the message input. Always `message`. - - `"direct"` + - `"message"` - - `"programmatic"` + - `message: object { content, role, agent, 2 more }` - - `defer_loading: optional boolean` + 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. - Whether this tool should be deferred and discovered via tool search. + - `content: array of BetaResponseInputContent` - - `description: optional string` + A list of one or many input items to the model, containing different content + types. - Optional description of the custom tool, used to provide more context. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `format: optional object { type } or object { definition, syntax, type }` + A text input to the model. - The input format for the custom tool. Default is unconstrained text. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `text: object { type }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Unconstrained free-form text. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `grammar: object { definition, syntax, type }` + A file input to the model. - A grammar defined by the user. + - `role: "user" or "system" or "developer"` - - `definition: string` + The role of the message input. One of `user`, `system`, or `developer`. - The grammar definition. + - `"user"` - - `syntax: "lark" or "regex"` + - `"system"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"developer"` - - `"lark"` + - `agent: optional object { agent_name }` - - `"regex"` + The agent that produced this item. - - `type: "grammar"` + - `agent_name: string` - Grammar format. Always `grammar`. + The canonical name of the agent that produced this item. - - `beta_namespace_tool: object { description, name, tools, type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Groups function/custom tools under a shared namespace. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `description: string` + - `"in_progress"` - A description of the namespace shown to the model. + - `"completed"` - - `name: string` + - `"incomplete"` - The namespace name used in tool calls (for example, `crm`). + - `type: optional "message"` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + The type of the message input. Always set to `message`. - The function/custom tools available inside this namespace. + - `"message"` - - `function: object { name, type, allowed_callers, 5 more }` + - `beta_response_output_message: object { id, content, role, 4 more }` - - `name: string` + An output message from the model. - - `type: "function"` + - `id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the output message. - The tool invocation context(s). + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"direct"` + The content of the output message. - - `"programmatic"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `defer_loading: optional boolean` + A text output from the model. - Whether this function should be deferred and discovered via tool search. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `description: optional string` + The annotations of the text output. - - `output_schema: optional map[unknown]` + - `file_citation: object { file_id, filename, index, type }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A citation to a file. - - `parameters: optional unknown` + - `file_id: string` - - `strict: optional boolean` + The ID of the file. - 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. + - `filename: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The filename of the file cited. - 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) + - `index: number` - - `name: string` + The index of the file in the list of files. - The name of the custom tool, used to identify it in tool calls. + - `type: "file_citation"` - - `type: "custom"` + The type of the file citation. Always `file_citation`. - The type of the custom tool. Always `custom`. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A citation for a web resource used to generate a model response. - The tool invocation context(s). + - `end_index: number` - - `defer_loading: optional boolean` + The index of the last character of the URL citation in the message. - Whether this tool should be deferred and discovered via tool search. + - `start_index: number` - - `description: optional string` + The index of the first character of the URL citation in the message. - Optional description of the custom tool, used to provide more context. + - `title: string` - - `format: optional object { type } or object { definition, syntax, type }` + The title of the web resource. - The input format for the custom tool. Default is unconstrained text. + - `type: "url_citation"` - - `type: "namespace"` + The type of the URL citation. Always `url_citation`. - The type of the tool. Always `namespace`. + - `url: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The URL of the web resource. - Hosted or BYOT tool search configuration for deferred tools. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `type: "tool_search"` + A citation for a container file used to generate a model response. - The type of the tool. Always `tool_search`. + - `container_id: string` - - `description: optional string` + The ID of the container file. - Description shown to the model for a client-executed tool search tool. + - `end_index: number` - - `execution: optional "server" or "client"` + The index of the last character of the container file citation in the message. - Whether tool search is executed by the server or by the client. + - `file_id: string` - - `"server"` + The ID of the file. - - `"client"` + - `filename: string` - - `parameters: optional unknown` + The filename of the container file cited. - Parameter schema for a client-executed tool search tool. + - `start_index: number` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The index of the first character of the container file citation in the message. - 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: "container_file_citation"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The type of the container file citation. Always `container_file_citation`. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `file_path: object { file_id, index, type }` - - `"web_search_preview"` + A path to a file. - - `"web_search_preview_2025_03_11"` + - `file_id: string` - - `search_content_types: optional array of "text" or "image"` + The ID of the file. - - `"text"` + - `index: number` - - `"image"` + The index of the file in the list of files. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "file_path"` - 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. + The type of the file path. Always `file_path`. - - `"low"` + - `text: string` - - `"medium"` + The text output from the model. - - `"high"` + - `type: "output_text"` - - `user_location: optional object { type, city, country, 2 more }` + The type of the output text. Always `output_text`. - The user's location. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "approximate"` + - `token: string` - The type of location approximation. Always `approximate`. + - `bytes: array of number` - - `city: optional string` + - `logprob: number` - Free text input for the city of the user, e.g. `San Francisco`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `country: optional string` + - `token: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `bytes: array of number` - - `region: optional string` + - `logprob: number` - Free text input for the region of the user, e.g. `California`. + - `beta_response_output_refusal: object { refusal, type }` - - `timezone: optional string` + A refusal from the model. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `refusal: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The refusal explanation from the model. - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "refusal"` - - `type: "apply_patch"` + The type of the refusal. Always `refusal`. - The type of the tool. Always `apply_patch`. + - `role: "assistant"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The role of the output message. Always `assistant`. - The tool invocation context(s). + - `status: "in_progress" or "completed" or "incomplete"` - - `"direct"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"programmatic"` + - `"in_progress"` - - `type: "tool_search_output"` + - `"completed"` - The item type. Always `tool_search_output`. + - `"incomplete"` - - `id: optional string` + - `type: "message"` - The unique ID of this tool search output. + The type of the output message. Always `message`. - `agent: optional object { agent_name }` @@ -59306,389 +69880,402 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `phase: optional "commentary" or "final_answer"` - The unique ID of the tool search call generated by the model. + 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. - - `execution: optional "server" or "client"` + - `"commentary"` - Whether tool search was executed by the server or by the client. + - `"final_answer"` - - `"server"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `"client"` + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `id: string` - The status of the tool search output. + The unique ID of the file search tool call. - - `"in_progress"` + - `queries: array of string` - - `"completed"` + The queries used to search for files. - - `"incomplete"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `additional_tools: object { role, tools, type, 2 more }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `role: "developer"` + - `"in_progress"` - The role that provided the additional tools. Only `developer` is supported. + - `"searching"` - - `tools: array of BetaTool` + - `"completed"` - A list of additional tools made available at this item. + - `"incomplete"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `"failed"` - 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). + - `type: "file_search_call"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The type of the file search tool call. Always `file_search_call`. - 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). + - `agent: optional object { agent_name }` - - `beta_computer_tool: object { type }` + The agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: string` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The results of the file search tool call. - 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). + - `attributes: optional map[string or number or boolean]` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + 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. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `union_member_0: string` - - `code_interpreter: object { container, type, allowed_callers }` + - `union_member_1: number` - A tool that runs Python code to help generate a response to a prompt. + - `union_member_2: boolean` - - `programmatic_tool_calling: object { type }` + - `file_id: optional string` - - `image_generation: object { type, action, background, 9 more }` + The unique ID of the file. - A tool that generates images using the GPT image models. + - `filename: optional string` - - `local_shell: object { type }` + The name of the file. - A tool that allows the model to execute shell commands in a local environment. + - `score: optional number` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The relevance score of the file - a value between 0 and 1. - A tool that allows the model to execute shell commands. + - `text: optional string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The text that was retrieved from the file. - 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) + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `beta_namespace_tool: object { description, name, tools, type }` + 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. - Groups function/custom tools under a shared namespace. + - `id: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The unique ID of the computer call. - Hosted or BYOT tool search configuration for deferred tools. + - `call_id: string` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + An identifier used when responding to the tool call with output. - 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). + - `pending_safety_checks: array of object { id, code, message }` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The pending safety checks for the computer call. - Allows the assistant to create, delete, or update files using unified diffs. + - `id: string` - - `type: "additional_tools"` + The ID of the pending safety check. - The item type. Always `additional_tools`. + - `code: optional string` - - `id: optional string` + The type of the pending safety check. - The unique ID of this additional tools item. + - `message: optional string` - - `agent: optional object { agent_name }` + Details about the pending safety check. - The agent that produced this item. + - `status: "in_progress" or "completed" or "incomplete"` - - `agent_name: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The canonical name of the agent that produced this item. + - `"in_progress"` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `"completed"` - 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). + - `"incomplete"` - - `id: string` + - `type: "computer_call"` - The unique identifier of the reasoning content. + The type of the computer call. Always `computer_call`. - - `summary: array of object { text, type }` + - `"computer_call"` - Reasoning summary content. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `text: string` + A click action. - A summary of the reasoning output from the model so far. + - `click: object { button, type, x, 2 more }` - - `type: "summary_text"` + A click action. - The type of the object. Always `summary_text`. + - `button: "left" or "right" or "wheel" or 2 more` - - `type: "reasoning"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The type of the object. Always `reasoning`. + - `"left"` - - `agent: optional object { agent_name }` + - `"right"` - The agent that produced this item. + - `"wheel"` - - `agent_name: string` + - `"back"` - The canonical name of the agent that produced this item. + - `"forward"` - - `content: optional array of object { text, type }` + - `type: "click"` - Reasoning text content. + Specifies the event type. For a click action, this property is always `click`. - - `text: string` + - `x: number` - The reasoning text from the model. + The x-coordinate where the click occurred. - - `type: "reasoning_text"` + - `y: number` - The type of the reasoning text. Always `reasoning_text`. + The y-coordinate where the click occurred. - - `encrypted_content: optional string` + - `keys: optional array of string` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The keys being held while clicking. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `double_click: object { keys, type, x, y }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A double click action. - - `"in_progress"` + - `keys: array of string` - - `"completed"` + The keys being held while double-clicking. - - `"incomplete"` + - `type: "double_click"` - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `x: number` - - `encrypted_content: string` + The x-coordinate where the double click occurred. - The encrypted content of the compaction summary. + - `y: number` - - `type: "compaction"` + The y-coordinate where the double click occurred. - The type of the item. Always `compaction`. + - `drag: object { path, type, keys }` - - `id: optional string` + A drag action. - The ID of the compaction item. + - `path: array of object { x, y }` - - `agent: optional object { agent_name }` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The agent that produced this item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `agent_name: string` + - `x: number` - The canonical name of the agent that produced this item. + The x-coordinate. - - `image_generation_call: object { id, result, status, 2 more }` + - `y: number` - An image generation request made by the model. + The y-coordinate. - - `id: string` + - `type: "drag"` - The unique ID of the image generation call. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `result: string` + - `keys: optional array of string` - The generated image encoded in base64. + The keys being held while dragging the mouse. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `keypress: object { keys, type }` - The status of the image generation call. + A collection of keypresses the model would like to perform. - - `"in_progress"` + - `keys: array of string` - - `"completed"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"generating"` + - `type: "keypress"` - - `"failed"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: "image_generation_call"` + - `move: object { type, x, y, keys }` - The type of the image generation call. Always `image_generation_call`. + A mouse move action. - - `agent: optional object { agent_name }` + - `type: "move"` - The agent that produced this item. + Specifies the event type. For a move action, this property is always set to `move`. - - `agent_name: string` + - `x: number` - The canonical name of the agent that produced this item. + The x-coordinate to move to. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `y: number` - A tool call to run code. + The y-coordinate to move to. - - `id: string` + - `keys: optional array of string` - The unique ID of the code interpreter tool call. + The keys being held while moving the mouse. - - `code: string` + - `screenshot: object { type }` - The code to run, or null if not available. + A screenshot action. - - `container_id: string` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The ID of the container used to run the code. + A scroll action. - - `outputs: array of object { logs, type } or object { type, url }` + - `scroll_x: number` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The horizontal scroll distance. - - `logs: object { logs, type }` + - `scroll_y: number` - The logs output from the code interpreter. + The vertical scroll distance. - - `logs: string` + - `type: "scroll"` - The logs output from the code interpreter. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `type: "logs"` + - `x: number` - The type of the output. Always `logs`. + The x-coordinate where the scroll occurred. - - `image: object { type, url }` + - `y: number` - The image output from the code interpreter. + The y-coordinate where the scroll occurred. - - `type: "image"` + - `keys: optional array of string` - The type of the output. Always `image`. + The keys being held while scrolling. - - `url: string` + - `type: object { text, type }` - The URL of the image output from the code interpreter. + An action to type in text. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `text: string` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The text to type. - - `"in_progress"` + - `type: "type"` - - `"completed"` + Specifies the event type. For a type action, this property is always set to `type`. - - `"incomplete"` + - `wait: object { type }` - - `"interpreting"` + A wait action. - - `"failed"` + - `actions: optional array of BetaComputerAction` - - `type: "code_interpreter_call"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `click: object { button, type, x, 2 more }` - - `agent: optional object { agent_name }` + A click action. - The agent that produced this item. + - `double_click: object { keys, type, x, y }` - - `agent_name: string` + A double click action. - The canonical name of the agent that produced this item. + - `drag: object { path, type, keys }` - - `local_shell_call: object { id, action, call_id, 3 more }` + A drag action. - A tool call to run a command on the local shell. + - `keypress: object { keys, type }` - - `id: string` + A collection of keypresses the model would like to perform. - The unique ID of the local shell call. + - `move: object { type, x, y, keys }` - - `action: object { command, env, type, 3 more }` + A mouse move action. - Execute a shell command on the server. + - `screenshot: object { type }` - - `command: array of string` + A screenshot action. - The command to run. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `env: map[string]` + A scroll action. - Environment variables to set for the command. + - `type: object { text, type }` - - `type: "exec"` + An action to type in text. - The type of the local shell action. Always `exec`. + - `wait: object { type }` - - `timeout_ms: optional number` + A wait action. - Optional timeout in milliseconds for the command. + - `agent: optional object { agent_name }` - - `user: optional string` + The agent that produced this item. - Optional user to run the command as. + - `agent_name: string` - - `working_directory: optional string` + The canonical name of the agent that produced this item. - Optional working directory to run the command in. + - `computer_call_output: object { call_id, output, type, 4 more }` + + The output of a computer tool call. - `call_id: string` - The unique ID of the local shell tool call generated by the model. + The ID of the computer tool call that produced the output. - - `status: "in_progress" or "completed" or "incomplete"` + - `output: object { type, file_id, image_url }` - The status of the local shell call. + A computer screenshot image used with the computer use tool. - - `"in_progress"` + - `type: "computer_screenshot"` - - `"completed"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"incomplete"` + - `file_id: optional string` - - `type: "local_shell_call"` + The identifier of an uploaded file that contains the screenshot. - The type of the local shell call. Always `local_shell_call`. + - `image_url: optional string` - - `agent: optional object { agent_name }` + The URL of the screenshot image. - The agent that produced this item. + - `type: "computer_call_output"` - - `agent_name: string` + The type of the computer tool call output. Always `computer_call_output`. - The canonical name of the agent that produced this item. + - `id: optional string` - - `local_shell_call_output: object { id, output, type, 2 more }` + The ID of the computer tool call output. - The output of a local shell tool call. + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. - `id: string` - The unique ID of the local shell tool call generated by the model. + The ID of the pending safety check. - - `output: string` + - `code: optional string` - A JSON string of the output of the local shell tool call. + The type of the pending safety check. - - `type: "local_shell_call_output"` + - `message: optional string` - The type of the local shell tool call output. Always `local_shell_call_output`. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -59700,7 +70287,7 @@ openai beta:responses compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -59708,127 +70295,124 @@ openai beta:responses compact \ - `"incomplete"` - - `shell_call: object { action, call_id, type, 5 more }` - - A tool representing a request to execute one or more shell commands. - - - `action: object { commands, max_output_length, timeout_ms }` - - The shell commands and limits that describe how to run the tool call. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `commands: array of string` + 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. - Ordered shell commands for the execution environment to run. + - `id: string` - - `max_output_length: optional number` + The unique ID of the web search tool call. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `timeout_ms: optional number` + 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). - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `search: object { type, queries, query, sources }` - - `call_id: string` + Action type "search" - Performs a web search query. - The unique ID of the shell tool call generated by the model. + - `type: "search"` - - `type: "shell_call"` + The action type. - The type of the item. Always `shell_call`. + - `queries: optional array of string` - - `id: optional string` + The search queries. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `query: optional string` - - `agent: optional object { agent_name }` + The search query. - The agent that produced this item. + - `sources: optional array of object { type, url }` - - `agent_name: string` + The sources used in the search. - The canonical name of the agent that produced this item. + - `type: "url"` - - `caller: optional object { type } or object { caller_id, type }` + The type of source. Always `url`. - The execution context that produced this tool call. + - `url: string` - - `direct: object { type }` + The URL of the source. - - `program: object { caller_id, type }` + - `open_page: object { type, url }` - - `caller_id: string` + Action type "open_page" - Opens a specific URL from search results. - The call ID of the program item that produced this tool call. + - `type: "open_page"` - - `type: "program"` + The action type. - The caller type. Always `program`. + - `url: optional string` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + The URL opened by the model. - The environment to execute the shell commands in. + - `find_in_page: object { pattern, type, url }` - - `beta_local_environment: object { type, skills }` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `beta_container_reference: object { container_id, type }` + - `pattern: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The pattern or text to search for within the page. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `type: "find_in_page"` - - `"in_progress"` + The action type. - - `"completed"` + - `url: string` - - `"incomplete"` + The URL of the page searched for the pattern. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The streamed output items emitted by a shell tool call. + The status of the web search tool call. - - `call_id: string` + - `"in_progress"` - The unique ID of the shell tool call generated by the model. + - `"searching"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"completed"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"failed"` - - `outcome: object { type } or object { exit_code, type }` + - `type: "web_search_call"` - The exit or timeout outcome associated with this shell call. + The type of the web search tool call. Always `web_search_call`. - - `timeout: object { type }` + - `agent: optional object { agent_name }` - Indicates that the shell call exceeded its configured time limit. + The agent that produced this item. - - `exit: object { exit_code, type }` + - `agent_name: string` - Indicates that the shell commands finished and returned an exit code. + The canonical name of the agent that produced this item. - - `exit_code: number` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The exit code returned by the shell process. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `type: "exit"` + - `arguments: string` - The outcome type. Always `exit`. + A JSON string of the arguments to pass to the function. - - `stderr: string` + - `call_id: string` - Captured stderr output for the shell call. + The unique ID of the function tool call generated by the model. - - `stdout: string` + - `name: string` - Captured stdout output for the shell call. + The name of the function to run. - - `type: "shell_call_output"` + - `type: "function_call"` - The type of the item. Always `shell_call_output`. + The type of the function tool call. Always `function_call`. - `id: optional string` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -59852,15 +70436,14 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `max_output_length: optional number` + - `namespace: optional string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The namespace of the function to run. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -59868,125 +70451,131 @@ openai beta:responses compact \ - `"incomplete"` - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `function_call_output: object { call_id, output, type, 4 more }` - A tool call representing a request to create, delete, or update files using diff patches. + The output of a function tool call. - `call_id: string` - The unique ID of the apply patch tool call generated by the model. + The unique ID of the function tool call generated by the model. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `output: string or BetaResponseFunctionCallOutputItemList` - The specific create, delete, or update instruction for the apply_patch tool call. + Text, image, or file output of the function tool call. - - `create_file: object { diff, path, type }` + - `union_member_0: string` - Instruction for creating a new file via the apply_patch tool. + A JSON string of the output of the function tool call. - - `diff: string` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - Unified diff content to apply when creating the file. + An array of content outputs (text, image, file) for the function tool call. - - `path: string` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - Path of the file to create relative to the workspace root. + A text input to the model. - - `type: "create_file"` + - `text: string` - The operation type. Always `create_file`. + The text input to the model. - - `delete_file: object { path, type }` + - `type: "input_text"` - Instruction for deleting an existing file via the apply_patch tool. + The type of the input item. Always `input_text`. - - `path: string` + - `prompt_cache_breakpoint: optional object { mode }` - Path of the file to delete relative to the workspace root. + 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. - - `type: "delete_file"` + - `mode: "explicit"` - The operation type. Always `delete_file`. + The breakpoint mode. Always `explicit`. - - `update_file: object { diff, path, type }` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - Instruction for updating an existing file via the apply_patch tool. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `diff: string` + - `type: "input_image"` - Unified diff content to apply to the existing file. + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` - - `path: string` + - `"high"` - Path of the file to update relative to the workspace root. + - `"auto"` - - `type: "update_file"` + - `"original"` - The operation type. Always `update_file`. + - `file_id: optional string` - - `status: "in_progress" or "completed"` + The ID of the file to be sent to the model. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `image_url: optional string` - - `"in_progress"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"completed"` + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "apply_patch_call"` + 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. - The type of the item. Always `apply_patch_call`. + - `mode: "explicit"` - - `id: optional string` + The breakpoint mode. Always `explicit`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `agent: optional object { agent_name }` + A file input to the model. - The agent that produced this item. + - `type: "input_file"` - - `agent_name: string` + The type of the input item. Always `input_file`. - The canonical name of the agent that produced this item. + - `detail: optional "auto" or "low" or "high"` - - `caller: optional object { type } or object { caller_id, type }` + 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`. - The execution context that produced this tool call. + - `"auto"` - - `direct: object { type }` + - `"low"` - - `program: object { caller_id, type }` + - `"high"` - - `caller_id: string` + - `file_data: optional string` - The call ID of the program item that produced this tool call. + The base64-encoded data of the file to be sent to the model. - - `type: "program"` + - `file_id: optional string` - The caller type. Always `program`. + The ID of the file to be sent to the model. - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `file_url: optional string` - The streamed output emitted by an apply patch tool call. + The URL of the file to be sent to the model. - - `call_id: string` + - `filename: optional string` - The unique ID of the apply patch tool call generated by the model. + The name of the file to be sent to the model. - - `status: "completed" or "failed"` + - `prompt_cache_breakpoint: optional object { mode }` - The status of the apply patch tool call output. One of `completed` or `failed`. + 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. - - `"completed"` + - `mode: "explicit"` - - `"failed"` + The breakpoint mode. Always `explicit`. - - `type: "apply_patch_call_output"` + - `type: "function_call_output"` - The type of the item. Always `apply_patch_call_output`. + The type of the function tool call output. Always `function_call_output`. - `id: optional string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -60012,109 +70601,91 @@ openai beta:responses compact \ The caller type. Always `program`. - - `output: optional string` - - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - A list of tools available on an MCP server. - - - `id: string` - - The unique ID of the list. - - - `server_label: string` - - The label of the MCP server. - - - `tools: array of object { input_schema, name, annotations, description }` - - The tools available on the server. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `input_schema: unknown` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The JSON schema describing the tool's input. + - `"in_progress"` - - `name: string` + - `"completed"` - The name of the tool. + - `"incomplete"` - - `annotations: optional unknown` + - `agent_message: object { author, content, recipient, 3 more }` - Additional annotations about the tool. + A message routed between agents. - - `description: optional string` + - `author: string` - The description of the tool. + The sending agent identity. - - `type: "mcp_list_tools"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - The type of the item. Always `mcp_list_tools`. + Plaintext, image, or encrypted content sent between agents. - - `agent: optional object { agent_name }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - The agent that produced this item. + A text input to the model. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + The text input to the model. - - `error: optional string` + - `type: "input_text"` - Error message if the server could not list tools. + The type of the input item. Always `input_text`. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` - A request for human approval of a tool invocation. + 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. - - `id: string` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The unique ID of the approval request. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `arguments: string` + - `type: "input_image"` - A JSON string of arguments for the tool. + The type of the input item. Always `input_image`. - - `name: string` + - `detail: optional "low" or "high" or "auto" or "original"` - The name of the tool to run. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `server_label: string` + - `file_id: optional string` - The label of the MCP server making the request. + The ID of the file to be sent to the model. - - `type: "mcp_approval_request"` + - `image_url: optional string` - The type of the item. Always `mcp_approval_request`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `agent: optional object { agent_name }` + - `prompt_cache_breakpoint: optional object { mode }` - The agent that produced this item. + 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. - - `agent_name: string` + - `encrypted_content: object { encrypted_content, type }` - The canonical name of the agent that produced this item. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + - `encrypted_content: string` - A response to an MCP approval request. + Opaque encrypted content. - - `approval_request_id: string` + - `type: "encrypted_content"` - The ID of the approval request being answered. + The type of the input item. Always `encrypted_content`. - - `approve: boolean` + - `recipient: string` - Whether the request was approved. + The destination agent identity. - - `type: "mcp_approval_response"` + - `type: "agent_message"` - The type of the item. Always `mcp_approval_response`. + The item type. Always `agent_message`. - `id: optional string` - The unique ID of the approval response + The unique ID of this agent message item. - `agent: optional object { agent_name }` @@ -60124,33 +70695,39 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `reason: optional string` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - Optional reason for the decision. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `mcp_call: object { id, arguments, name, 7 more }` + The multi-agent action that was executed. - An invocation of a tool on an MCP server. + - `"spawn_agent"` - - `id: string` + - `"interrupt_agent"` - The unique ID of the tool call. + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` - `arguments: string` - A JSON string of the arguments passed to the tool. + The action arguments as a JSON string. - - `name: string` + - `call_id: string` - The name of the tool that was run. + The unique ID linking this call to its output. - - `server_label: string` + - `type: "multi_agent_call"` - The label of the MCP server running the tool. + The item type. Always `multi_agent_call`. - - `type: "mcp_call"` + - `id: optional string` - The type of the item. Always `mcp_call`. + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -60160,133 +70737,117 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. - - - `output: optional string` - - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"in_progress"` + The multi-agent action that produced this result. - - `"completed"` + - `"spawn_agent"` - - `"incomplete"` + - `"interrupt_agent"` - - `"calling"` + - `"list_agents"` - - `"failed"` + - `"send_message"` - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `"followup_task"` - The output of a custom tool call from your code, being sent back to the model. + - `"wait_agent"` - `call_id: string` - The call ID, used to map this custom tool call output to a custom tool call. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The unique ID of the multi-agent call. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `output: array of object { text, type, annotations }` - - `string output: string` + Text output returned by the multi-agent action. - A string of the output of the custom tool call. + - `text: string` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The text content. - Text, image, or file output of the custom tool call. + - `type: "output_text"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The content type. Always `output_text`. - A text input to the model. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `text: string` + Citations associated with the text content. - The text input to the model. + - `union_member_0: array of object { file_id, filename, index, type }` - - `type: "input_text"` + - `file_id: string` - The type of the input item. Always `input_text`. + The ID of the file. - - `prompt_cache_breakpoint: optional object { mode }` + - `filename: string` - 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. + The filename of the file cited. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `index: number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The index of the file in the list of files. - - `detail: "low" or "high" or "auto" or "original"` + - `type: "file_citation"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The citation type. Always `file_citation`. - - `type: "input_image"` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - The type of the input item. Always `input_image`. + - `end_index: number` - - `file_id: optional string` + The index of the last character of the citation in the message. - The ID of the file to be sent to the model. + - `start_index: number` - - `image_url: optional string` + The index of the first character of the citation in the message. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `title: string` - - `prompt_cache_breakpoint: optional object { mode }` + The title of the cited resource. - 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. + - `type: "url_citation"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The citation type. Always `url_citation`. - A file input to the model. + - `url: string` - - `type: "input_file"` + The URL of the cited resource. - The type of the input item. Always `input_file`. + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `detail: optional "auto" or "low" or "high"` + - `container_id: string` - 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`. + The ID of the container. - - `file_data: optional string` + - `end_index: number` - The content of the file to be sent to the model. + The index of the last character of the citation in the message. - - `file_id: optional string` + - `file_id: string` - The ID of the file to be sent to the model. + The ID of the container file. - - `file_url: optional string` + - `filename: string` - The URL of the file to be sent to the model. + The filename of the container file cited. - - `filename: optional string` + - `start_index: number` - The name of the file to be sent to the model. + The index of the first character of the citation in the message. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "container_file_citation"` - 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. + The citation type. Always `container_file_citation`. - - `type: "custom_tool_call_output"` + - `type: "multi_agent_call_output"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The item type. Always `multi_agent_call_output`. - `id: optional string` - The unique ID of the custom tool call output in the OpenAI platform. + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -60296,1082 +70857,1101 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. + - `tool_search_call: object { arguments, type, id, 4 more }` - - `direct: object { type }` + - `arguments: unknown` - - `program: object { caller_id, type }` + The arguments supplied to the tool search call. - - `caller_id: string` + - `type: "tool_search_call"` - The call ID of the program item that produced this tool call. + The item type. Always `tool_search_call`. - - `type: "program"` + - `id: optional string` - The caller type. Always `program`. + The unique ID of this tool search call. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `agent: optional object { agent_name }` - A call to a custom tool created by the model. + The agent that produced this item. - - `call_id: string` + - `agent_name: string` - An identifier used to map this custom tool call to a tool call output. + The canonical name of the agent that produced this item. - - `input: string` + - `call_id: optional string` - The input for the custom tool call generated by the model. + The unique ID of the tool search call generated by the model. - - `name: string` + - `execution: optional "server" or "client"` - The name of the custom tool being called. + Whether tool search was executed by the server or by the client. - - `type: "custom_tool_call"` + - `"server"` - The type of the custom tool call. Always `custom_tool_call`. + - `"client"` - - `id: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The unique ID of the custom tool call in the OpenAI platform. + The status of the tool search call. - - `agent: optional object { agent_name }` + - `"in_progress"` - The agent that produced this item. + - `"completed"` - - `agent_name: string` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `caller: optional object { type } or object { caller_id, type }` + - `tools: array of BetaTool` - The execution context that produced this tool call. + The loaded tool definitions returned by the tool search output. - - `direct: object { type }` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `program: object { caller_id, type }` + 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). - - `caller_id: string` + - `name: string` - The call ID of the program item that produced this tool call. + The name of the function to call. - - `type: "program"` + - `parameters: map[unknown]` - - `namespace: optional string` + A JSON schema object describing the parameters of the function. - The namespace of the custom tool being called. + - `strict: boolean` - - `compaction_trigger: object { type, agent }` + Whether strict parameter validation is enforced for this function tool. - Compacts the current context. Must be the final input item. + - `type: "function"` - - `type: "compaction_trigger"` + The type of the function tool. Always `function`. - The type of the item. Always `compaction_trigger`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `defer_loading: optional boolean` - - `item_reference: object { id, agent, type }` + Whether this function is deferred and loaded via tool search. - An internal identifier for an item to reference. + - `description: optional string` - - `id: string` + A description of the function. Used by the model to determine whether or not to call the function. - The ID of the item to reference. + - `output_schema: optional map[unknown]` - - `agent: optional object { agent_name }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The agent that produced this item. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `type: "file_search"` - - `type: optional "item_reference"` + The type of the file search tool. Always `file_search`. - The type of item to reference. Always `item_reference`. + - `vector_store_ids: array of string` - - `"item_reference"` + The IDs of the vector stores to search. - - `program: object { id, call_id, code, 3 more }` + - `filters: optional object { key, type, value } or object { filters, type }` - - `id: string` + A filter to apply. - The unique ID of this program item. + - `Comparison Filter: object { key, type, value }` - - `call_id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The stable call ID of the program item. + - `key: string` - - `code: string` + The key to compare against the value. - The JavaScript source executed by programmatic tool calling. + - `type: "eq" or "ne" or "gt" or 5 more` - - `fingerprint: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Opaque program replay fingerprint that must be round-tripped. + - `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 - - `type: "program"` + - `"eq"` - The item type. Always `program`. + - `"ne"` - - `agent: optional object { agent_name }` + - `"gt"` - The agent that produced this item. + - `"gte"` - - `agent_name: string` + - `"lt"` - The canonical name of the agent that produced this item. + - `"lte"` - - `program_output: object { id, call_id, result, 3 more }` + - `"in"` - - `id: string` + - `"nin"` - The unique ID of this program output item. + - `value: string or number or boolean or array of string or number` - - `call_id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The call ID of the program item. + - `union_member_0: string` - - `result: string` + - `union_member_1: number` - The result produced by the program item. + - `union_member_2: boolean` - - `status: "completed" or "incomplete"` + - `union_member_3: array of string or number` - The terminal status of the program output. + - `union_member_0: string` - - `"completed"` + - `union_member_1: number` - - `"incomplete"` + - `Compound Filter: object { filters, type }` - - `type: "program_output"` + Combine multiple filters using `and` or `or`. - The item type. Always `program_output`. + - `filters: array of object { key, type, value } or unknown` - - `agent: optional object { agent_name }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The agent that produced this item. + - `Comparison Filter: object { key, type, value }` - - `agent_name: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The canonical name of the agent that produced this item. + - `key: string` - - `metadata: map[string]` + The key to compare against the value. - 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. + - `type: "eq" or "ne" or "gt" or 5 more` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `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 - Model ID used to generate the response, like `gpt-4o` 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. + - `"eq"` - - `"gpt-5.6-sol"` + - `"ne"` - - `"gpt-5.6-terra"` + - `"gt"` - - `"gpt-5.6-luna"` + - `"gte"` - - `"gpt-5.4"` + - `"lt"` - - `"gpt-5.4-mini"` + - `"lte"` - - `"gpt-5.4-nano"` + - `"in"` - - `"gpt-5.4-mini-2026-03-17"` + - `"nin"` - - `"gpt-5.4-nano-2026-03-17"` + - `value: string or number or boolean or array of string or number` - - `"gpt-5.3-chat-latest"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-5.2"` + - `union_member_0: string` - - `"gpt-5.2-2025-12-11"` + - `union_member_1: number` - - `"gpt-5.2-chat-latest"` + - `union_member_2: boolean` - - `"gpt-5.2-pro"` + - `union_member_3: array of string or number` - - `"gpt-5.2-pro-2025-12-11"` + - `union_member_0: string` - - `"gpt-5.1"` + - `union_member_1: number` - - `"gpt-5.1-2025-11-13"` + - `union_member_1: unknown` - - `"gpt-5.1-codex"` + - `type: "and" or "or"` - - `"gpt-5.1-mini"` + Type of operation: `and` or `or`. - - `"gpt-5.1-chat-latest"` + - `"and"` - - `"gpt-5"` + - `"or"` - - `"gpt-5-mini"` + - `max_num_results: optional number` - - `"gpt-5-nano"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-5-2025-08-07"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"gpt-5-mini-2025-08-07"` + Ranking options for search. - - `"gpt-5-nano-2025-08-07"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"gpt-5-chat-latest"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"gpt-4.1"` + - `embedding_weight: number` - - `"gpt-4.1-mini"` + The weight of the embedding in the reciprocal ranking fusion. - - `"gpt-4.1-nano"` + - `text_weight: number` - - `"gpt-4.1-2025-04-14"` + The weight of the text in the reciprocal ranking fusion. - - `"gpt-4.1-mini-2025-04-14"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"gpt-4.1-nano-2025-04-14"` + The ranker to use for the file search. - - `"o4-mini"` + - `"auto"` - - `"o4-mini-2025-04-16"` + - `"default-2024-11-15"` - - `"o3"` + - `score_threshold: optional number` - - `"o3-2025-04-16"` + 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. - - `"o3-mini"` + - `beta_computer_tool: object { type }` - - `"o3-mini-2025-01-31"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"o1"` + - `type: "computer"` - - `"o1-2024-12-17"` + The type of the computer tool. Always `computer`. - - `"o1-preview"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `"o1-preview-2024-09-12"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"o1-mini"` + - `display_height: number` - - `"o1-mini-2024-09-12"` + The height of the computer display. - - `"gpt-4o"` + - `display_width: number` - - `"gpt-4o-2024-11-20"` + The width of the computer display. - - `"gpt-4o-2024-08-06"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"gpt-4o-2024-05-13"` + The type of computer environment to control. - - `"gpt-4o-audio-preview"` + - `"windows"` - - `"gpt-4o-audio-preview-2024-10-01"` + - `"mac"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `"linux"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `"ubuntu"` - - `"gpt-4o-mini-audio-preview"` + - `"browser"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `type: "computer_use_preview"` - - `"gpt-4o-search-preview"` + The type of the computer use tool. Always `computer_use_preview`. - - `"gpt-4o-mini-search-preview"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `"gpt-4o-search-preview-2025-03-11"` + 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). - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `type: "web_search" or "web_search_2025_08_26"` - - `"chatgpt-4o-latest"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"codex-mini-latest"` + - `"web_search"` - - `"gpt-4o-mini"` + - `"web_search_2025_08_26"` - - `"gpt-4o-mini-2024-07-18"` + - `filters: optional object { allowed_domains }` - - `"gpt-4-turbo"` + Filters for the search. - - `"gpt-4-turbo-2024-04-09"` + - `allowed_domains: optional array of string` - - `"gpt-4-0125-preview"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"gpt-4-turbo-preview"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"gpt-4-1106-preview"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"gpt-4-vision-preview"` + 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. - - `"gpt-4"` + - `"low"` - - `"gpt-4-0314"` + - `"medium"` - - `"gpt-4-0613"` + - `"high"` - - `"gpt-4-32k"` + - `user_location: optional object { city, country, region, 2 more }` - - `"gpt-4-32k-0314"` + The approximate location of the user. - - `"gpt-4-32k-0613"` + - `city: optional string` - - `"gpt-3.5-turbo"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-3.5-turbo-16k"` + - `country: optional string` - - `"gpt-3.5-turbo-0301"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"gpt-3.5-turbo-0613"` + - `region: optional string` - - `"gpt-3.5-turbo-1106"` + Free text input for the region of the user, e.g. `California`. - - `"gpt-3.5-turbo-0125"` + - `timezone: optional string` - - `"gpt-3.5-turbo-16k-0613"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"o1-pro"` + - `type: optional "approximate"` - - `"o1-pro-2025-03-19"` + The type of location approximation. Always `approximate`. - - `"o3-pro"` + - `"approximate"` - - `"o3-pro-2025-06-10"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `"o3-deep-research"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"o3-deep-research-2025-06-26"` + - `server_label: string` - - `"o4-mini-deep-research"` + A label for this MCP server, used to identify it in tool calls. - - `"o4-mini-deep-research-2025-06-26"` + - `type: "mcp"` - - `"computer-use-preview"` + The type of the MCP tool. Always `mcp`. - - `"computer-use-preview-2025-03-11"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5-codex"` + The tool invocation context(s). - - `"gpt-5-pro"` + - `"direct"` - - `"gpt-5-pro-2025-10-06"` + - `"programmatic"` - - `"gpt-5.1-codex-max"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `object: "response"` + List of allowed tool names or a filter object. - The object type of this resource - always set to `response`. + - `MCP allowed tools: array of string` - - `output: array of BetaResponseOutputItem` + A string array of allowed tool names - An array of content items generated by the model. + - `MCP tool filter: object { read_only, tool_names }` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + A filter object to specify which tools are allowed. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `read_only: optional boolean` - An output message from the model. + 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. - - `id: string` + - `tool_names: optional array of string` - The unique ID of the output message. + List of allowed tool names. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `authorization: optional string` - The content of the output message. + 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. - - `role: "assistant"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The role of the output message. Always `assistant`. + 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). - - `status: "in_progress" or "completed" or "incomplete"` + Currently supported `connector_id` values are: - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - 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` - - `type: "message"` + - `"connector_dropbox"` - The type of the output message. Always `message`. + - `"connector_gmail"` - - `agent: optional object { agent_name }` + - `"connector_googlecalendar"` - The agent that produced this item. + - `"connector_googledrive"` - - `phase: optional "commentary"` + - `"connector_microsoftteams"` - 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. + - `"connector_outlookcalendar"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `"connector_outlookemail"` - 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. + - `"connector_sharepoint"` - - `id: string` + - `defer_loading: optional boolean` - The unique ID of the file search tool call. + Whether this MCP tool is deferred and discovered via tool search. - - `queries: array of string` + - `headers: optional map[string]` - The queries used to search for files. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `require_approval: optional object { always, never } or "always" or "never"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Specify which of the MCP server's tools require approval. - - `type: "file_search_call"` + - `MCP tool approval filter: object { always, never }` - The type of the file search tool call. Always `file_search_call`. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `agent: optional object { agent_name }` + - `always: optional object { read_only, tool_names }` - The agent that produced this item. + A filter object to specify which tools are allowed. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `read_only: optional boolean` - The results of the file search tool call. + 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. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `tool_names: optional array of string` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + List of allowed tool names. - - `arguments: string` + - `never: optional object { read_only, tool_names }` - A JSON string of the arguments to pass to the function. + A filter object to specify which tools are allowed. - - `call_id: string` + - `read_only: optional boolean` - The unique ID of the function tool call generated by the model. + 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. - - `name: string` + - `tool_names: optional array of string` - The name of the function to run. + List of allowed tool names. - - `type: "function_call"` + - `MCP tool approval setting: "always" or "never"` - The type of the function tool call. Always `function_call`. + 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. - - `id: optional string` + - `"always"` - The unique ID of the function tool call. + - `"never"` - - `agent: optional object { agent_name }` + - `server_description: optional string` - The agent that produced this item. + Optional description of the MCP server, used to provide more context. - - `caller: optional object { type } or object { caller_id, type }` + - `server_url: optional string` - The execution context that produced this tool call. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `namespace: optional string` + - `tunnel_id: optional string` - The namespace of the function to run. + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `code_interpreter: object { container, type, allowed_callers }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool that runs Python code to help generate a response to a prompt. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `id: string` + 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. - The unique ID of the function call tool output. + - `union_member_0: string` - - `call_id: string` + The container ID. - The unique ID of the function tool call generated by the model. + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `type: "auto"` - - `string output: string` + Always `auto`. - A string of the output of the function call. + - `file_ids: optional array of string` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + An optional list of uploaded files to make available to your code. - Text, image, or file output of the function call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The memory limit for the code interpreter container. - A text input to the model. + - `"1g"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"4g"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"16g"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"64g"` - A file input to the model. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `status: "in_progress" or "completed" or "incomplete"` + Network access policy for the container. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_container_network_policy_disabled: object { type }` - - `"in_progress"` + - `type: "disabled"` - - `"completed"` + Disable outbound network access. Always `disabled`. - - `"incomplete"` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `type: "function_call_output"` + - `allowed_domains: array of string` - The type of the function tool call output. Always `function_call_output`. + A list of allowed domains when type is `allowlist`. - - `agent: optional object { agent_name }` + - `type: "allowlist"` - The agent that produced this item. + Allow outbound network access only to specified domains. Always `allowlist`. - - `agent_name: string` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The canonical name of the agent that produced this item. + Optional domain-scoped secrets for allowlisted domains. - - `caller: optional object { type } or object { caller_id, type }` + - `domain: string` - The execution context that produced this tool call. + The domain associated with the secret. - - `direct: object { type }` + - `name: string` - - `program: object { caller_id, type }` + The name of the secret to inject for the domain. - - `caller_id: string` + - `value: string` - The call ID of the program item that produced this tool call. + The secret value to inject for the domain. - - `type: "program"` + - `type: "code_interpreter"` - The caller type. Always `program`. + The type of the code interpreter tool. Always `code_interpreter`. - - `created_by: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The identifier of the actor that created the item. + The tool invocation context(s). - - `agent_message: object { id, author, content, 3 more }` + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the agent message. + - `programmatic_tool_calling: object { type }` - - `author: string` + - `image_generation: object { type, action, background, 9 more }` - The sending agent identity. + A tool that generates images using the GPT image models. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `type: "image_generation"` - Encrypted content sent between agents. + The type of the image generation tool. Always `image_generation`. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `action: optional "generate" or "edit" or "auto"` - A text input to the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"generate"` - A text output from the model. + - `"edit"` - - `text: object { text, type }` + - `"auto"` - A text content. + - `background: optional "transparent" or "opaque" or "auto"` - - `text: string` + 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. - - `type: "text"` + `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. - - `summary_text: object { text, type }` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - A summary text from the model. + - `"transparent"` - - `text: string` + - `"opaque"` - A summary of the reasoning output from the model so far. + - `"auto"` - - `type: "summary_text"` + - `input_fidelity: optional "high" or "low"` - The type of the object. Always `summary_text`. + 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`. - - `reasoning_text: object { text, type }` + - `"high"` - Reasoning text from the model. + - `"low"` - - `text: string` + - `input_image_mask: optional object { file_id, image_url }` - The reasoning text from the model. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "reasoning_text"` + - `file_id: optional string` - The type of the reasoning text. Always `reasoning_text`. + File ID for the mask image. - - `beta_response_output_refusal: object { refusal, type }` + - `image_url: optional string` - A refusal from the model. + Base64-encoded mask image. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The image generation model to use. Default: `gpt-image-1`. - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `"gpt-image-1"` - A screenshot of a computer. + - `"gpt-image-1-mini"` - - `detail: "low" or "high" or "auto" or "original"` + - `"gpt-image-2"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"gpt-image-2-2026-04-21"` - - `"low"` + - `"gpt-image-1.5"` - - `"high"` + - `"chatgpt-image-latest"` - - `"auto"` + - `moderation: optional "auto" or "low"` - - `"original"` + Moderation level for the generated image. Default: `auto`. - - `file_id: string` + - `"auto"` - The identifier of an uploaded file that contains the screenshot. + - `"low"` - - `image_url: string` + - `output_compression: optional number` - The URL of the screenshot image. + Compression level for the output image. Default: 100. - - `type: "computer_screenshot"` + - `output_format: optional "png" or "webp" or "jpeg"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"png"` - 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. + - `"webp"` - - `mode: "explicit"` + - `"jpeg"` - The breakpoint mode. Always `explicit`. + - `partial_images: optional number` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - A file input to the model. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `encrypted_content: object { encrypted_content, type }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"low"` - - `encrypted_content: string` + - `"medium"` - Opaque encrypted content. + - `"high"` - - `type: "encrypted_content"` + - `"auto"` - The type of the input item. Always `encrypted_content`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `recipient: string` + 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`. - The destination agent identity. + - `"1024x1024"` - - `type: "agent_message"` + - `"1024x1536"` - The type of the item. Always `agent_message`. + - `"1536x1024"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `local_shell: object { type }` - - `agent_name: string` + A tool that allows the model to execute shell commands in a local environment. - The canonical name of the agent that produced this item. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `multi_agent_call: object { id, action, arguments, 3 more }` + A tool that allows the model to execute shell commands. - - `id: string` + - `type: "shell"` - The unique ID of the multi-agent call item. + The type of the shell tool. Always `shell`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `allowed_callers: optional array of "direct" or "programmatic"` - The multi-agent action to execute. + The tool invocation context(s). - - `"spawn_agent"` + - `"direct"` - - `"interrupt_agent"` + - `"programmatic"` - - `"list_agents"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"send_message"` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `"followup_task"` + - `type: "container_auto"` - - `"wait_agent"` + Automatically creates a container for this request - - `arguments: string` + - `file_ids: optional array of string` - The JSON string of arguments generated for the action. + An optional list of uploaded files to make available to your code. - - `call_id: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The unique ID linking this call to its output. + The memory limit for the container. - - `type: "multi_agent_call"` + - `"1g"` - The type of the multi-agent call. Always `multi_agent_call`. + - `"4g"` - - `agent: optional object { agent_name }` + - `"16g"` - The agent that produced this item. + - `"64g"` - - `agent_name: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The canonical name of the agent that produced this item. + Network access policy for the container. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `beta_container_network_policy_disabled: object { type }` - - `id: string` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The unique ID of the multi-agent call output item. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + An optional list of skills referenced by id or inline data. - The multi-agent action that produced this result. + - `beta_skill_reference: object { skill_id, type, version }` - - `"spawn_agent"` + - `skill_id: string` - - `"interrupt_agent"` + The ID of the referenced skill. - - `"list_agents"` + - `type: "skill_reference"` - - `"send_message"` + References a skill created with the /v1/skills endpoint. - - `"followup_task"` + - `version: optional string` - - `"wait_agent"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `call_id: string` + - `beta_inline_skill: object { description, name, source, type }` - The unique ID of the multi-agent call. + - `description: string` - - `output: array of BetaResponseOutputText` + The description of the skill. - Text output returned by the multi-agent action. + - `name: string` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The name of the skill. - The annotations of the text output. + - `source: object { data, media_type, type }` - - `text: string` + Inline skill payload - The text output from the model. + - `data: string` - - `type: "output_text"` + Base64-encoded skill zip bundle. - The type of the output text. Always `output_text`. + - `media_type: "application/zip"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The media type of the inline skill payload. Must be `application/zip`. - - `type: "multi_agent_call_output"` + - `type: "base64"` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the inline skill source. Must be `base64`. - - `agent: optional object { agent_name }` + - `type: "inline"` - The agent that produced this item. + Defines an inline skill for this request. - - `agent_name: string` + - `beta_local_environment: object { type, skills }` - The canonical name of the agent that produced this item. + - `type: "local"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + Use a local computer environment. - 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. + - `skills: optional array of BetaLocalSkill` - - `id: string` + An optional list of skills. - The unique ID of the web search tool call. + - `description: string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The description of the skill. - 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). + - `name: string` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The name of the skill. - The status of the web search tool call. + - `path: string` - - `type: "web_search_call"` + The path to the directory containing the skill. - The type of the web search tool call. Always `web_search_call`. + - `beta_container_reference: object { container_id, type }` - - `agent: optional object { agent_name }` + - `container_id: string` - The agent that produced this item. + The ID of the referenced container. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `type: "container_reference"` - 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. + References a container created with the /v1/containers endpoint - - `id: string` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The unique ID of the computer call. + 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) - - `call_id: string` + - `name: string` - An identifier used when responding to the tool call with output. + The name of the custom tool, used to identify it in tool calls. - - `pending_safety_checks: array of object { id, code, message }` + - `type: "custom"` - The pending safety checks for the computer call. + The type of the custom tool. Always `custom`. - - `status: "in_progress" or "completed" or "incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The tool invocation context(s). - - `type: "computer_call"` + - `"direct"` - The type of the computer call. Always `computer_call`. + - `"programmatic"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `defer_loading: optional boolean` - A click action. + Whether this tool should be deferred and discovered via tool search. - - `actions: optional array of BetaComputerAction` + - `description: optional string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Optional description of the custom tool, used to provide more context. - - `agent: optional object { agent_name }` + - `format: optional object { type } or object { definition, syntax, type }` - The agent that produced this item. + The input format for the custom tool. Default is unconstrained text. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `text: object { type }` - - `id: string` + Unconstrained free-form text. - The unique ID of the computer call tool output. + - `grammar: object { definition, syntax, type }` - - `call_id: string` + A grammar defined by the user. - The ID of the computer tool call that produced the output. + - `definition: string` - - `output: object { type, file_id, image_url }` + The grammar definition. - A computer screenshot image used with the computer use tool. + - `syntax: "lark" or "regex"` - - `type: "computer_screenshot"` + The syntax of the grammar definition. One of `lark` or `regex`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"lark"` - - `file_id: optional string` + - `"regex"` - The identifier of an uploaded file that contains the screenshot. + - `type: "grammar"` - - `image_url: optional string` + Grammar format. Always `grammar`. - The URL of the screenshot image. + - `beta_namespace_tool: object { description, name, tools, type }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + Groups function/custom tools under a shared namespace. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `description: string` - - `"completed"` + A description of the namespace shown to the model. - - `"incomplete"` + - `name: string` - - `"failed"` + The namespace name used in tool calls (for example, `crm`). - - `"in_progress"` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `type: "computer_call_output"` + The function/custom tools available inside this namespace. - The type of the computer tool call output. Always `computer_call_output`. + - `function: object { name, type, allowed_callers, 5 more }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `name: string` - The safety checks reported by the API that have been acknowledged by the - developer. + - `type: "function"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ID of the pending safety check. + The tool invocation context(s). - - `code: optional string` + - `"direct"` - The type of the pending safety check. + - `"programmatic"` - - `message: optional string` + - `defer_loading: optional boolean` - Details about the pending safety check. + Whether this function should be deferred and discovered via tool search. - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + - `output_schema: optional map[unknown]` - - `agent_name: string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The canonical name of the agent that produced this item. + - `parameters: optional unknown` - - `created_by: optional string` + - `strict: optional boolean` - The identifier of the actor that created the item. + 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. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + 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) - - `id: string` + - `name: string` - The unique identifier of the reasoning content. + The name of the custom tool, used to identify it in tool calls. - - `summary: array of object { text, type }` + - `type: "custom"` - Reasoning summary content. + The type of the custom tool. Always `custom`. - - `type: "reasoning"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the object. Always `reasoning`. + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `content: optional array of object { text, type }` + - `description: optional string` - Reasoning text content. + Optional description of the custom tool, used to provide more context. - - `encrypted_content: optional string` + - `format: optional object { type } or object { definition, syntax, type }` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The input format for the custom tool. Default is unconstrained text. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "namespace"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the tool. Always `namespace`. - - `program: object { id, call_id, code, 3 more }` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `id: string` + Hosted or BYOT tool search configuration for deferred tools. - The unique ID of the program item. + - `type: "tool_search"` - - `call_id: string` + The type of the tool. Always `tool_search`. - The stable call ID of the program item. + - `description: optional string` - - `code: string` + Description shown to the model for a client-executed tool search tool. - The JavaScript source executed by programmatic tool calling. + - `execution: optional "server" or "client"` - - `fingerprint: string` + Whether tool search is executed by the server or by the client. - Opaque program replay fingerprint that must be round-tripped. + - `"server"` - - `type: "program"` + - `"client"` - The type of the item. Always `program`. + - `parameters: optional unknown` - - `agent: optional object { agent_name }` + Parameter schema for a client-executed tool search tool. - The agent that produced this item. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `program_output: object { id, call_id, result, 3 more }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `id: string` + - `"web_search_preview"` - The unique ID of the program output item. + - `"web_search_preview_2025_03_11"` - - `call_id: string` + - `search_content_types: optional array of "text" or "image"` - The call ID of the program item. + - `"text"` - - `result: string` + - `"image"` - The result produced by the program item. + - `search_context_size: optional "low" or "medium" or "high"` - - `status: "completed" or "incomplete"` + 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. - The terminal status of the program output item. + - `"low"` - - `"completed"` + - `"medium"` - - `"incomplete"` + - `"high"` - - `type: "program_output"` + - `user_location: optional object { type, city, country, 2 more }` - The type of the item. Always `program_output`. + The user's location. - - `agent: optional object { agent_name }` + - `type: "approximate"` - The agent that produced this item. + The type of location approximation. Always `approximate`. - - `agent_name: string` + - `city: optional string` - The canonical name of the agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `country: optional string` - - `id: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The unique ID of the tool search call item. + - `region: optional string` - - `arguments: unknown` + Free text input for the region of the user, e.g. `California`. - Arguments used for the tool search call. + - `timezone: optional string` - - `call_id: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique ID of the tool search call generated by the model. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `execution: "server" or "client"` + Allows the assistant to create, delete, or update files using unified diffs. - Whether tool search was executed by the server or by the client. + - `type: "apply_patch"` - - `"server"` + The type of the tool. Always `apply_patch`. - - `"client"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `status: "in_progress" or "completed" or "incomplete"` + The tool invocation context(s). - The status of the tool search call item that was recorded. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `type: "tool_search_output"` - - `"incomplete"` + The item type. Always `tool_search_output`. - - `type: "tool_search_call"` + - `id: optional string` - The type of the item. Always `tool_search_call`. + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -61381,21 +71961,11 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - - `id: string` - - The unique ID of the tool search output item. - - - `call_id: string` + - `call_id: optional string` The unique ID of the tool search call generated by the model. - - `execution: "server" or "client"` + - `execution: optional "server" or "client"` Whether tool search was executed by the server or by the client. @@ -61403,9 +71973,9 @@ openai beta:responses compact \ - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output item that was recorded. + The status of the tool search output. - `"in_progress"` @@ -61413,9 +71983,15 @@ openai beta:responses compact \ - `"incomplete"` + - `additional_tools: object { role, tools, type, 2 more }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + - `tools: array of BetaTool` - The loaded tool definitions returned by tool search. + A list of additional tools made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -61481,9 +72057,13 @@ openai beta:responses compact \ Allows the assistant to create, delete, or update files using unified diffs. - - `type: "tool_search_output"` + - `type: "additional_tools"` - The type of the item. Always `tool_search_output`. + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -61493,132 +72073,85 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `additional_tools: object { id, role, tools, 2 more }` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` - The unique ID of the additional tools item. - - - `role: "unknown" or "user" or "assistant" or 5 more` - - The role that provided the additional tools. - - - `"unknown"` - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"critic"` - - - `"discriminator"` - - - `"developer"` - - - `"tool"` - - - `tools: array of BetaTool` - - The additional tool definitions made available at this item. - - - `beta_function_tool: object { name, parameters, strict, 5 more }` - - 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). - - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - 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). - - - `beta_computer_tool: object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - 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: object { server_label, type, allowed_callers, 9 more }` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The unique identifier of the reasoning content. - - `code_interpreter: object { container, type, allowed_callers }` + - `summary: array of object { text, type }` - A tool that runs Python code to help generate a response to a prompt. + Reasoning summary content. - - `programmatic_tool_calling: object { type }` + - `text: string` - - `image_generation: object { type, action, background, 9 more }` + A summary of the reasoning output from the model so far. - A tool that generates images using the GPT image models. + - `type: "summary_text"` - - `local_shell: object { type }` + The type of the object. Always `summary_text`. - A tool that allows the model to execute shell commands in a local environment. + - `type: "reasoning"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The type of the object. Always `reasoning`. - A tool that allows the model to execute shell commands. + - `agent: optional object { agent_name }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The agent that produced this item. - 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) + - `agent_name: string` - - `beta_namespace_tool: object { description, name, tools, type }` + The canonical name of the agent that produced this item. - Groups function/custom tools under a shared namespace. + - `content: optional array of object { text, type }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + Reasoning text content. - Hosted or BYOT tool search configuration for deferred tools. + - `text: string` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The reasoning text from the model. - 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: "reasoning_text"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The type of the reasoning text. Always `reasoning_text`. - Allows the assistant to create, delete, or update files using unified diffs. + - `encrypted_content: optional string` - - `type: "additional_tools"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The type of the item. Always `additional_tools`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The agent that produced this item. + - `"in_progress"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `id: string` - - The unique ID of the compaction item. - - `encrypted_content: string` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `type: "compaction"` The type of the item. Always `compaction`. + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -61627,10 +72160,6 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -61688,10 +72217,44 @@ openai beta:responses compact \ The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + - `type: "code_interpreter_call"` The type of the code interpreter tool call. Always `code_interpreter_call`. @@ -61700,6 +72263,10 @@ openai beta:responses compact \ The agent that produced this item. + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `local_shell_call: object { id, action, call_id, 3 more }` A tool call to run a command on the local shell. @@ -61796,13 +72363,9 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: string` + - `shell_call: object { action, call_id, type, 5 more }` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - `action: object { commands, max_output_length, timeout_ms }` @@ -61810,41 +72373,61 @@ openai beta:responses compact \ - `commands: array of string` - - `max_output_length: number` + Ordered shell commands for the execution environment to run. - Optional maximum number of characters to return from each command. + - `max_output_length: optional number` - - `timeout_ms: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Optional timeout in milliseconds for the commands. + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `type: "shell_call"` - Represents the use of a local environment to perform shell actions. + The type of the item. Always `shell_call`. - - `beta_response_local_environment: object { type }` + - `id: optional string` - Represents the use of a local environment to perform shell actions. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: "local"` + - `agent: optional object { agent_name }` - The environment type. Always `local`. + The agent that produced this item. - - `beta_response_container_reference: object { container_id, type }` + - `agent_name: string` - Represents a container created with /v1/containers. + The canonical name of the agent that produced this item. - - `container_id: string` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "container_reference"` + The execution context that produced this tool call. - The environment type. Always `container_reference`. + - `direct: object { type }` - - `status: "in_progress" or "completed" or "incomplete"` + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `beta_local_environment: object { type, skills }` + + - `beta_container_reference: object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. @@ -61854,9 +72437,53 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "shell_call"` + - `shell_call_output: object { call_id, output, type, 5 more }` - The type of the item. Always `shell_call`. + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -61880,65 +72507,330 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The ID of the entity that created this tool call. + - `max_output_length: optional number` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The output of a shell tool call that was emitted. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the shell call output. - The unique ID of the shell call output. Populated when this item is returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` - The unique ID of the shell tool call generated by the model. + The unique ID of the apply patch tool call generated by the model. - - `max_output_length: number` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The specific create, delete, or update instruction for the apply_patch tool call. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `create_file: object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `delete_file: object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `update_file: object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `apply_patch_call_output: object { call_id, status, type, 4 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` - An array of shell call output contents + A JSON string of the arguments passed to the tool. - - `outcome: object { type } or object { exit_code, type }` + - `name: string` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The name of the tool that was run. - - `timeout: object { type }` + - `server_label: string` - Indicates that the shell call exceeded its configured time limit. + The label of the MCP server running the tool. - - `exit: object { exit_code, type }` + - `type: "mcp_call"` - Indicates that the shell commands finished and returned an exit code. + The type of the item. Always `mcp_call`. - - `exit_code: number` + - `agent: optional object { agent_name }` - Exit code from the shell process. + The agent that produced this item. - - `type: "exit"` + - `agent_name: string` - The outcome type. Always `exit`. + The canonical name of the agent that produced this item. - - `stderr: string` + - `approval_request_id: optional string` - The standard error output that was captured. + 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. - - `stdout: string` + - `error: optional string` - The standard output that was captured. + The error from the tool call, if any. - - `created_by: optional string` + - `output: optional string` - The identifier of the actor that created the item. + The output from the tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` @@ -61946,107 +72838,110 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "shell_call_output"` + - `"calling"` - The type of the shell call output. Always `shell_call_output`. + - `"failed"` - - `agent: optional object { agent_name }` + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - The agent that produced this item. + The output of a custom tool call from your code, being sent back to the model. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + The call ID, used to map this custom tool call output to a custom tool call. - - `caller: optional object { type } or object { caller_id, type }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The execution context that produced this tool call. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `direct: object { type }` + - `string output: string` - - `program: object { caller_id, type }` + A string of the output of the custom tool call. - - `caller_id: string` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The call ID of the program item that produced this tool call. + Text, image, or file output of the custom tool call. - - `type: "program"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `created_by: optional string` + A text input to the model. - The identifier of the actor that created the item. + - `text: string` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + The text input to the model. - A tool call that applies file diffs by creating, deleting, or updating files. + - `type: "input_text"` - - `id: string` + The type of the input item. Always `input_text`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `prompt_cache_breakpoint: optional object { mode }` - - `call_id: string` + 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. - The unique ID of the apply patch tool call generated by the model. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `detail: "low" or "high" or "auto" or "original"` - - `create_file: object { diff, path, type }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Instruction describing how to create a file via the apply_patch tool. + - `type: "input_image"` - - `diff: string` + The type of the input item. Always `input_image`. - Diff to apply. + - `file_id: optional string` - - `path: string` + The ID of the file to be sent to the model. - Path of the file to create. + - `image_url: optional string` - - `type: "create_file"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Create a new file with the provided diff. + - `prompt_cache_breakpoint: optional object { mode }` - - `delete_file: object { path, type }` + 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. - Instruction describing how to delete a file via the apply_patch tool. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `path: string` + A file input to the model. - Path of the file to delete. + - `type: "input_file"` - - `type: "delete_file"` + The type of the input item. Always `input_file`. - Delete the specified file. + - `detail: optional "auto" or "low" or "high"` - - `update_file: object { diff, path, type }` + 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`. - Instruction describing how to update a file via the apply_patch tool. + - `file_data: optional string` - - `diff: string` + The content of the file to be sent to the model. - Diff to apply. + - `file_id: optional string` - - `path: string` + The ID of the file to be sent to the model. - Path of the file to update. + - `file_url: optional string` - - `type: "update_file"` + The URL of the file to be sent to the model. - Update an existing file with the provided diff. + - `filename: optional string` - - `status: "in_progress" or "completed"` + The name of the file to be sent to the model. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"in_progress"` + 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. - - `"completed"` + - `type: "custom_tool_call_output"` - - `type: "apply_patch_call"` + The type of the custom tool call output. Always `custom_tool_call_output`. - The type of the item. Always `apply_patch_call`. + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. - `agent: optional object { agent_name }` @@ -62070,33 +72965,31 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` - - The ID of the entity that created this tool call. + The caller type. Always `program`. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - The output emitted by an apply patch tool call. + A call to a custom tool created by the model. - - `id: string` + - `call_id: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + An identifier used to map this custom tool call to a tool call output. - - `call_id: string` + - `input: string` - The unique ID of the apply patch tool call generated by the model. + The input for the custom tool call generated by the model. - - `status: "completed" or "failed"` + - `name: string` - The status of the apply patch tool call output. One of `completed` or `failed`. + The name of the custom tool being called. - - `"completed"` + - `type: "custom_tool_call"` - - `"failed"` + The type of the custom tool call. Always `custom_tool_call`. - - `type: "apply_patch_call_output"` + - `id: optional string` - The type of the item. Always `apply_patch_call_output`. + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` @@ -62120,37 +73013,33 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` - - The ID of the entity that created this tool call output. - - - `output: optional string` + - `namespace: optional string` - Optional textual output returned by the apply patch tool. + The namespace of the custom tool being called. - - `mcp_call: object { id, arguments, name, 7 more }` + - `compaction_trigger: object { type, agent }` - An invocation of a tool on an MCP server. + Compacts the current context. Must be the final input item. - - `id: string` + - `type: "compaction_trigger"` - The unique ID of the tool call. + The type of the item. Always `compaction_trigger`. - - `arguments: string` + - `agent: optional object { agent_name }` - A JSON string of the arguments passed to the tool. + The agent that produced this item. - - `name: string` + - `agent_name: string` - The name of the tool that was run. + The canonical name of the agent that produced this item. - - `server_label: string` + - `item_reference: object { id, agent, type }` - The label of the MCP server running the tool. + An internal identifier for an item to reference. - - `type: "mcp_call"` + - `id: string` - The type of the item. Always `mcp_call`. + The ID of the item to reference. - `agent: optional object { agent_name }` @@ -62160,68 +73049,67 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `type: optional "item_reference"` - 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. + The type of item to reference. Always `item_reference`. - - `error: optional string` + - `"item_reference"` - The error from the tool call, if any. + - `program: object { id, call_id, code, 3 more }` - - `output: optional string` + - `id: string` - The output from the tool call. + The unique ID of this program item. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `call_id: string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The stable call ID of the program item. - - `"in_progress"` + - `code: string` - - `"completed"` + The JavaScript source executed by programmatic tool calling. - - `"incomplete"` + - `fingerprint: string` - - `"calling"` + Opaque program replay fingerprint that must be round-tripped. - - `"failed"` + - `type: "program"` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + The item type. Always `program`. - A list of tools available on an MCP server. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - The unique ID of the list. + - `agent_name: string` - - `server_label: string` + The canonical name of the agent that produced this item. - The label of the MCP server. + - `program_output: object { id, call_id, result, 3 more }` - - `tools: array of object { input_schema, name, annotations, description }` + - `id: string` - The tools available on the server. + The unique ID of this program output item. - - `input_schema: unknown` + - `call_id: string` - The JSON schema describing the tool's input. + The call ID of the program item. - - `name: string` + - `result: string` - The name of the tool. + The result produced by the program item. - - `annotations: optional unknown` + - `status: "completed" or "incomplete"` - Additional annotations about the tool. + The terminal status of the program output. - - `description: optional string` + - `"completed"` - The description of the tool. + - `"incomplete"` - - `type: "mcp_list_tools"` + - `type: "program_output"` - The type of the item. Always `mcp_list_tools`. + The item type. Always `program_output`. - `agent: optional object { agent_name }` @@ -62231,1016 +73119,981 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `error: optional string` + - `response_id: string` - Error message if the server could not list tools. + The ID of the active response that should receive the input. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `type: "response.inject"` - A request for human approval of a tool invocation. + The event discriminator. Always `response.inject`. - - `id: string` +### Beta Response Inject Failed Event - The unique ID of the approval request. +- `beta_response_inject_failed_event: object { error, input, response_id, 3 more }` - - `arguments: string` + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - A JSON string of arguments for the tool. + - `error: object { code, message }` - - `name: string` + Information about why the input was not committed. - The name of the tool to run. + - `code: "response_already_completed" or "response_not_found"` - - `server_label: string` + A machine-readable error code. - The label of the MCP server making the request. + - `"response_already_completed"` - - `type: "mcp_approval_request"` + - `"response_not_found"` - The type of the item. Always `mcp_approval_request`. + - `message: string` - - `agent: optional object { agent_name }` + A human-readable description of the error. - The agent that produced this item. + - `input: array of BetaResponseInputItem` - - `agent_name: string` + The raw input items that were not committed. - The canonical name of the agent that produced this item. + - `beta_easy_input_message: object { content, role, phase, type }` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + 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. - A response to an MCP approval request. + - `content: string or BetaResponseInputMessageContentList` - - `id: string` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The unique ID of the approval response + - `Text input: string` - - `approval_request_id: string` + A text input to the model. - The ID of the approval request being answered. + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - `approve: boolean` + A list of one or many input items to the model, containing different content + types. - Whether the request was approved. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `type: "mcp_approval_response"` + A text input to the model. - The type of the item. Always `mcp_approval_response`. + - `text: string` - - `agent: optional object { agent_name }` + The text input to the model. - The agent that produced this item. + - `type: "input_text"` - - `agent_name: string` + The type of the input item. Always `input_text`. - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `reason: optional string` + 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. - Optional reason for the decision. + - `mode: "explicit"` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + The breakpoint mode. Always `explicit`. - A call to a custom tool created by the model. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `call_id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - An identifier used to map this custom tool call to a tool call output. + - `detail: "low" or "high" or "auto" or "original"` - - `input: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The input for the custom tool call generated by the model. + - `"low"` - - `name: string` + - `"high"` - The name of the custom tool being called. + - `"auto"` - - `type: "custom_tool_call"` + - `"original"` - The type of the custom tool call. Always `custom_tool_call`. + - `type: "input_image"` - - `id: optional string` + The type of the input item. Always `input_image`. - The unique ID of the custom tool call in the OpenAI platform. + - `file_id: optional string` - - `agent: optional object { agent_name }` + The ID of the file to be sent to the model. - The agent that produced this item. + - `image_url: optional string` - - `caller: optional object { type } or object { caller_id, type }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The execution context that produced this tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `namespace: optional string` + 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. - The namespace of the custom tool being called. + - `mode: "explicit"` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The breakpoint mode. Always `explicit`. - The output of a custom tool call from your code, being sent back to the model. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `id: string` + A file input to the model. - The unique ID of the custom tool call output item. + - `type: "input_file"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the input item. Always `input_file`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `detail: optional "auto" or "low" or "high"` - - `"in_progress"` + 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`. - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"low"` - - `created_by: optional string` + - `"high"` - The identifier of the actor that created the item. + - `file_data: optional string` - - `parallel_tool_calls: boolean` + The content of the file to be sent to the model. - Whether to allow the model to run tool calls in parallel. + - `file_id: optional string` - - `temperature: number` + The ID of the file to be sent to the model. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `file_url: optional string` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The URL of the file to be sent to the model. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `filename: optional string` - - `beta_tool_choice_options: "none" or "auto" or "required"` + The name of the file to be sent to the model. - Controls which (if any) tool is called by the model. + - `prompt_cache_breakpoint: optional object { mode }` - `none` means the model will not call any tool and instead generates a message. + 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. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `mode: "explicit"` - `required` means the model must call one or more tools. + The breakpoint mode. Always `explicit`. - - `"none"` + - `role: "user" or "assistant" or "system" or "developer"` - - `"auto"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"required"` + - `"user"` - - `beta_tool_choice_allowed: object { mode, tools, type }` + - `"assistant"` - Constrains the tools available to the model to a pre-defined set. + - `"system"` - - `mode: "auto" or "required"` + - `"developer"` - Constrains the tools available to the model to a pre-defined set. + - `phase: optional "commentary" or "final_answer"` - `auto` allows the model to pick from among the allowed tools and generate a - message. + 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. - `required` requires the model to call one or more of the allowed tools. + - `"commentary"` - - `"auto"` + - `"final_answer"` - - `"required"` + - `type: optional "message"` - - `tools: array of map[unknown]` + The type of the message input. Always `message`. - A list of tool definitions that the model should be allowed to call. + - `"message"` - For the Responses API, the list of tool definitions might look like: + - `message: object { content, role, agent, 2 more }` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + 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. - - `type: "allowed_tools"` + - `content: array of BetaResponseInputContent` - Allowed tool configuration type. Always `allowed_tools`. + A list of one or many input items to the model, containing different content + types. - - `beta_tool_choice_types: object { type }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + A text input to the model. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Allowed values are: + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + A file input to the model. - - `"file_search"` + - `role: "user" or "system" or "developer"` - - `"web_search_preview"` + The role of the message input. One of `user`, `system`, or `developer`. - - `"computer"` + - `"user"` - - `"computer_use_preview"` + - `"system"` - - `"computer_use"` + - `"developer"` - - `"web_search_preview_2025_03_11"` + - `agent: optional object { agent_name }` - - `"image_generation"` + The agent that produced this item. - - `"code_interpreter"` + - `agent_name: string` - - `beta_tool_choice_function: object { name, type }` + The canonical name of the agent that produced this item. - Use this option to force the model to call a specific function. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The name of the function to call. + - `"in_progress"` - - `type: "function"` + - `"completed"` - For function calling, the type is always `function`. + - `"incomplete"` - - `beta_tool_choice_mcp: object { server_label, type, name }` + - `type: optional "message"` - Use this option to force the model to call a specific tool on a remote MCP server. + The type of the message input. Always set to `message`. - - `server_label: string` + - `"message"` - The label of the MCP server to use. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `type: "mcp"` + An output message from the model. - For MCP tools, the type is always `mcp`. + - `id: string` - - `name: optional string` + The unique ID of the output message. - The name of the tool to call on the server. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `beta_tool_choice_custom: object { name, type }` + The content of the output message. - Use this option to force the model to call a specific custom tool. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `name: string` + A text output from the model. - The name of the custom tool to call. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `type: "custom"` + The annotations of the text output. - For custom tool calling, the type is always `custom`. + - `file_citation: object { file_id, filename, index, type }` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + A citation to a file. - - `beta_tool_choice_apply_patch: object { type }` + - `file_id: string` - Forces the model to call the apply_patch tool when executing a tool call. + The ID of the file. - - `type: "apply_patch"` + - `filename: string` - The tool to call. Always `apply_patch`. + The filename of the file cited. - - `beta_tool_choice_shell: object { type }` + - `index: number` - Forces the model to call the shell tool when a tool call is required. + The index of the file in the list of files. - - `type: "shell"` + - `type: "file_citation"` - The tool to call. Always `shell`. + The type of the file citation. Always `file_citation`. - - `tools: array of BetaTool` + - `url_citation: object { end_index, start_index, title, 2 more }` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + A citation for a web resource used to generate a model response. - We support the following categories of tools: + - `end_index: number` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The index of the last character of the URL citation in the message. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `start_index: number` - 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). + The index of the first character of the URL citation in the message. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `title: string` - 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). + The title of the web resource. - - `beta_computer_tool: object { type }` + - `type: "url_citation"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the URL citation. Always `url_citation`. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `url: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The URL of the web resource. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - 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). + A citation for a container file used to generate a model response. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `container_id: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The ID of the container file. - - `code_interpreter: object { container, type, allowed_callers }` + - `end_index: number` - A tool that runs Python code to help generate a response to a prompt. + The index of the last character of the container file citation in the message. - - `programmatic_tool_calling: object { type }` + - `file_id: string` - - `image_generation: object { type, action, background, 9 more }` + The ID of the file. - A tool that generates images using the GPT image models. + - `filename: string` - - `local_shell: object { type }` + The filename of the container file cited. - A tool that allows the model to execute shell commands in a local environment. + - `start_index: number` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The index of the first character of the container file citation in the message. - A tool that allows the model to execute shell commands. + - `type: "container_file_citation"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The type of the container file citation. Always `container_file_citation`. - 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) + - `file_path: object { file_id, index, type }` - - `beta_namespace_tool: object { description, name, tools, type }` + A path to a file. - Groups function/custom tools under a shared namespace. + - `file_id: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The ID of the file. - Hosted or BYOT tool search configuration for deferred tools. + - `index: number` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The index of the file in the list of files. - 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: "file_path"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The type of the file path. Always `file_path`. - Allows the assistant to create, delete, or update files using unified diffs. + - `text: string` - - `top_p: number` + The text output from the model. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `type: "output_text"` - We generally recommend altering this or `temperature` but not both. + The type of the output text. Always `output_text`. - - `background: optional boolean` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `token: string` - - `completed_at: optional number` + - `bytes: array of number` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `logprob: number` - - `conversation: optional object { id }` + - `top_logprobs: array of object { token, bytes, logprob }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `token: string` - - `id: string` + - `bytes: array of number` - The unique ID of the conversation that this response was associated with. + - `logprob: number` - - `max_output_tokens: optional number` + - `beta_response_output_refusal: object { refusal, type }` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + A refusal from the model. - - `max_tool_calls: optional number` + - `refusal: string` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The refusal explanation from the model. - - `moderation: optional object { input, output }` + - `type: "refusal"` - Moderation results for the response input and output, if moderated completions were requested. + The type of the refusal. Always `refusal`. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `role: "assistant"` - Moderation for the response input. + The role of the output message. Always `assistant`. - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `status: "in_progress" or "completed" or "incomplete"` - A moderation result produced for the response input or output. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `categories: map[boolean]` + - `"in_progress"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"completed"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"incomplete"` - Which modalities of input are reflected by the score for each category. + - `type: "message"` - - `"text"` + The type of the output message. Always `message`. - - `"image"` + - `agent: optional object { agent_name }` - - `category_scores: map[number]` + The agent that produced this item. - A dictionary of moderation categories to scores. + - `agent_name: string` - - `flagged: boolean` + The canonical name of the agent that produced this item. - A boolean indicating whether the content was flagged by any category. + - `phase: optional "commentary" or "final_answer"` - - `model: string` + 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. - The moderation model that produced this result. + - `"commentary"` - - `type: "moderation_result"` + - `"final_answer"` - The object type, which was always `moderation_result` for successful moderation results. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `error: object { code, message, type }` + 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. - An error produced while attempting moderation for the response input or output. + - `id: string` - - `code: string` + The unique ID of the file search tool call. - The error code. + - `queries: array of string` - - `message: string` + The queries used to search for files. - The error message. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `type: "error"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The object type, which was always `error` for moderation failures. + - `"in_progress"` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"searching"` - Moderation for the response output. + - `"completed"` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `"incomplete"` - A moderation result produced for the response input or output. + - `"failed"` - - `categories: map[boolean]` + - `type: "file_search_call"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The type of the file search tool call. Always `file_search_call`. - - `category_applied_input_types: map[array of "text" or "image"]` + - `agent: optional object { agent_name }` - Which modalities of input are reflected by the score for each category. + The agent that produced this item. - - `"text"` + - `agent_name: string` - - `"image"` + The canonical name of the agent that produced this item. - - `category_scores: map[number]` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - A dictionary of moderation categories to scores. + The results of the file search tool call. - - `flagged: boolean` + - `attributes: optional map[string or number or boolean]` - A boolean indicating whether the content was flagged by any category. + 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. - - `model: string` + - `union_member_0: string` - The moderation model that produced this result. + - `union_member_1: number` - - `type: "moderation_result"` + - `union_member_2: boolean` - The object type, which was always `moderation_result` for successful moderation results. + - `file_id: optional string` - - `error: object { code, message, type }` + The unique ID of the file. - An error produced while attempting moderation for the response input or output. + - `filename: optional string` - - `code: string` + The name of the file. - The error code. + - `score: optional number` - - `message: string` + The relevance score of the file - a value between 0 and 1. - The error message. + - `text: optional string` - - `type: "error"` + The text that was retrieved from the file. - The object type, which was always `error` for moderation failures. + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `previous_response_id: optional string` + 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. - 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`. + - `id: string` - - `prompt: optional object { id, variables, version }` + The unique ID of the computer call. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. - `id: string` - The unique identifier of the prompt template to use. + The ID of the pending safety check. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `code: optional string` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The type of the pending safety check. - - `union_member_0: string` + - `message: optional string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + Details about the pending safety check. - A text input to the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"in_progress"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"completed"` - A file input to the model. + - `"incomplete"` - - `version: optional string` + - `type: "computer_call"` - Optional version of the prompt template. + The type of the computer call. Always `computer_call`. - - `prompt_cache_key: optional string` + - `"computer_call"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `prompt_cache_options: optional object { mode, ttl }` + A click action. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `click: object { button, type, x, 2 more }` - - `mode: "implicit" or "explicit"` + A click action. - Whether implicit prompt-cache breakpoints were enabled. + - `button: "left" or "right" or "wheel" or 2 more` - - `"implicit"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"explicit"` + - `"left"` - - `ttl: "30m"` + - `"right"` - The minimum lifetime applied to each cache breakpoint. + - `"wheel"` - - `"30m"` + - `"back"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"forward"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `type: "click"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + Specifies the event type. For a click action, this property is always `click`. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `x: number` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The x-coordinate where the click occurred. - - `"in_memory"` + - `y: number` - - `"24h"` + The y-coordinate where the click occurred. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `keys: optional array of string` - **gpt-5 and o-series models only** + The keys being held while clicking. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `double_click: object { keys, type, x, y }` - - `context: optional "auto" or "current_turn" or "all_turns"` + A double click action. - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `keys: array of string` - - `"auto"` + The keys being held while double-clicking. - - `"current_turn"` + - `type: "double_click"` - - `"all_turns"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `x: number` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The x-coordinate where the double click occurred. - - `"none"` + - `y: number` - - `"minimal"` + The y-coordinate where the double click occurred. - - `"low"` + - `drag: object { path, type, keys }` - - `"medium"` + A drag action. - - `"high"` + - `path: array of object { x, y }` - - `"xhigh"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"max"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `x: number` - **Deprecated:** use `summary` instead. + The x-coordinate. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `y: number` - - `"auto"` + The y-coordinate. - - `"concise"` + - `type: "drag"` - - `"detailed"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `mode: optional string or "standard" or "pro"` + - `keys: optional array of string` - Controls the reasoning execution mode for the request. + The keys being held while dragging the mouse. - When returned on a response, this is the effective execution mode. + - `keypress: object { keys, type }` - - `"standard"` + A collection of keypresses the model would like to perform. - - `"pro"` + - `keys: array of string` - - `summary: optional "auto" or "concise" or "detailed"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `type: "keypress"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"auto"` + - `move: object { type, x, y, keys }` - - `"concise"` + A mouse move action. - - `"detailed"` + - `type: "move"` - - `safety_identifier: optional string` + Specifies the event type. For a move action, this property is always set to `move`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `x: number` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The x-coordinate to move to. - Specifies the processing type used for serving the request. + - `y: number` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The y-coordinate to move to. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `keys: optional array of string` - - `"auto"` + The keys being held while moving the mouse. - - `"default"` + - `screenshot: object { type }` - - `"flex"` + A screenshot action. - - `"scale"` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `"priority"` + A scroll action. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `scroll_x: number` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The horizontal scroll distance. - - `"completed"` + - `scroll_y: number` - - `"failed"` + The vertical scroll distance. - - `"in_progress"` + - `type: "scroll"` - - `"cancelled"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `type: object { text, type }` - - `"queued"` + An action to type in text. - - `"incomplete"` + - `text: string` - - `text: optional object { format, verbosity }` + The text to type. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `type: "type"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + Specifies the event type. For a type action, this property is always set to `type`. - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `wait: object { type }` - An object specifying the format that the model must output. + A wait action. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `actions: optional array of BetaComputerAction` - The default format is `{ "type": "text" }` with no additional options. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - **Not recommended for gpt-4o and newer models:** + - `click: object { button, type, x, 2 more }` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + A click action. - - `text: object { type }` + - `double_click: object { keys, type, x, y }` - Default response format. Used to generate text responses. + A double click action. - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + - `drag: object { path, type, keys }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + A drag action. - - `name: string` + - `keypress: object { keys, type }` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + A collection of keypresses the model would like to perform. - - `schema: map[unknown]` + - `move: object { type, x, y, keys }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A mouse move action. - - `type: "json_schema"` + - `screenshot: object { type }` - The type of response format being defined. Always `json_schema`. + A screenshot action. - - `description: optional string` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A scroll action. - - `strict: optional boolean` + - `type: object { text, type }` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + An action to type in text. - - `json_object: object { type }` + - `wait: object { type }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + A wait action. - - `verbosity: optional "low" or "medium" or "high"` + - `agent: optional object { agent_name }` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"medium"` + The canonical name of the agent that produced this item. - - `"high"` + - `computer_call_output: object { call_id, output, type, 4 more }` - - `top_logprobs: optional number` + The output of a computer tool call. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `call_id: string` - - `truncation: optional "auto" or "disabled"` + The ID of the computer tool call that produced the output. - The truncation strategy to use for the model response. + - `output: object { type, file_id, image_url }` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + A computer screenshot image used with the computer use tool. - - `"auto"` + - `type: "computer_screenshot"` - - `"disabled"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `file_id: optional string` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The identifier of an uploaded file that contains the screenshot. - - `input_tokens: number` + - `image_url: optional string` - The number of input tokens. + The URL of the screenshot image. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `type: "computer_call_output"` - A detailed breakdown of the input tokens. + The type of the computer tool call output. Always `computer_call_output`. - - `cache_write_tokens: number` + - `id: optional string` - The number of input tokens that were written to the cache. + The ID of the computer tool call output. - - `cached_tokens: number` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The safety checks reported by the API that have been acknowledged by the developer. - - `output_tokens: number` + - `id: string` - The number of output tokens. + The ID of the pending safety check. - - `output_tokens_details: object { reasoning_tokens }` + - `code: optional string` - A detailed breakdown of the output tokens. + The type of the pending safety check. - - `reasoning_tokens: number` + - `message: optional string` - The number of reasoning tokens. + Details about the pending safety check. - - `total_tokens: number` + - `agent: optional object { agent_name }` - The total number of tokens used. + The agent that produced this item. - - `user: optional string` + - `agent_name: string` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The canonical name of the agent that produced this item. - - `sequence_number: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The sequence number for this event. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `type: "response.created"` + - `"in_progress"` - The type of the event. Always `response.created`. + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that owns this multi-agent streaming event. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `id: string` -### Beta Response Custom Tool Call + The unique ID of the web search tool call. -- `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - A call to a custom tool created by the model. + 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). - - `call_id: string` + - `search: object { type, queries, query, sources }` - An identifier used to map this custom tool call to a tool call output. + Action type "search" - Performs a web search query. - - `input: string` + - `type: "search"` - The input for the custom tool call generated by the model. + The action type. - - `name: string` + - `queries: optional array of string` - The name of the custom tool being called. + The search queries. - - `type: "custom_tool_call"` + - `query: optional string` - The type of the custom tool call. Always `custom_tool_call`. + The search query. - - `id: optional string` + - `sources: optional array of object { type, url }` - The unique ID of the custom tool call in the OpenAI platform. + The sources used in the search. - - `agent: optional object { agent_name }` + - `type: "url"` - The agent that produced this item. + The type of source. Always `url`. - - `agent_name: string` + - `url: string` - The canonical name of the agent that produced this item. + The URL of the source. - - `caller: optional object { type } or object { caller_id, type }` + - `open_page: object { type, url }` - The execution context that produced this tool call. + Action type "open_page" - Opens a specific URL from search results. - - `direct: object { type }` + - `type: "open_page"` - - `program: object { caller_id, type }` + The action type. - - `caller_id: string` + - `url: optional string` - The call ID of the program item that produced this tool call. + The URL opened by the model. - - `type: "program"` + - `find_in_page: object { pattern, type, url }` - - `namespace: optional string` + Action type "find_in_page": Searches for a pattern within a loaded page. - The namespace of the custom tool being called. + - `pattern: string` -### Beta Response Custom Tool Call Input Delta Event + The pattern or text to search for within the page. -- `beta_response_custom_tool_call_input_delta_event: object { delta, item_id, output_index, 3 more }` + - `type: "find_in_page"` - Event representing a delta (partial update) to the input of a custom tool call. + The action type. - - `delta: string` + - `url: string` - The incremental input data (delta) for the custom tool call. + The URL of the page searched for the pattern. - - `item_id: string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - Unique identifier for the API item associated with this event. + The status of the web search tool call. - - `output_index: number` + - `"in_progress"` - The index of the output this delta applies to. + - `"searching"` - - `sequence_number: number` + - `"completed"` - The sequence number of this event. + - `"failed"` - - `type: "response.custom_tool_call_input.delta"` + - `type: "web_search_call"` - The event type identifier. + The type of the web search tool call. Always `web_search_call`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Custom Tool Call Input Done Event - -- `beta_response_custom_tool_call_input_done_event: object { input, item_id, output_index, 3 more }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - Event indicating that input for a custom tool call is complete. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `input: string` + - `arguments: string` - The complete input data for the custom tool call. + A JSON string of the arguments to pass to the function. - - `item_id: string` + - `call_id: string` - Unique identifier for the API item associated with this event. + The unique ID of the function tool call generated by the model. - - `output_index: number` + - `name: string` - The index of the output this event applies to. + The name of the function to run. - - `sequence_number: number` + - `type: "function_call"` - The sequence number of this event. + The type of the function tool call. Always `function_call`. - - `type: "response.custom_tool_call_input.done"` + - `id: optional string` - The event type identifier. + The unique ID of the function tool call. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Custom Tool Call Item + - `caller: optional object { type } or object { caller_id, type }` -- `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` + The execution context that produced this tool call. - A call to a custom tool created by the model. + - `direct: object { type }` - - `id: string` + - `program: object { caller_id, type }` - The unique ID of the custom tool call item. + - `caller_id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -63251,34 +74104,27 @@ openai beta:responses compact \ - `"incomplete"` - - `created_by: optional string` - - The identifier of the actor that created the item. - -### Beta Response Custom Tool Call Output - -- `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `function_call_output: object { call_id, output, type, 4 more }` - The output of a custom tool call from your code, being sent back to the model. + The output of a function tool call. - `call_id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the function tool call generated by the model. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `output: string or BetaResponseFunctionCallOutputItemList` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Text, image, or file output of the function tool call. - - `string output: string` + - `union_member_0: string` - A string of the output of the custom tool call. + A JSON string of the output of the function tool call. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - Text, image, or file output of the custom tool call. + An array of content outputs (text, image, file) for the function tool call. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -63298,11 +74144,15 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `detail: "low" or "high" or "auto" or "original"` + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `detail: optional "low" or "high" or "auto" or "original"` The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. @@ -63314,10 +74164,6 @@ openai beta:responses compact \ - `"original"` - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - `file_id: optional string` The ID of the file to be sent to the model. @@ -63334,7 +74180,7 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` A file input to the model. @@ -63354,7 +74200,7 @@ openai beta:responses compact \ - `file_data: optional string` - The content of the file to be sent to the model. + The base64-encoded data of the file to be sent to the model. - `file_id: optional string` @@ -63376,13 +74222,13 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. - - `type: "custom_tool_call_output"` + - `type: "function_call_output"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of the function tool call output. Always `function_call_output`. - `id: optional string` - The unique ID of the custom tool call output in the OpenAI platform. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -63408,1285 +74254,1357 @@ openai beta:responses compact \ The caller type. Always `program`. -### Beta Response Custom Tool Call Output Item + - `status: optional "in_progress" or "completed" or "incomplete"` -- `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The output of a custom tool call from your code, being sent back to the model. + - `"in_progress"` - - `id: string` + - `"completed"` - The unique ID of the custom tool call output item. + - `"incomplete"` - - `status: "in_progress" or "completed" or "incomplete"` + - `agent_message: object { author, content, recipient, 3 more }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A message routed between agents. - - `"in_progress"` + - `author: string` - - `"completed"` + The sending agent identity. - - `"incomplete"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `created_by: optional string` + Plaintext, image, or encrypted content sent between agents. - The identifier of the actor that created the item. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` -### Beta Response Error + A text input to the model. -- `beta_response_error: object { code, message }` + - `text: string` - An error object returned when the model fails to generate a Response. + The text input to the model. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `type: "input_text"` - The error code for the response. + The type of the input item. Always `input_text`. - - `"server_error"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"rate_limit_exceeded"` + 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. - - `"invalid_prompt"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `"bio_policy"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"vector_store_timeout"` + - `type: "input_image"` - - `"invalid_image"` + The type of the input item. Always `input_image`. - - `"invalid_image_format"` + - `detail: optional "low" or "high" or "auto" or "original"` - - `"invalid_base64_image"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"invalid_image_url"` + - `file_id: optional string` - - `"image_too_large"` + The ID of the file to be sent to the model. - - `"image_too_small"` + - `image_url: optional string` - - `"image_parse_error"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"image_content_policy_violation"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"invalid_image_mode"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"image_file_too_large"` + - `encrypted_content: object { encrypted_content, type }` - - `"unsupported_image_media_type"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"empty_image_file"` + - `encrypted_content: string` - - `"failed_to_download_image"` + Opaque encrypted content. - - `"image_file_not_found"` + - `type: "encrypted_content"` - - `message: string` + The type of the input item. Always `encrypted_content`. - A human-readable description of the error. + - `recipient: string` -### Beta Response Error Event + The destination agent identity. -- `beta_response_error_event: object { code, message, param, 3 more }` + - `type: "agent_message"` - Emitted when an error occurs. + The item type. Always `agent_message`. - - `code: string` + - `id: optional string` - The error code. + The unique ID of this agent message item. - - `message: string` + - `agent: optional object { agent_name }` - The error message. + The agent that produced this item. - - `param: string` + - `agent_name: string` - The error parameter. + The canonical name of the agent that produced this item. - - `sequence_number: number` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - The sequence number of this event. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "error"` + The multi-agent action that was executed. - The type of the event. Always `error`. + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The action arguments as a JSON string. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. + + - `id: optional string` + + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Failed Event + - `multi_agent_call_output: object { action, call_id, output, 3 more }` -- `beta_response_failed_event: object { response, sequence_number, type, agent }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - An event that is emitted when a response fails. + The multi-agent action that produced this result. - - `response: object { id, created_at, error, 31 more }` + - `"spawn_agent"` - The response that failed. + - `"interrupt_agent"` - - `id: string` + - `"list_agents"` - Unique identifier for this Response. + - `"send_message"` - - `created_at: number` + - `"followup_task"` - Unix timestamp (in seconds) of when this Response was created. + - `"wait_agent"` - - `error: object { code, message }` + - `call_id: string` - An error object returned when the model fails to generate a Response. + The unique ID of the multi-agent call. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `output: array of object { text, type, annotations }` - The error code for the response. + Text output returned by the multi-agent action. - - `"server_error"` + - `text: string` - - `"rate_limit_exceeded"` + The text content. - - `"invalid_prompt"` + - `type: "output_text"` - - `"bio_policy"` + The content type. Always `output_text`. - - `"vector_store_timeout"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `"invalid_image"` + Citations associated with the text content. - - `"invalid_image_format"` + - `union_member_0: array of object { file_id, filename, index, type }` - - `"invalid_base64_image"` + - `file_id: string` - - `"invalid_image_url"` + The ID of the file. - - `"image_too_large"` + - `filename: string` - - `"image_too_small"` + The filename of the file cited. - - `"image_parse_error"` + - `index: number` - - `"image_content_policy_violation"` + The index of the file in the list of files. - - `"invalid_image_mode"` + - `type: "file_citation"` - - `"image_file_too_large"` + The citation type. Always `file_citation`. - - `"unsupported_image_media_type"` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - `"empty_image_file"` + - `end_index: number` - - `"failed_to_download_image"` + The index of the last character of the citation in the message. - - `"image_file_not_found"` + - `start_index: number` - - `message: string` + The index of the first character of the citation in the message. - A human-readable description of the error. + - `title: string` - - `incomplete_details: object { reason }` + The title of the cited resource. - Details about why the response is incomplete. + - `type: "url_citation"` - - `reason: optional "max_output_tokens" or "content_filter"` + The citation type. Always `url_citation`. - The reason why the response is incomplete. + - `url: string` - - `"max_output_tokens"` + The URL of the cited resource. - - `"content_filter"` + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `instructions: string or array of BetaResponseInputItem` + - `container_id: string` - A system (or developer) message inserted into the model's context. + The ID of the container. - When using 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. + - `end_index: number` - - `union_member_0: string` + The index of the last character of the citation in the message. - A text input to the model, equivalent to a text input with the - `developer` role. + - `file_id: string` - - `Input item list: array of BetaResponseInputItem` + The ID of the container file. - A list of one or many input items to the model, containing - different content types. + - `filename: string` - - `beta_easy_input_message: object { content, role, phase, type }` + The filename of the container file cited. - 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. + - `start_index: number` - - `content: string or BetaResponseInputMessageContentList` + The index of the first character of the citation in the message. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `type: "container_file_citation"` - - `Text input: string` + The citation type. Always `container_file_citation`. - A text input to the model. + - `type: "multi_agent_call_output"` - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + The item type. Always `multi_agent_call_output`. - A list of one or many input items to the model, containing different content - types. + - `id: optional string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The unique ID of this multi-agent call output. - A text input to the model. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The text input to the model. + - `agent_name: string` - - `type: "input_text"` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_text`. + - `tool_search_call: object { arguments, type, id, 4 more }` - - `prompt_cache_breakpoint: optional object { mode }` + - `arguments: unknown` - 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. + The arguments supplied to the tool search call. - - `mode: "explicit"` + - `type: "tool_search_call"` - The breakpoint mode. Always `explicit`. + The item type. Always `tool_search_call`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `id: optional string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique ID of this tool search call. - - `detail: "low" or "high" or "auto" or "original"` + - `agent: optional object { agent_name }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` + - `call_id: optional string` - - `"original"` + The unique ID of the tool search call generated by the model. - - `type: "input_image"` + - `execution: optional "server" or "client"` - The type of the input item. Always `input_image`. + Whether tool search was executed by the server or by the client. - - `file_id: optional string` + - `"server"` - The ID of the file to be sent to the model. + - `"client"` - - `image_url: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The status of the tool search call. - - `prompt_cache_breakpoint: optional object { mode }` + - `"in_progress"` - 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. + - `"completed"` - - `mode: "explicit"` + - `"incomplete"` - The breakpoint mode. Always `explicit`. + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `tools: array of BetaTool` - A file input to the model. + The loaded tool definitions returned by the tool search output. - - `type: "input_file"` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The type of the input item. Always `input_file`. + 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). - - `detail: optional "auto" or "low" or "high"` + - `name: string` - 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`. + The name of the function to call. - - `"auto"` + - `parameters: map[unknown]` - - `"low"` + A JSON schema object describing the parameters of the function. - - `"high"` + - `strict: boolean` - - `file_data: optional string` + Whether strict parameter validation is enforced for this function tool. - The content of the file to be sent to the model. + - `type: "function"` - - `file_id: optional string` + The type of the function tool. Always `function`. - The ID of the file to be sent to the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_url: optional string` + The tool invocation context(s). - The URL of the file to be sent to the model. + - `"direct"` - - `filename: optional string` + - `"programmatic"` - The name of the file to be sent to the model. + - `defer_loading: optional boolean` - - `prompt_cache_breakpoint: optional object { mode }` + Whether this function is deferred and loaded via tool search. - 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. + - `description: optional string` - - `mode: "explicit"` + A description of the function. Used by the model to determine whether or not to call the function. - The breakpoint mode. Always `explicit`. + - `output_schema: optional map[unknown]` - - `role: "user" or "assistant" or "system" or "developer"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"user"` + 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). - - `"assistant"` + - `type: "file_search"` - - `"system"` + The type of the file search tool. Always `file_search`. - - `"developer"` + - `vector_store_ids: array of string` - - `phase: optional "commentary"` + The IDs of the vector stores to search. - 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. + - `filters: optional object { key, type, value } or object { filters, type }` - - `"commentary"` + A filter to apply. - - `type: optional "message"` + - `Comparison Filter: object { key, type, value }` - The type of the message input. Always `message`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"message"` + - `key: string` - - `message: object { content, role, agent, 2 more }` + The key to compare against the value. - 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. + - `type: "eq" or "ne" or "gt" or 5 more` - - `content: array of BetaResponseInputContent` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A list of one or many input items to the model, containing different content - types. + - `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 - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"eq"` - A text input to the model. + - `"ne"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"gt"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"gte"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"lt"` - A file input to the model. + - `"lte"` - - `role: "user" or "system" or "developer"` + - `"in"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"nin"` - - `"user"` + - `value: string or number or boolean or array of string or number` - - `"system"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"developer"` + - `union_member_0: string` - - `agent: optional object { agent_name }` + - `union_member_1: number` - The agent that produced this item. + - `union_member_2: boolean` - - `agent_name: string` + - `union_member_3: array of string or number` - The canonical name of the agent that produced this item. + - `union_member_0: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `union_member_1: number` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Compound Filter: object { filters, type }` - - `"in_progress"` + Combine multiple filters using `and` or `or`. - - `"completed"` + - `filters: array of object { key, type, value } or unknown` - - `"incomplete"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: optional "message"` + - `Comparison Filter: object { key, type, value }` - The type of the message input. Always set to `message`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"message"` + - `key: string` - - `beta_response_output_message: object { id, content, role, 4 more }` + The key to compare against the value. - An output message from the model. + - `type: "eq" or "ne" or "gt" or 5 more` - - `id: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The unique ID of the output message. + - `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 - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"eq"` - The content of the output message. + - `"ne"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"gt"` - A text output from the model. + - `"gte"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"lt"` - The annotations of the text output. + - `"lte"` - - `file_citation: object { file_id, filename, index, type }` + - `"in"` - A citation to a file. + - `"nin"` - - `file_id: string` + - `value: string or number or boolean or array of string or number` - The ID of the file. + The value to compare against the attribute key; supports string, number, or boolean types. - - `filename: string` + - `union_member_0: string` - The filename of the file cited. + - `union_member_1: number` - - `index: number` + - `union_member_2: boolean` - The index of the file in the list of files. + - `union_member_3: array of string or number` - - `type: "file_citation"` + - `union_member_0: string` - The type of the file citation. Always `file_citation`. + - `union_member_1: number` - - `url_citation: object { end_index, start_index, title, 2 more }` + - `union_member_1: unknown` - A citation for a web resource used to generate a model response. + - `type: "and" or "or"` - - `end_index: number` + Type of operation: `and` or `or`. - The index of the last character of the URL citation in the message. + - `"and"` - - `start_index: number` + - `"or"` - The index of the first character of the URL citation in the message. + - `max_num_results: optional number` - - `title: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The title of the web resource. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "url_citation"` + Ranking options for search. - The type of the URL citation. Always `url_citation`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `url: string` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The URL of the web resource. + - `embedding_weight: number` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + The weight of the embedding in the reciprocal ranking fusion. - A citation for a container file used to generate a model response. + - `text_weight: number` - - `container_id: string` + The weight of the text in the reciprocal ranking fusion. - The ID of the container file. + - `ranker: optional "auto" or "default-2024-11-15"` - - `end_index: number` + The ranker to use for the file search. - The index of the last character of the container file citation in the message. + - `"auto"` - - `file_id: string` + - `"default-2024-11-15"` - The ID of the file. + - `score_threshold: optional number` - - `filename: string` + 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. - The filename of the container file cited. + - `beta_computer_tool: object { type }` - - `start_index: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The index of the first character of the container file citation in the message. + - `type: "computer"` - - `type: "container_file_citation"` + The type of the computer tool. Always `computer`. - The type of the container file citation. Always `container_file_citation`. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `file_path: object { file_id, index, type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A path to a file. + - `display_height: number` - - `file_id: string` + The height of the computer display. - The ID of the file. + - `display_width: number` - - `index: number` + The width of the computer display. - The index of the file in the list of files. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `type: "file_path"` + The type of computer environment to control. - The type of the file path. Always `file_path`. + - `"windows"` - - `text: string` + - `"mac"` - The text output from the model. + - `"linux"` - - `type: "output_text"` + - `"ubuntu"` - The type of the output text. Always `output_text`. + - `"browser"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "computer_use_preview"` - - `token: string` + The type of the computer use tool. Always `computer_use_preview`. - - `bytes: array of number` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `logprob: number` + 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). - - `top_logprobs: array of object { token, bytes, logprob }` + - `type: "web_search" or "web_search_2025_08_26"` - - `token: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `bytes: array of number` + - `"web_search"` - - `logprob: number` + - `"web_search_2025_08_26"` - - `beta_response_output_refusal: object { refusal, type }` + - `filters: optional object { allowed_domains }` - A refusal from the model. + Filters for the search. - - `refusal: string` + - `allowed_domains: optional array of string` - The refusal explanation from the model. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `type: "refusal"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The type of the refusal. Always `refusal`. + - `search_context_size: optional "low" or "medium" or "high"` - - `role: "assistant"` + 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. - The role of the output message. Always `assistant`. + - `"low"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"medium"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"high"` - - `"in_progress"` + - `user_location: optional object { city, country, region, 2 more }` - - `"completed"` + The approximate location of the user. - - `"incomplete"` + - `city: optional string` - - `type: "message"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the output message. Always `message`. + - `country: optional string` - - `agent: optional object { agent_name }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The agent that produced this item. + - `region: optional string` - - `agent_name: string` + Free text input for the region of the user, e.g. `California`. - The canonical name of the agent that produced this item. + - `timezone: optional string` - - `phase: optional "commentary"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `type: optional "approximate"` - - `"commentary"` + The type of location approximation. Always `approximate`. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `"approximate"` - 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. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `id: string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The unique ID of the file search tool call. + - `server_label: string` - - `queries: array of string` + A label for this MCP server, used to identify it in tool calls. - The queries used to search for files. + - `type: "mcp"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The type of the MCP tool. Always `mcp`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `MCP allowed tools: array of string` + + A string array of allowed tool names + + - `MCP tool filter: object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"in_progress"` + 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). - - `"searching"` + Currently supported `connector_id` values are: - - `"completed"` + - 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` - - `"incomplete"` + - `"connector_dropbox"` - - `"failed"` + - `"connector_gmail"` - - `type: "file_search_call"` + - `"connector_googlecalendar"` - The type of the file search tool call. Always `file_search_call`. + - `"connector_googledrive"` - - `agent: optional object { agent_name }` + - `"connector_microsoftteams"` - The agent that produced this item. + - `"connector_outlookcalendar"` - - `agent_name: string` + - `"connector_outlookemail"` - The canonical name of the agent that produced this item. + - `"connector_sharepoint"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `defer_loading: optional boolean` - The results of the file search tool call. + Whether this MCP tool is deferred and discovered via tool search. - - `attributes: optional map[string or number or boolean]` + - `headers: optional map[string]` - 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. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `union_member_0: string` + - `require_approval: optional object { always, never } or "always" or "never"` - - `union_member_1: number` + Specify which of the MCP server's tools require approval. - - `union_member_2: boolean` + - `MCP tool approval filter: object { always, never }` - - `file_id: optional string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The unique ID of the file. + - `always: optional object { read_only, tool_names }` - - `filename: optional string` + A filter object to specify which tools are allowed. - The name of the file. + - `read_only: optional boolean` - - `score: optional number` + 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. - The relevance score of the file - a value between 0 and 1. + - `tool_names: optional array of string` - - `text: optional string` + List of allowed tool names. - The text that was retrieved from the file. + - `never: optional object { read_only, tool_names }` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + A filter object to specify which tools are allowed. - 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. + - `read_only: optional boolean` - - `id: string` + 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. - The unique ID of the computer call. + - `tool_names: optional array of string` - - `call_id: string` + List of allowed tool names. - An identifier used when responding to the tool call with output. + - `MCP tool approval setting: "always" or "never"` - - `pending_safety_checks: array of object { id, code, message }` + 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. - The pending safety checks for the computer call. + - `"always"` - - `id: string` + - `"never"` - The ID of the pending safety check. + - `server_description: optional string` - - `code: optional string` + Optional description of the MCP server, used to provide more context. - The type of the pending safety check. + - `server_url: optional string` - - `message: optional string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Details about the pending safety check. + - `tunnel_id: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + 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. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `code_interpreter: object { container, type, allowed_callers }` - - `"in_progress"` + A tool that runs Python code to help generate a response to a prompt. - - `"completed"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"incomplete"` + 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. - - `type: "computer_call"` + - `union_member_0: string` - The type of the computer call. Always `computer_call`. + The container ID. - - `"computer_call"` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - A click action. + - `type: "auto"` - - `click: object { button, type, x, 2 more }` + Always `auto`. - A click action. + - `file_ids: optional array of string` - - `button: "left" or "right" or "wheel" or 2 more` + An optional list of uploaded files to make available to your code. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"left"` + The memory limit for the code interpreter container. - - `"right"` + - `"1g"` - - `"wheel"` + - `"4g"` - - `"back"` + - `"16g"` - - `"forward"` + - `"64g"` - - `type: "click"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Specifies the event type. For a click action, this property is always `click`. + Network access policy for the container. - - `x: number` + - `beta_container_network_policy_disabled: object { type }` - The x-coordinate where the click occurred. + - `type: "disabled"` - - `y: number` + Disable outbound network access. Always `disabled`. - The y-coordinate where the click occurred. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `keys: optional array of string` + - `allowed_domains: array of string` - The keys being held while clicking. + A list of allowed domains when type is `allowlist`. - - `double_click: object { keys, type, x, y }` + - `type: "allowlist"` - A double click action. + Allow outbound network access only to specified domains. Always `allowlist`. - - `keys: array of string` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The keys being held while double-clicking. + Optional domain-scoped secrets for allowlisted domains. - - `type: "double_click"` + - `domain: string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The domain associated with the secret. - - `x: number` + - `name: string` - The x-coordinate where the double click occurred. + The name of the secret to inject for the domain. - - `y: number` + - `value: string` - The y-coordinate where the double click occurred. + The secret value to inject for the domain. - - `drag: object { path, type, keys }` + - `type: "code_interpreter"` - A drag action. + The type of the code interpreter tool. Always `code_interpreter`. - - `path: array of object { x, y }` + - `allowed_callers: optional array of "direct" or "programmatic"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The tool invocation context(s). - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"direct"` - - `x: number` + - `"programmatic"` - The x-coordinate. + - `programmatic_tool_calling: object { type }` - - `y: number` + - `image_generation: object { type, action, background, 9 more }` - The y-coordinate. + A tool that generates images using the GPT image models. - - `type: "drag"` + - `type: "image_generation"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The type of the image generation tool. Always `image_generation`. - - `keys: optional array of string` + - `action: optional "generate" or "edit" or "auto"` - The keys being held while dragging the mouse. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `keypress: object { keys, type }` + - `"generate"` - A collection of keypresses the model would like to perform. + - `"edit"` - - `keys: array of string` + - `"auto"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `background: optional "transparent" or "opaque" or "auto"` - - `type: "keypress"` + 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. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + `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. - - `move: object { type, x, y, keys }` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - A mouse move action. + - `"transparent"` - - `type: "move"` + - `"opaque"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"auto"` - - `x: number` + - `input_fidelity: optional "high" or "low"` - The x-coordinate to move to. + 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`. - - `y: number` + - `"high"` - The y-coordinate to move to. + - `"low"` - - `keys: optional array of string` + - `input_image_mask: optional object { file_id, image_url }` - The keys being held while moving the mouse. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `screenshot: object { type }` + - `file_id: optional string` - A screenshot action. + File ID for the mask image. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `image_url: optional string` - A scroll action. + Base64-encoded mask image. - - `scroll_x: number` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - The horizontal scroll distance. + The image generation model to use. Default: `gpt-image-1`. - - `scroll_y: number` + - `"gpt-image-1"` - The vertical scroll distance. + - `"gpt-image-1-mini"` - - `type: "scroll"` + - `"gpt-image-2"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"gpt-image-2-2026-04-21"` - - `x: number` + - `"gpt-image-1.5"` - The x-coordinate where the scroll occurred. + - `"chatgpt-image-latest"` - - `y: number` + - `moderation: optional "auto" or "low"` - The y-coordinate where the scroll occurred. + Moderation level for the generated image. Default: `auto`. - - `keys: optional array of string` + - `"auto"` - The keys being held while scrolling. + - `"low"` - - `type: object { text, type }` + - `output_compression: optional number` - An action to type in text. + Compression level for the output image. Default: 100. - - `text: string` + - `output_format: optional "png" or "webp" or "jpeg"` - The text to type. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: "type"` + - `"png"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"webp"` - - `wait: object { type }` + - `"jpeg"` - A wait action. + - `partial_images: optional number` - - `actions: optional array of BetaComputerAction` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `click: object { button, type, x, 2 more }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A click action. + - `"low"` - - `double_click: object { keys, type, x, y }` + - `"medium"` - A double click action. + - `"high"` - - `drag: object { path, type, keys }` + - `"auto"` - A drag action. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `keypress: object { keys, type }` + 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`. - A collection of keypresses the model would like to perform. + - `"1024x1024"` - - `move: object { type, x, y, keys }` + - `"1024x1536"` - A mouse move action. + - `"1536x1024"` - - `screenshot: object { type }` + - `"auto"` - A screenshot action. + - `local_shell: object { type }` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + A tool that allows the model to execute shell commands in a local environment. - A scroll action. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `type: object { text, type }` + A tool that allows the model to execute shell commands. - An action to type in text. + - `type: "shell"` - - `wait: object { type }` + The type of the shell tool. Always `shell`. - A wait action. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `computer_call_output: object { call_id, output, type, 4 more }` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - The output of a computer tool call. + - `type: "container_auto"` - - `call_id: string` + Automatically creates a container for this request - The ID of the computer tool call that produced the output. + - `file_ids: optional array of string` - - `output: object { type, file_id, image_url }` + An optional list of uploaded files to make available to your code. - A computer screenshot image used with the computer use tool. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "computer_screenshot"` + The memory limit for the container. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"1g"` - - `file_id: optional string` + - `"4g"` - The identifier of an uploaded file that contains the screenshot. + - `"16g"` - - `image_url: optional string` + - `"64g"` - The URL of the screenshot image. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `type: "computer_call_output"` + Network access policy for the container. - The type of the computer tool call output. Always `computer_call_output`. + - `beta_container_network_policy_disabled: object { type }` - - `id: optional string` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The ID of the computer tool call output. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + An optional list of skills referenced by id or inline data. - The safety checks reported by the API that have been acknowledged by the developer. + - `beta_skill_reference: object { skill_id, type, version }` - - `id: string` + - `skill_id: string` - The ID of the pending safety check. + The ID of the referenced skill. - - `code: optional string` + - `type: "skill_reference"` - The type of the pending safety check. + References a skill created with the /v1/skills endpoint. - - `message: optional string` + - `version: optional string` - Details about the pending safety check. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `agent: optional object { agent_name }` + - `beta_inline_skill: object { description, name, source, type }` - The agent that produced this item. + - `description: string` - - `agent_name: string` + The description of the skill. - The canonical name of the agent that produced this item. + - `name: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The name of the skill. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `source: object { data, media_type, type }` - - `"in_progress"` + Inline skill payload - - `"completed"` + - `data: string` - - `"incomplete"` + Base64-encoded skill zip bundle. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `media_type: "application/zip"` - 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. + The media type of the inline skill payload. Must be `application/zip`. - - `id: string` + - `type: "base64"` - The unique ID of the web search tool call. + The type of the inline skill source. Must be `base64`. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `type: "inline"` - 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). + Defines an inline skill for this request. - - `search: object { type, queries, query, sources }` + - `beta_local_environment: object { type, skills }` - Action type "search" - Performs a web search query. + - `type: "local"` - - `type: "search"` + Use a local computer environment. - The action type. + - `skills: optional array of BetaLocalSkill` - - `queries: optional array of string` + An optional list of skills. - The search queries. + - `description: string` - - `query: optional string` + The description of the skill. - The search query. + - `name: string` - - `sources: optional array of object { type, url }` + The name of the skill. - The sources used in the search. + - `path: string` - - `type: "url"` + The path to the directory containing the skill. - The type of source. Always `url`. + - `beta_container_reference: object { container_id, type }` - - `url: string` + - `container_id: string` - The URL of the source. + The ID of the referenced container. - - `open_page: object { type, url }` + - `type: "container_reference"` - Action type "open_page" - Opens a specific URL from search results. + References a container created with the /v1/containers endpoint - - `type: "open_page"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The action type. + 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) - - `url: optional string` + - `name: string` - The URL opened by the model. + The name of the custom tool, used to identify it in tool calls. - - `find_in_page: object { pattern, type, url }` + - `type: "custom"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The type of the custom tool. Always `custom`. - - `pattern: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The pattern or text to search for within the page. + The tool invocation context(s). - - `type: "find_in_page"` + - `"direct"` - The action type. + - `"programmatic"` - - `url: string` + - `defer_loading: optional boolean` - The URL of the page searched for the pattern. + Whether this tool should be deferred and discovered via tool search. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `description: optional string` - The status of the web search tool call. + Optional description of the custom tool, used to provide more context. - - `"in_progress"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"searching"` + The input format for the custom tool. Default is unconstrained text. - - `"completed"` + - `text: object { type }` - - `"failed"` + Unconstrained free-form text. - - `type: "web_search_call"` + - `grammar: object { definition, syntax, type }` - The type of the web search tool call. Always `web_search_call`. + A grammar defined by the user. - - `agent: optional object { agent_name }` + - `definition: string` - The agent that produced this item. + The grammar definition. - - `agent_name: string` + - `syntax: "lark" or "regex"` - The canonical name of the agent that produced this item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `"lark"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"regex"` - - `arguments: string` + - `type: "grammar"` - A JSON string of the arguments to pass to the function. + Grammar format. Always `grammar`. - - `call_id: string` + - `beta_namespace_tool: object { description, name, tools, type }` - The unique ID of the function tool call generated by the model. + Groups function/custom tools under a shared namespace. - - `name: string` + - `description: string` - The name of the function to run. + A description of the namespace shown to the model. - - `type: "function_call"` + - `name: string` - The type of the function tool call. Always `function_call`. + The namespace name used in tool calls (for example, `crm`). - - `id: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - The unique ID of the function tool call. + The function/custom tools available inside this namespace. - - `agent: optional object { agent_name }` + - `function: object { name, type, allowed_callers, 5 more }` - The agent that produced this item. + - `name: string` - - `agent_name: string` + - `type: "function"` - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `caller: optional object { type } or object { caller_id, type }` + The tool invocation context(s). - The execution context that produced this tool call. + - `"direct"` - - `direct: object { type }` + - `"programmatic"` - - `program: object { caller_id, type }` + - `defer_loading: optional boolean` - - `caller_id: string` + Whether this function should be deferred and discovered via tool search. - The call ID of the program item that produced this tool call. + - `description: optional string` - - `type: "program"` + - `output_schema: optional map[unknown]` - - `namespace: optional string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The namespace of the function to run. + - `parameters: optional unknown` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `strict: optional boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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. - - `"in_progress"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"completed"` + 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) - - `"incomplete"` + - `name: string` - - `function_call_output: object { call_id, output, type, 4 more }` + The name of the custom tool, used to identify it in tool calls. - The output of a function tool call. + - `type: "custom"` - - `call_id: string` + The type of the custom tool. Always `custom`. - The unique ID of the function tool call generated by the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output: string or BetaResponseFunctionCallOutputItemList` + The tool invocation context(s). - Text, image, or file output of the function tool call. + - `defer_loading: optional boolean` - - `union_member_0: string` + Whether this tool should be deferred and discovered via tool search. - A JSON string of the output of the function tool call. + - `description: optional string` - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + Optional description of the custom tool, used to provide more context. - An array of content outputs (text, image, file) for the function tool call. + - `format: optional object { type } or object { definition, syntax, type }` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + The input format for the custom tool. Default is unconstrained text. - A text input to the model. + - `type: "namespace"` - - `text: string` + The type of the tool. Always `namespace`. - The text input to the model. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `type: "input_text"` + Hosted or BYOT tool search configuration for deferred tools. - The type of the input item. Always `input_text`. + - `type: "tool_search"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of the tool. Always `tool_search`. - 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. + - `description: optional string` - - `mode: "explicit"` + Description shown to the model for a client-executed tool search tool. - The breakpoint mode. Always `explicit`. + - `execution: optional "server" or "client"` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + Whether tool search is executed by the server or by the client. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `"server"` - - `type: "input_image"` + - `"client"` - The type of the input item. Always `input_image`. + - `parameters: optional unknown` - - `detail: optional "low" or "high" or "auto" or "original"` + Parameter schema for a client-executed tool search tool. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"low"` + 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). - - `"high"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"auto"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"original"` + - `"web_search_preview"` - - `file_id: optional string` + - `"web_search_preview_2025_03_11"` - The ID of the file to be sent to the model. + - `search_content_types: optional array of "text" or "image"` - - `image_url: optional string` + - `"text"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"image"` - - `prompt_cache_breakpoint: optional object { mode }` + - `search_context_size: optional "low" or "medium" or "high"` - 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. + 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. - - `mode: "explicit"` + - `"low"` - The breakpoint mode. Always `explicit`. + - `"medium"` - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `"high"` - A file input to the model. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "input_file"` + The user's location. - The type of the input item. Always `input_file`. + - `type: "approximate"` - - `detail: optional "auto" or "low" or "high"` + The type of location approximation. Always `approximate`. - 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`. + - `city: optional string` - - `"auto"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"low"` + - `country: optional string` - - `"high"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `file_data: optional string` + - `region: optional string` - The base64-encoded data of the file to be sent to the model. + Free text input for the region of the user, e.g. `California`. - - `file_id: optional string` + - `timezone: optional string` - The ID of the file to be sent to the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `file_url: optional string` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The URL of the file to be sent to the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `filename: optional string` + - `type: "apply_patch"` - The name of the file to be sent to the model. + The type of the tool. Always `apply_patch`. - - `prompt_cache_breakpoint: optional object { mode }` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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. + The tool invocation context(s). - - `mode: "explicit"` + - `"direct"` - The breakpoint mode. Always `explicit`. + - `"programmatic"` - - `type: "function_call_output"` + - `type: "tool_search_output"` - The type of the function tool call output. Always `function_call_output`. + The item type. Always `tool_search_output`. - `id: optional string` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -64696,25 +75614,21 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` + - `call_id: optional string` - - `program: object { caller_id, type }` + The unique ID of the tool search call generated by the model. - - `caller_id: string` + - `execution: optional "server" or "client"` - The call ID of the program item that produced this tool call. + Whether tool search was executed by the server or by the client. - - `type: "program"` + - `"server"` - The caller type. Always `program`. + - `"client"` - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The status of the tool search output. - `"in_progress"` @@ -64722,81 +75636,87 @@ openai beta:responses compact \ - `"incomplete"` - - `agent_message: object { author, content, recipient, 3 more }` + - `additional_tools: object { role, tools, type, 2 more }` - A message routed between agents. + - `role: "developer"` - - `author: string` + The role that provided the additional tools. Only `developer` is supported. - The sending agent identity. + - `tools: array of BetaTool` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + A list of additional tools made available at this item. - Plaintext, image, or encrypted content sent between agents. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + 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). - A text input to the model. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `text: string` + 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). - The text input to the model. + - `beta_computer_tool: object { type }` - - `type: "input_text"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the input item. Always `input_text`. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `prompt_cache_breakpoint: optional object { mode }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - 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. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + 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). - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `type: "input_image"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The type of the input item. Always `input_image`. + - `code_interpreter: object { container, type, allowed_callers }` - - `detail: optional "low" or "high" or "auto" or "original"` + A tool that runs Python code to help generate a response to a prompt. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `programmatic_tool_calling: object { type }` - - `file_id: optional string` + - `image_generation: object { type, action, background, 9 more }` - The ID of the file to be sent to the model. + A tool that generates images using the GPT image models. - - `image_url: optional string` + - `local_shell: object { type }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A tool that allows the model to execute shell commands in a local environment. - - `prompt_cache_breakpoint: optional object { mode }` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - 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. + A tool that allows the model to execute shell commands. - - `encrypted_content: object { encrypted_content, type }` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + 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) - - `encrypted_content: string` + - `beta_namespace_tool: object { description, name, tools, type }` - Opaque encrypted content. + Groups function/custom tools under a shared namespace. - - `type: "encrypted_content"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The type of the input item. Always `encrypted_content`. + Hosted or BYOT tool search configuration for deferred tools. - - `recipient: string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The destination agent identity. + 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: "agent_message"` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The item type. Always `agent_message`. + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. - `id: optional string` - The unique ID of this agent message item. + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -64806,159 +75726,191 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - The multi-agent action that was executed. + - `id: string` - - `"spawn_agent"` + The unique identifier of the reasoning content. - - `"interrupt_agent"` + - `summary: array of object { text, type }` - - `"list_agents"` + Reasoning summary content. - - `"send_message"` + - `text: string` - - `"followup_task"` + A summary of the reasoning output from the model so far. - - `"wait_agent"` + - `type: "summary_text"` - - `arguments: string` + The type of the object. Always `summary_text`. - The action arguments as a JSON string. + - `type: "reasoning"` - - `call_id: string` + The type of the object. Always `reasoning`. - The unique ID linking this call to its output. + - `agent: optional object { agent_name }` - - `type: "multi_agent_call"` + The agent that produced this item. - The item type. Always `multi_agent_call`. + - `agent_name: string` - - `id: optional string` + The canonical name of the agent that produced this item. - The unique ID of this multi-agent call. + - `content: optional array of object { text, type }` - - `agent: optional object { agent_name }` + Reasoning text content. - The agent that produced this item. + - `text: string` - - `agent_name: string` + The reasoning text from the model. - The canonical name of the agent that produced this item. + - `type: "reasoning_text"` - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + The type of the reasoning text. Always `reasoning_text`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `encrypted_content: optional string` - The multi-agent action that produced this result. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"spawn_agent"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"interrupt_agent"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"list_agents"` + - `"in_progress"` - - `"send_message"` + - `"completed"` - - `"followup_task"` + - `"incomplete"` - - `"wait_agent"` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - - `call_id: string` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The unique ID of the multi-agent call. + - `encrypted_content: string` - - `output: array of object { text, type, annotations }` + The encrypted content of the compaction summary. - Text output returned by the multi-agent action. + - `type: "compaction"` - - `text: string` + The type of the item. Always `compaction`. - The text content. + - `id: optional string` - - `type: "output_text"` + The ID of the compaction item. - The content type. Always `output_text`. + - `agent: optional object { agent_name }` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + The agent that produced this item. - Citations associated with the text content. + - `agent_name: string` - - `union_member_0: array of object { file_id, filename, index, type }` + The canonical name of the agent that produced this item. - - `file_id: string` + - `image_generation_call: object { id, result, status, 2 more }` - The ID of the file. + An image generation request made by the model. - - `filename: string` + - `id: string` - The filename of the file cited. + The unique ID of the image generation call. - - `index: number` + - `result: string` - The index of the file in the list of files. + The generated image encoded in base64. - - `type: "file_citation"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The citation type. Always `file_citation`. + The status of the image generation call. - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + - `"in_progress"` - - `end_index: number` + - `"completed"` - The index of the last character of the citation in the message. + - `"generating"` - - `start_index: number` + - `"failed"` - The index of the first character of the citation in the message. + - `type: "image_generation_call"` - - `title: string` + The type of the image generation call. Always `image_generation_call`. - The title of the cited resource. + - `agent: optional object { agent_name }` - - `type: "url_citation"` + The agent that produced this item. - The citation type. Always `url_citation`. + - `agent_name: string` - - `url: string` + The canonical name of the agent that produced this item. - The URL of the cited resource. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. - `container_id: string` - The ID of the container. + The ID of the container used to run the code. - - `end_index: number` + - `outputs: array of object { logs, type } or object { type, url }` - The index of the last character of the citation in the message. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `file_id: string` + - `logs: object { logs, type }` - The ID of the container file. + The logs output from the code interpreter. - - `filename: string` + - `logs: string` - The filename of the container file cited. + The logs output from the code interpreter. - - `start_index: number` + - `type: "logs"` - The index of the first character of the citation in the message. + The type of the output. Always `logs`. - - `type: "container_file_citation"` + - `image: object { type, url }` - The citation type. Always `container_file_citation`. + The image output from the code interpreter. - - `type: "multi_agent_call_output"` + - `type: "image"` - The item type. Always `multi_agent_call_output`. + The type of the output. Always `image`. - - `id: optional string` + - `url: string` - The unique ID of this multi-agent call output. + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. - `agent: optional object { agent_name }` @@ -64968,43 +75920,49 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `tool_search_call: object { arguments, type, id, 4 more }` + - `local_shell_call: object { id, action, call_id, 3 more }` - - `arguments: unknown` + A tool call to run a command on the local shell. - The arguments supplied to the tool search call. + - `id: string` - - `type: "tool_search_call"` + The unique ID of the local shell call. - The item type. Always `tool_search_call`. + - `action: object { command, env, type, 3 more }` - - `id: optional string` + Execute a shell command on the server. - The unique ID of this tool search call. + - `command: array of string` - - `agent: optional object { agent_name }` + The command to run. - The agent that produced this item. + - `env: map[string]` - - `agent_name: string` + Environment variables to set for the command. - The canonical name of the agent that produced this item. + - `type: "exec"` - - `call_id: optional string` + The type of the local shell action. Always `exec`. - The unique ID of the tool search call generated by the model. + - `timeout_ms: optional number` - - `execution: optional "server" or "client"` + Optional timeout in milliseconds for the command. - Whether tool search was executed by the server or by the client. + - `user: optional string` - - `"server"` + Optional user to run the command as. - - `"client"` + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the local shell call. - `"in_progress"` @@ -65012,1049 +75970,1013 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + - `type: "local_shell_call"` - - `tools: array of BetaTool` + The type of the local shell call. Always `local_shell_call`. - The loaded tool definitions returned by the tool search output. + - `agent: optional object { agent_name }` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The agent that produced this item. - 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). + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the function to call. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `parameters: map[unknown]` + The output of a local shell tool call. - A JSON schema object describing the parameters of the function. + - `id: string` - - `strict: boolean` + The unique ID of the local shell tool call generated by the model. - Whether strict parameter validation is enforced for this function tool. + - `output: string` - - `type: "function"` + A JSON string of the output of the local shell tool call. - The type of the function tool. Always `function`. + - `type: "local_shell_call_output"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the local shell tool call output. Always `local_shell_call_output`. - The tool invocation context(s). + - `agent: optional object { agent_name }` - - `"direct"` + The agent that produced this item. - - `"programmatic"` + - `agent_name: string` - - `defer_loading: optional boolean` + The canonical name of the agent that produced this item. - Whether this function is deferred and loaded via tool search. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `description: optional string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - A description of the function. Used by the model to determine whether or not to call the function. + - `"in_progress"` - - `output_schema: optional map[unknown]` + - `"completed"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"incomplete"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `shell_call: object { action, call_id, type, 5 more }` - 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). + A tool representing a request to execute one or more shell commands. - - `type: "file_search"` + - `action: object { commands, max_output_length, timeout_ms }` - The type of the file search tool. Always `file_search`. + The shell commands and limits that describe how to run the tool call. - - `vector_store_ids: array of string` + - `commands: array of string` - The IDs of the vector stores to search. + Ordered shell commands for the execution environment to run. - - `filters: optional object { key, type, value } or object { filters, type }` + - `max_output_length: optional number` - A filter to apply. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `Comparison Filter: object { key, type, value }` + - `timeout_ms: optional number` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `key: string` + - `call_id: string` - The key to compare against the value. + The unique ID of the shell tool call generated by the model. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "shell_call"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the item. Always `shell_call`. - - `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 + - `id: optional string` - - `"eq"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"ne"` + - `agent: optional object { agent_name }` - - `"gt"` + The agent that produced this item. - - `"gte"` + - `agent_name: string` - - `"lt"` + The canonical name of the agent that produced this item. - - `"lte"` + - `caller: optional object { type } or object { caller_id, type }` - - `"in"` + The execution context that produced this tool call. - - `"nin"` + - `direct: object { type }` - - `value: string or number or boolean or array of unknown` + - `program: object { caller_id, type }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `caller_id: string` - - `union_member_0: string` + The call ID of the program item that produced this tool call. - - `union_member_1: number` + - `type: "program"` - - `union_member_2: boolean` + The caller type. Always `program`. - - `union_member_3: array of unknown` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `Compound Filter: object { filters, type }` + The environment to execute the shell commands in. - Combine multiple filters using `and` or `or`. + - `beta_local_environment: object { type, skills }` - - `filters: array of object { key, type, value } or unknown` + - `beta_container_reference: object { container_id, type }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `Comparison Filter: object { key, type, value }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"in_progress"` - - `key: string` + - `"completed"` - The key to compare against the value. + - `"incomplete"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `shell_call_output: object { call_id, output, type, 5 more }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The streamed output items emitted by a shell tool call. - - `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 + - `call_id: string` - - `"eq"` + The unique ID of the shell tool call generated by the model. - - `"ne"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `"gt"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `"gte"` + - `outcome: object { type } or object { exit_code, type }` - - `"lt"` + The exit or timeout outcome associated with this shell call. - - `"lte"` + - `timeout: object { type }` - - `"in"` + Indicates that the shell call exceeded its configured time limit. - - `"nin"` + - `exit: object { exit_code, type }` - - `value: string or number or boolean or array of unknown` + Indicates that the shell commands finished and returned an exit code. - The value to compare against the attribute key; supports string, number, or boolean types. + - `exit_code: number` - - `union_member_0: string` + The exit code returned by the shell process. - - `union_member_1: number` + - `type: "exit"` - - `union_member_2: boolean` + The outcome type. Always `exit`. - - `union_member_3: array of unknown` + - `stderr: string` - - `union_member_1: unknown` + Captured stderr output for the shell call. - - `type: "and" or "or"` + - `stdout: string` - Type of operation: `and` or `or`. + Captured stdout output for the shell call. - - `"and"` + - `type: "shell_call_output"` - - `"or"` + The type of the item. Always `shell_call_output`. - - `max_num_results: optional number` + - `id: optional string` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `agent: optional object { agent_name }` - Ranking options for search. + The agent that produced this item. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `agent_name: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The canonical name of the agent that produced this item. - - `embedding_weight: number` + - `caller: optional object { type } or object { caller_id, type }` - The weight of the embedding in the reciprocal ranking fusion. + The execution context that produced this tool call. - - `text_weight: number` + - `direct: object { type }` - The weight of the text in the reciprocal ranking fusion. + - `program: object { caller_id, type }` - - `ranker: optional "auto" or "default-2024-11-15"` + - `caller_id: string` - The ranker to use for the file search. + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `"default-2024-11-15"` + The caller type. Always `program`. - - `score_threshold: optional number` + - `max_output_length: optional number` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `beta_computer_tool: object { type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The status of the shell call output. - - `type: "computer"` + - `"in_progress"` - The type of the computer tool. Always `computer`. + - `"completed"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `"incomplete"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `apply_patch_call: object { call_id, operation, status, 4 more }` - - `display_height: number` + A tool call representing a request to create, delete, or update files using diff patches. - The height of the computer display. + - `call_id: string` - - `display_width: number` + The unique ID of the apply patch tool call generated by the model. - The width of the computer display. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `environment: "windows" or "mac" or "linux" or 2 more` + The specific create, delete, or update instruction for the apply_patch tool call. - The type of computer environment to control. + - `create_file: object { diff, path, type }` - - `"windows"` + Instruction for creating a new file via the apply_patch tool. - - `"mac"` + - `diff: string` - - `"linux"` + Unified diff content to apply when creating the file. - - `"ubuntu"` + - `path: string` - - `"browser"` + Path of the file to create relative to the workspace root. - - `type: "computer_use_preview"` + - `type: "create_file"` - The type of the computer use tool. Always `computer_use_preview`. + The operation type. Always `create_file`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `delete_file: object { path, type }` - 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). + Instruction for deleting an existing file via the apply_patch tool. - - `type: "web_search" or "web_search_2025_08_26"` + - `path: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Path of the file to delete relative to the workspace root. - - `"web_search"` + - `type: "delete_file"` - - `"web_search_2025_08_26"` + The operation type. Always `delete_file`. - - `filters: optional object { allowed_domains }` + - `update_file: object { diff, path, type }` - Filters for the search. + Instruction for updating an existing file via the apply_patch tool. - - `allowed_domains: optional array of string` + - `diff: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + Unified diff content to apply to the existing file. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `path: string` - - `search_context_size: optional "low" or "medium" or "high"` + Path of the file to update relative to the workspace root. - 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. + - `type: "update_file"` - - `"low"` + The operation type. Always `update_file`. - - `"medium"` + - `status: "in_progress" or "completed"` - - `"high"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `user_location: optional object { city, country, region, 2 more }` + - `"in_progress"` - The approximate location of the user. + - `"completed"` - - `city: optional string` + - `type: "apply_patch_call"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the item. Always `apply_patch_call`. - - `country: optional string` + - `id: optional string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `region: optional string` + - `agent: optional object { agent_name }` - Free text input for the region of the user, e.g. `California`. + The agent that produced this item. - - `timezone: optional string` + - `agent_name: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The canonical name of the agent that produced this item. - - `type: optional "approximate"` + - `caller: optional object { type } or object { caller_id, type }` - The type of location approximation. Always `approximate`. + The execution context that produced this tool call. - - `"approximate"` + - `direct: object { type }` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `program: object { caller_id, type }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `caller_id: string` - - `server_label: string` + The call ID of the program item that produced this tool call. - A label for this MCP server, used to identify it in tool calls. + - `type: "program"` - - `type: "mcp"` + The caller type. Always `program`. - The type of the MCP tool. Always `mcp`. + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The streamed output emitted by an apply patch tool call. - The tool invocation context(s). + - `call_id: string` - - `"direct"` + The unique ID of the apply patch tool call generated by the model. - - `"programmatic"` + - `status: "completed" or "failed"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The status of the apply patch tool call output. One of `completed` or `failed`. - List of allowed tool names or a filter object. + - `"completed"` - - `MCP allowed tools: array of string` + - `"failed"` - A string array of allowed tool names + - `type: "apply_patch_call_output"` - - `MCP tool filter: object { read_only, tool_names }` + The type of the item. Always `apply_patch_call_output`. - A filter object to specify which tools are allowed. + - `id: optional string` - - `read_only: optional boolean` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - 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. + - `agent: optional object { agent_name }` - - `tool_names: optional array of string` + The agent that produced this item. - List of allowed tool names. + - `agent_name: string` - - `authorization: optional string` + The canonical name of the agent that produced this item. - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The execution context that produced this tool call. - 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). + - `direct: object { type }` - Currently supported `connector_id` values are: + - `program: object { caller_id, type }` - - 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` + - `caller_id: string` - - `"connector_dropbox"` + The call ID of the program item that produced this tool call. - - `"connector_gmail"` + - `type: "program"` - - `"connector_googlecalendar"` + The caller type. Always `program`. - - `"connector_googledrive"` + - `output: optional string` - - `"connector_microsoftteams"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"connector_outlookcalendar"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `"connector_outlookemail"` + A list of tools available on an MCP server. - - `"connector_sharepoint"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the list. - Whether this MCP tool is deferred and discovered via tool search. + - `server_label: string` - - `headers: optional map[string]` + The label of the MCP server. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `tools: array of object { input_schema, name, annotations, description }` - - `require_approval: optional object { always, never } or "always" or "never"` + The tools available on the server. - Specify which of the MCP server's tools require approval. + - `input_schema: unknown` - - `MCP tool approval filter: object { always, never }` + The JSON schema describing the tool's input. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `name: string` - - `always: optional object { read_only, tool_names }` + The name of the tool. - A filter object to specify which tools are allowed. + - `annotations: optional unknown` - - `read_only: optional boolean` + Additional annotations about the tool. - 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. + - `description: optional string` - - `tool_names: optional array of string` + The description of the tool. - List of allowed tool names. + - `type: "mcp_list_tools"` - - `never: optional object { read_only, tool_names }` + The type of the item. Always `mcp_list_tools`. - A filter object to specify which tools are allowed. + - `agent: optional object { agent_name }` - - `read_only: optional boolean` + The agent that produced this item. - 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. + - `agent_name: string` - - `tool_names: optional array of string` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `error: optional string` - - `MCP tool approval setting: "always" or "never"` + Error message if the server could not list tools. - 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. + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `"always"` + A request for human approval of a tool invocation. - - `"never"` + - `id: string` - - `server_description: optional string` + The unique ID of the approval request. - Optional description of the MCP server, used to provide more context. + - `arguments: string` - - `server_url: optional string` + A JSON string of arguments for the tool. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `name: string` - - `tunnel_id: optional string` + The name of the tool to run. - 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. + - `server_label: string` - - `code_interpreter: object { container, type, allowed_callers }` + The label of the MCP server making the request. - A tool that runs Python code to help generate a response to a prompt. + - `type: "mcp_approval_request"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The type of the item. Always `mcp_approval_request`. - 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. + - `agent: optional object { agent_name }` - - `union_member_0: string` + The agent that produced this item. - The container ID. + - `agent_name: string` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + The canonical name of the agent that produced this item. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - - `type: "auto"` + A response to an MCP approval request. - Always `auto`. + - `approval_request_id: string` - - `file_ids: optional array of string` + The ID of the approval request being answered. - An optional list of uploaded files to make available to your code. + - `approve: boolean` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Whether the request was approved. - The memory limit for the code interpreter container. + - `type: "mcp_approval_response"` - - `"1g"` + The type of the item. Always `mcp_approval_response`. - - `"4g"` + - `id: optional string` - - `"16g"` + The unique ID of the approval response - - `"64g"` + - `agent: optional object { agent_name }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The agent that produced this item. - Network access policy for the container. + - `agent_name: string` - - `beta_container_network_policy_disabled: object { type }` + The canonical name of the agent that produced this item. - - `type: "disabled"` + - `reason: optional string` - Disable outbound network access. Always `disabled`. + Optional reason for the decision. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `mcp_call: object { id, arguments, name, 7 more }` - - `allowed_domains: array of string` + An invocation of a tool on an MCP server. - A list of allowed domains when type is `allowlist`. + - `id: string` - - `type: "allowlist"` + The unique ID of the tool call. - Allow outbound network access only to specified domains. Always `allowlist`. + - `arguments: string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + A JSON string of the arguments passed to the tool. - Optional domain-scoped secrets for allowlisted domains. + - `name: string` - - `domain: string` + The name of the tool that was run. - The domain associated with the secret. + - `server_label: string` - - `name: string` + The label of the MCP server running the tool. - The name of the secret to inject for the domain. + - `type: "mcp_call"` - - `value: string` + The type of the item. Always `mcp_call`. - The secret value to inject for the domain. + - `agent: optional object { agent_name }` - - `type: "code_interpreter"` + The agent that produced this item. - The type of the code interpreter tool. Always `code_interpreter`. + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `approval_request_id: optional string` - - `"direct"` + 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. - - `"programmatic"` + - `error: optional string` - - `programmatic_tool_calling: object { type }` + The error from the tool call, if any. - - `image_generation: object { type, action, background, 9 more }` + - `output: optional string` - A tool that generates images using the GPT image models. + The output from the tool call. - - `type: "image_generation"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The type of the image generation tool. Always `image_generation`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `action: optional "generate" or "edit" or "auto"` + - `"in_progress"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"completed"` - - `"generate"` + - `"incomplete"` - - `"edit"` + - `"calling"` - - `"auto"` + - `"failed"` - - `background: optional "transparent" or "opaque" or "auto"` + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - 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. + The output of a custom tool call from your code, being sent back to the model. - `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. + - `call_id: string` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The call ID, used to map this custom tool call output to a custom tool call. - - `"transparent"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"opaque"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"auto"` + - `string output: string` - - `input_fidelity: optional "high" or "low"` + A string of the output of the custom tool call. - 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`. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"high"` + Text, image, or file output of the custom tool call. - - `"low"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `input_image_mask: optional object { file_id, image_url }` + A text input to the model. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `text: string` - - `file_id: optional string` + The text input to the model. - File ID for the mask image. + - `type: "input_text"` - - `image_url: optional string` + The type of the input item. Always `input_text`. - Base64-encoded mask image. + - `prompt_cache_breakpoint: optional object { mode }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + 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. - The image generation model to use. Default: `gpt-image-1`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"gpt-image-1"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"gpt-image-1-mini"` + - `detail: "low" or "high" or "auto" or "original"` - - `"gpt-image-2"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"gpt-image-2-2026-04-21"` + - `type: "input_image"` - - `"gpt-image-1.5"` + The type of the input item. Always `input_image`. - - `"chatgpt-image-latest"` + - `file_id: optional string` - - `moderation: optional "auto" or "low"` + The ID of the file to be sent to the model. - Moderation level for the generated image. Default: `auto`. + - `image_url: optional string` - - `"auto"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"low"` + - `prompt_cache_breakpoint: optional object { mode }` - - `output_compression: optional number` + 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. - Compression level for the output image. Default: 100. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `output_format: optional "png" or "webp" or "jpeg"` + A file input to the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `type: "input_file"` - - `"png"` + The type of the input item. Always `input_file`. - - `"webp"` + - `detail: optional "auto" or "low" or "high"` - - `"jpeg"` + 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`. - - `partial_images: optional number` + - `file_data: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The content of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `file_id: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The ID of the file to be sent to the model. - - `"low"` + - `file_url: optional string` - - `"medium"` + The URL of the file to be sent to the model. - - `"high"` + - `filename: optional string` - - `"auto"` + The name of the file to be sent to the model. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - 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`. + 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. - - `"1024x1024"` + - `type: "custom_tool_call_output"` - - `"1024x1536"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"1536x1024"` + - `id: optional string` - - `"auto"` + The unique ID of the custom tool call output in the OpenAI platform. - - `local_shell: object { type }` + - `agent: optional object { agent_name }` - A tool that allows the model to execute shell commands in a local environment. + The agent that produced this item. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `agent_name: string` - A tool that allows the model to execute shell commands. + The canonical name of the agent that produced this item. - - `type: "shell"` + - `caller: optional object { type } or object { caller_id, type }` - The type of the shell tool. Always `shell`. + The execution context that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `direct: object { type }` - The tool invocation context(s). + - `program: object { caller_id, type }` - - `"direct"` + - `caller_id: string` - - `"programmatic"` + The call ID of the program item that produced this tool call. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `type: "program"` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + The caller type. Always `program`. - - `type: "container_auto"` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - Automatically creates a container for this request + A call to a custom tool created by the model. - - `file_ids: optional array of string` + - `call_id: string` - An optional list of uploaded files to make available to your code. + An identifier used to map this custom tool call to a tool call output. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `input: string` - The memory limit for the container. + The input for the custom tool call generated by the model. - - `"1g"` + - `name: string` - - `"4g"` + The name of the custom tool being called. - - `"16g"` + - `type: "custom_tool_call"` - - `"64g"` + The type of the custom tool call. Always `custom_tool_call`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `id: optional string` - Network access policy for the container. + The unique ID of the custom tool call in the OpenAI platform. - - `beta_container_network_policy_disabled: object { type }` + - `agent: optional object { agent_name }` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The agent that produced this item. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `agent_name: string` - An optional list of skills referenced by id or inline data. + The canonical name of the agent that produced this item. - - `beta_skill_reference: object { skill_id, type, version }` + - `caller: optional object { type } or object { caller_id, type }` - - `skill_id: string` + The execution context that produced this tool call. - The ID of the referenced skill. + - `direct: object { type }` - - `type: "skill_reference"` + - `program: object { caller_id, type }` - References a skill created with the /v1/skills endpoint. + - `caller_id: string` - - `version: optional string` + The call ID of the program item that produced this tool call. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `type: "program"` - - `beta_inline_skill: object { description, name, source, type }` + - `namespace: optional string` - - `description: string` + The namespace of the custom tool being called. - The description of the skill. + - `compaction_trigger: object { type, agent }` - - `name: string` + Compacts the current context. Must be the final input item. - The name of the skill. + - `type: "compaction_trigger"` - - `source: object { data, media_type, type }` + The type of the item. Always `compaction_trigger`. - Inline skill payload + - `agent: optional object { agent_name }` - - `data: string` + The agent that produced this item. - Base64-encoded skill zip bundle. + - `agent_name: string` - - `media_type: "application/zip"` + The canonical name of the agent that produced this item. - The media type of the inline skill payload. Must be `application/zip`. + - `item_reference: object { id, agent, type }` - - `type: "base64"` + An internal identifier for an item to reference. - The type of the inline skill source. Must be `base64`. + - `id: string` - - `type: "inline"` + The ID of the item to reference. - Defines an inline skill for this request. + - `agent: optional object { agent_name }` - - `beta_local_environment: object { type, skills }` + The agent that produced this item. - - `type: "local"` + - `agent_name: string` - Use a local computer environment. + The canonical name of the agent that produced this item. - - `skills: optional array of BetaLocalSkill` + - `type: optional "item_reference"` - An optional list of skills. + The type of item to reference. Always `item_reference`. - - `description: string` + - `"item_reference"` - The description of the skill. + - `program: object { id, call_id, code, 3 more }` - - `name: string` + - `id: string` - The name of the skill. + The unique ID of this program item. - - `path: string` + - `call_id: string` - The path to the directory containing the skill. + The stable call ID of the program item. - - `beta_container_reference: object { container_id, type }` + - `code: string` - - `container_id: string` + The JavaScript source executed by programmatic tool calling. - The ID of the referenced container. + - `fingerprint: string` - - `type: "container_reference"` + Opaque program replay fingerprint that must be round-tripped. - References a container created with the /v1/containers endpoint + - `type: "program"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The item type. Always `program`. - 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) + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The name of the custom tool, used to identify it in tool calls. + - `agent_name: string` - - `type: "custom"` + The canonical name of the agent that produced this item. - The type of the custom tool. Always `custom`. + - `program_output: object { id, call_id, result, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of this program output item. - - `"direct"` + - `call_id: string` - - `"programmatic"` + The call ID of the program item. - - `defer_loading: optional boolean` + - `result: string` - Whether this tool should be deferred and discovered via tool search. + The result produced by the program item. - - `description: optional string` + - `status: "completed" or "incomplete"` - Optional description of the custom tool, used to provide more context. + The terminal status of the program output. - - `format: optional object { type } or object { definition, syntax, type }` + - `"completed"` - The input format for the custom tool. Default is unconstrained text. + - `"incomplete"` - - `text: object { type }` + - `type: "program_output"` - Unconstrained free-form text. + The item type. Always `program_output`. - - `grammar: object { definition, syntax, type }` + - `agent: optional object { agent_name }` - A grammar defined by the user. + The agent that produced this item. - - `definition: string` + - `agent_name: string` - The grammar definition. + The canonical name of the agent that produced this item. - - `syntax: "lark" or "regex"` + - `response_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The ID of the response that rejected the input. - - `"lark"` + - `sequence_number: number` - - `"regex"` + The sequence number for this event. - - `type: "grammar"` + - `type: "response.inject.failed"` - Grammar format. Always `grammar`. + The event discriminator. Always `response.inject.failed`. - - `beta_namespace_tool: object { description, name, tools, type }` + - `stream_id: optional string` - Groups function/custom tools under a shared namespace. + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `description: string` +### Beta Response Input - A description of the namespace shown to the model. +- `beta_response_input: array of BetaResponseInputItem` - - `name: string` + A list of one or many input items to the model, containing + different content types. - The namespace name used in tool calls (for example, `crm`). + - `beta_easy_input_message: object { content, role, phase, type }` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + 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. - The function/custom tools available inside this namespace. + - `content: string or BetaResponseInputMessageContentList` - - `function: object { name, type, allowed_callers, 5 more }` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `name: string` + - `Text input: string` - - `type: "function"` + A text input to the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - The tool invocation context(s). + A list of one or many input items to the model, containing different content + types. - - `"direct"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"programmatic"` + A text input to the model. - - `defer_loading: optional boolean` + - `text: string` - Whether this function should be deferred and discovered via tool search. + The text input to the model. - - `description: optional string` + - `type: "input_text"` - - `output_schema: optional map[unknown]` + The type of the input item. Always `input_text`. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `prompt_cache_breakpoint: optional object { mode }` - - `parameters: optional unknown` + 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. - - `strict: optional boolean` + - `mode: "explicit"` - 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. + The breakpoint mode. Always `explicit`. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - 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) + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `name: string` + - `detail: "low" or "high" or "auto" or "original"` - The name of the custom tool, used to identify it in tool calls. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "custom"` + - `"low"` - The type of the custom tool. Always `custom`. + - `"high"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"auto"` - The tool invocation context(s). + - `"original"` - - `defer_loading: optional boolean` + - `type: "input_image"` - Whether this tool should be deferred and discovered via tool search. + The type of the input item. Always `input_image`. - - `description: optional string` + - `file_id: optional string` - Optional description of the custom tool, used to provide more context. + The ID of the file to be sent to the model. - - `format: optional object { type } or object { definition, syntax, type }` + - `image_url: optional string` - The input format for the custom tool. Default is unconstrained text. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: "namespace"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the tool. Always `namespace`. + 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. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `mode: "explicit"` - Hosted or BYOT tool search configuration for deferred tools. + The breakpoint mode. Always `explicit`. - - `type: "tool_search"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The type of the tool. Always `tool_search`. + A file input to the model. - - `description: optional string` + - `type: "input_file"` - Description shown to the model for a client-executed tool search tool. + The type of the input item. Always `input_file`. - - `execution: optional "server" or "client"` + - `detail: optional "auto" or "low" or "high"` - Whether tool search is executed by the server or by the client. + 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`. - - `"server"` + - `"auto"` - - `"client"` + - `"low"` - - `parameters: optional unknown` + - `"high"` - Parameter schema for a client-executed tool search tool. + - `file_data: optional string` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The content of the file to be sent to the model. - 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). + - `file_id: optional string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The ID of the file to be sent to the model. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `file_url: optional string` - - `"web_search_preview"` + The URL of the file to be sent to the model. - - `"web_search_preview_2025_03_11"` + - `filename: optional string` - - `search_content_types: optional array of "text" or "image"` + The name of the file to be sent to the model. - - `"text"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"image"` + 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. - - `search_context_size: optional "low" or "medium" or "high"` + - `mode: "explicit"` - 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. + The breakpoint mode. Always `explicit`. - - `"low"` + - `role: "user" or "assistant" or "system" or "developer"` - - `"medium"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"high"` + - `"user"` - - `user_location: optional object { type, city, country, 2 more }` + - `"assistant"` - The user's location. + - `"system"` - - `type: "approximate"` + - `"developer"` - The type of location approximation. Always `approximate`. + - `phase: optional "commentary" or "final_answer"` - - `city: optional string` + 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. - Free text input for the city of the user, e.g. `San Francisco`. + - `"commentary"` - - `country: optional string` + - `"final_answer"` + + - `type: optional "message"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The type of the message input. Always `message`. - - `region: optional string` + - `"message"` - Free text input for the region of the user, e.g. `California`. + - `message: object { content, role, agent, 2 more }` - - `timezone: optional string` + 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. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `content: array of BetaResponseInputContent` - - `beta_apply_patch_tool: object { type, allowed_callers }` + A list of one or many input items to the model, containing different content + types. - Allows the assistant to create, delete, or update files using unified diffs. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `type: "apply_patch"` + A text input to the model. - The type of the tool. Always `apply_patch`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The tool invocation context(s). + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"direct"` + A file input to the model. - - `"programmatic"` + - `role: "user" or "system" or "developer"` - - `type: "tool_search_output"` + The role of the message input. One of `user`, `system`, or `developer`. - The item type. Always `tool_search_output`. + - `"user"` - - `id: optional string` + - `"system"` - The unique ID of this tool search output. + - `"developer"` - `agent: optional object { agent_name }` @@ -66064,21 +76986,10 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. - - - `execution: optional "server" or "client"` - - Whether tool search was executed by the server or by the client. - - - `"server"` - - - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -66086,174 +76997,174 @@ openai beta:responses compact \ - `"incomplete"` - - `additional_tools: object { role, tools, type, 2 more }` + - `type: optional "message"` - - `role: "developer"` + The type of the message input. Always set to `message`. - The role that provided the additional tools. Only `developer` is supported. + - `"message"` - - `tools: array of BetaTool` + - `beta_response_output_message: object { id, content, role, 4 more }` - A list of additional tools made available at this item. + An output message from the model. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `id: string` - 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). + The unique ID of the output message. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - 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). + The content of the output message. - - `beta_computer_tool: object { type }` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A text output from the model. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The annotations of the text output. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `file_citation: object { file_id, filename, index, type }` - 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). + A citation to a file. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `file_id: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The ID of the file. - - `code_interpreter: object { container, type, allowed_callers }` + - `filename: string` - A tool that runs Python code to help generate a response to a prompt. + The filename of the file cited. - - `programmatic_tool_calling: object { type }` + - `index: number` - - `image_generation: object { type, action, background, 9 more }` + The index of the file in the list of files. - A tool that generates images using the GPT image models. + - `type: "file_citation"` - - `local_shell: object { type }` + The type of the file citation. Always `file_citation`. - A tool that allows the model to execute shell commands in a local environment. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + A citation for a web resource used to generate a model response. - A tool that allows the model to execute shell commands. + - `end_index: number` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The index of the last character of the URL citation in the message. - 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) + - `start_index: number` - - `beta_namespace_tool: object { description, name, tools, type }` + The index of the first character of the URL citation in the message. - Groups function/custom tools under a shared namespace. + - `title: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The title of the web resource. - Hosted or BYOT tool search configuration for deferred tools. + - `type: "url_citation"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The type of the URL citation. Always `url_citation`. - 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). + - `url: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The URL of the web resource. - Allows the assistant to create, delete, or update files using unified diffs. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `type: "additional_tools"` + A citation for a container file used to generate a model response. - The item type. Always `additional_tools`. + - `container_id: string` - - `id: optional string` + The ID of the container file. - The unique ID of this additional tools item. + - `end_index: number` - - `agent: optional object { agent_name }` + The index of the last character of the container file citation in the message. - The agent that produced this item. + - `file_id: string` - - `agent_name: string` + The ID of the file. - The canonical name of the agent that produced this item. + - `filename: string` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + The filename of the container file cited. - 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). + - `start_index: number` - - `id: string` + The index of the first character of the container file citation in the message. - The unique identifier of the reasoning content. + - `type: "container_file_citation"` - - `summary: array of object { text, type }` + The type of the container file citation. Always `container_file_citation`. - Reasoning summary content. + - `file_path: object { file_id, index, type }` - - `text: string` + A path to a file. - A summary of the reasoning output from the model so far. + - `file_id: string` - - `type: "summary_text"` + The ID of the file. - The type of the object. Always `summary_text`. + - `index: number` - - `type: "reasoning"` + The index of the file in the list of files. - The type of the object. Always `reasoning`. + - `type: "file_path"` - - `agent: optional object { agent_name }` + The type of the file path. Always `file_path`. - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text output from the model. - The canonical name of the agent that produced this item. + - `type: "output_text"` - - `content: optional array of object { text, type }` + The type of the output text. Always `output_text`. - Reasoning text content. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `text: string` + - `token: string` - The reasoning text from the model. + - `bytes: array of number` - - `type: "reasoning_text"` + - `logprob: number` - The type of the reasoning text. Always `reasoning_text`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `encrypted_content: optional string` + - `token: string` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `bytes: array of number` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `logprob: number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_response_output_refusal: object { refusal, type }` - - `"in_progress"` + A refusal from the model. - - `"completed"` + - `refusal: string` - - `"incomplete"` + The refusal explanation from the model. - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `type: "refusal"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The type of the refusal. Always `refusal`. - - `encrypted_content: string` + - `role: "assistant"` - The encrypted content of the compaction summary. + The role of the output message. Always `assistant`. - - `type: "compaction"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the item. Always `compaction`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `id: optional string` + - `"in_progress"` - The ID of the compaction item. + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. - `agent: optional object { agent_name }` @@ -66263,33 +77174,47 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `image_generation_call: object { id, result, status, 2 more }` + - `phase: optional "commentary" or "final_answer"` - An image generation request made by the model. + 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"` + + - `"final_answer"` + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` - The unique ID of the image generation call. + The unique ID of the file search tool call. - - `result: string` + - `queries: array of string` - The generated image encoded in base64. + The queries used to search for files. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The status of the image generation call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - - `"generating"` + - `"incomplete"` - `"failed"` - - `type: "image_generation_call"` + - `type: "file_search_call"` - The type of the image generation call. Always `image_generation_call`. + The type of the file search tool call. Always `file_search_call`. - `agent: optional object { agent_name }` @@ -66299,54 +77224,73 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - A tool call to run code. + The results of the file search tool call. - - `id: string` + - `attributes: optional map[string or number or boolean]` - The unique ID of the code interpreter tool call. + 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. - - `code: string` + - `union_member_0: string` - The code to run, or null if not available. + - `union_member_1: number` - - `container_id: string` + - `union_member_2: boolean` - The ID of the container used to run the code. + - `file_id: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + The unique ID of the file. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `filename: optional string` - - `logs: object { logs, type }` + The name of the file. - The logs output from the code interpreter. + - `score: optional number` - - `logs: string` + The relevance score of the file - a value between 0 and 1. - The logs output from the code interpreter. + - `text: optional string` - - `type: "logs"` + The text that was retrieved from the file. - The type of the output. Always `logs`. + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `image: object { type, url }` + 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. - The image output from the code interpreter. + - `id: string` - - `type: "image"` + The unique ID of the computer call. - The type of the output. Always `image`. + - `call_id: string` - - `url: string` + An identifier used when responding to the tool call with output. - The URL of the image output from the code interpreter. + - `pending_safety_checks: array of object { id, code, message }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The pending safety checks for the computer call. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -66354,271 +77298,290 @@ openai beta:responses compact \ - `"incomplete"` - - `"interpreting"` + - `type: "computer_call"` - - `"failed"` + The type of the computer call. Always `computer_call`. - - `type: "code_interpreter_call"` + - `"computer_call"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `agent: optional object { agent_name }` + A click action. - The agent that produced this item. + - `click: object { button, type, x, 2 more }` - - `agent_name: string` + A click action. - The canonical name of the agent that produced this item. + - `button: "left" or "right" or "wheel" or 2 more` - - `local_shell_call: object { id, action, call_id, 3 more }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - A tool call to run a command on the local shell. + - `"left"` - - `id: string` + - `"right"` - The unique ID of the local shell call. + - `"wheel"` - - `action: object { command, env, type, 3 more }` + - `"back"` - Execute a shell command on the server. + - `"forward"` - - `command: array of string` + - `type: "click"` - The command to run. + Specifies the event type. For a click action, this property is always `click`. - - `env: map[string]` + - `x: number` - Environment variables to set for the command. + The x-coordinate where the click occurred. - - `type: "exec"` + - `y: number` - The type of the local shell action. Always `exec`. + The y-coordinate where the click occurred. - - `timeout_ms: optional number` + - `keys: optional array of string` - Optional timeout in milliseconds for the command. + The keys being held while clicking. - - `user: optional string` + - `double_click: object { keys, type, x, y }` - Optional user to run the command as. + A double click action. - - `working_directory: optional string` + - `keys: array of string` - Optional working directory to run the command in. + The keys being held while double-clicking. - - `call_id: string` + - `type: "double_click"` - The unique ID of the local shell tool call generated by the model. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `status: "in_progress" or "completed" or "incomplete"` + - `x: number` - The status of the local shell call. + The x-coordinate where the double click occurred. - - `"in_progress"` + - `y: number` - - `"completed"` + The y-coordinate where the double click occurred. - - `"incomplete"` + - `drag: object { path, type, keys }` - - `type: "local_shell_call"` + A drag action. - The type of the local shell call. Always `local_shell_call`. + - `path: array of object { x, y }` - - `agent: optional object { agent_name }` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The agent that produced this item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `agent_name: string` + - `x: number` - The canonical name of the agent that produced this item. + The x-coordinate. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `y: number` - The output of a local shell tool call. + The y-coordinate. - - `id: string` + - `type: "drag"` - The unique ID of the local shell tool call generated by the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `output: string` + - `keys: optional array of string` - A JSON string of the output of the local shell tool call. + The keys being held while dragging the mouse. - - `type: "local_shell_call_output"` + - `keypress: object { keys, type }` - The type of the local shell tool call output. Always `local_shell_call_output`. + A collection of keypresses the model would like to perform. - - `agent: optional object { agent_name }` + - `keys: array of string` - The agent that produced this item. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `agent_name: string` + - `type: "keypress"` - The canonical name of the agent that produced this item. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `move: object { type, x, y, keys }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + A mouse move action. - - `"in_progress"` + - `type: "move"` - - `"completed"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"incomplete"` + - `x: number` - - `shell_call: object { action, call_id, type, 5 more }` + The x-coordinate to move to. - A tool representing a request to execute one or more shell commands. + - `y: number` - - `action: object { commands, max_output_length, timeout_ms }` + The y-coordinate to move to. - The shell commands and limits that describe how to run the tool call. + - `keys: optional array of string` - - `commands: array of string` + The keys being held while moving the mouse. - Ordered shell commands for the execution environment to run. + - `screenshot: object { type }` - - `max_output_length: optional number` + A screenshot action. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `timeout_ms: optional number` + A scroll action. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `scroll_x: number` - - `call_id: string` + The horizontal scroll distance. - The unique ID of the shell tool call generated by the model. + - `scroll_y: number` - - `type: "shell_call"` + The vertical scroll distance. - The type of the item. Always `shell_call`. + - `type: "scroll"` - - `id: optional string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `x: number` - - `agent: optional object { agent_name }` + The x-coordinate where the scroll occurred. - The agent that produced this item. + - `y: number` - - `agent_name: string` + The y-coordinate where the scroll occurred. - The canonical name of the agent that produced this item. + - `keys: optional array of string` - - `caller: optional object { type } or object { caller_id, type }` + The keys being held while scrolling. - The execution context that produced this tool call. + - `type: object { text, type }` - - `direct: object { type }` + An action to type in text. - - `program: object { caller_id, type }` + - `text: string` - - `caller_id: string` + The text to type. - The call ID of the program item that produced this tool call. + - `type: "type"` - - `type: "program"` + Specifies the event type. For a type action, this property is always set to `type`. - The caller type. Always `program`. + - `wait: object { type }` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + A wait action. - The environment to execute the shell commands in. + - `actions: optional array of BetaComputerAction` - - `beta_local_environment: object { type, skills }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `beta_container_reference: object { container_id, type }` + - `click: object { button, type, x, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A click action. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `double_click: object { keys, type, x, y }` - - `"in_progress"` + A double click action. - - `"completed"` + - `drag: object { path, type, keys }` - - `"incomplete"` + A drag action. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `keypress: object { keys, type }` - The streamed output items emitted by a shell tool call. + A collection of keypresses the model would like to perform. - - `call_id: string` + - `move: object { type, x, y, keys }` - The unique ID of the shell tool call generated by the model. + A mouse move action. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `screenshot: object { type }` - Captured chunks of stdout and stderr output, along with their associated outcomes. + A screenshot action. - - `outcome: object { type } or object { exit_code, type }` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The exit or timeout outcome associated with this shell call. + A scroll action. - - `timeout: object { type }` + - `type: object { text, type }` - Indicates that the shell call exceeded its configured time limit. + An action to type in text. - - `exit: object { exit_code, type }` + - `wait: object { type }` - Indicates that the shell commands finished and returned an exit code. + A wait action. - - `exit_code: number` + - `agent: optional object { agent_name }` - The exit code returned by the shell process. + The agent that produced this item. - - `type: "exit"` + - `agent_name: string` - The outcome type. Always `exit`. + The canonical name of the agent that produced this item. - - `stderr: string` + - `computer_call_output: object { call_id, output, type, 4 more }` - Captured stderr output for the shell call. + The output of a computer tool call. - - `stdout: string` + - `call_id: string` - Captured stdout output for the shell call. + The ID of the computer tool call that produced the output. - - `type: "shell_call_output"` + - `output: object { type, file_id, image_url }` - The type of the item. Always `shell_call_output`. + A computer screenshot image used with the computer use tool. - - `id: optional string` + - `type: "computer_screenshot"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `agent: optional object { agent_name }` + - `file_id: optional string` - The agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `agent_name: string` + - `image_url: optional string` - The canonical name of the agent that produced this item. + The URL of the screenshot image. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "computer_call_output"` - The execution context that produced this tool call. + The type of the computer tool call output. Always `computer_call_output`. - - `direct: object { type }` + - `id: optional string` - - `program: object { caller_id, type }` + The ID of the computer tool call output. - - `caller_id: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The call ID of the program item that produced this tool call. + The safety checks reported by the API that have been acknowledged by the developer. - - `type: "program"` + - `id: string` - The caller type. Always `program`. + The ID of the pending safety check. - - `max_output_length: optional number` + - `code: optional string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the shell call output. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -66626,125 +77589,124 @@ openai beta:responses compact \ - `"incomplete"` - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - A tool call representing a request to create, delete, or update files using diff patches. + 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. - - `call_id: string` + - `id: string` - The unique ID of the apply patch tool call generated by the model. + The unique ID of the web search tool call. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The specific create, delete, or update instruction for the apply_patch tool call. + 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). - - `create_file: object { diff, path, type }` + - `search: object { type, queries, query, sources }` - Instruction for creating a new file via the apply_patch tool. + Action type "search" - Performs a web search query. - - `diff: string` + - `type: "search"` - Unified diff content to apply when creating the file. + The action type. - - `path: string` + - `queries: optional array of string` - Path of the file to create relative to the workspace root. + The search queries. - - `type: "create_file"` + - `query: optional string` - The operation type. Always `create_file`. + The search query. - - `delete_file: object { path, type }` + - `sources: optional array of object { type, url }` - Instruction for deleting an existing file via the apply_patch tool. + The sources used in the search. - - `path: string` + - `type: "url"` - Path of the file to delete relative to the workspace root. + The type of source. Always `url`. - - `type: "delete_file"` + - `url: string` - The operation type. Always `delete_file`. + The URL of the source. - - `update_file: object { diff, path, type }` + - `open_page: object { type, url }` - Instruction for updating an existing file via the apply_patch tool. + Action type "open_page" - Opens a specific URL from search results. - - `diff: string` + - `type: "open_page"` - Unified diff content to apply to the existing file. + The action type. - - `path: string` + - `url: optional string` - Path of the file to update relative to the workspace root. + The URL opened by the model. - - `type: "update_file"` + - `find_in_page: object { pattern, type, url }` - The operation type. Always `update_file`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `status: "in_progress" or "completed"` + - `pattern: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The pattern or text to search for within the page. - - `"in_progress"` + - `type: "find_in_page"` - - `"completed"` + The action type. - - `type: "apply_patch_call"` + - `url: string` - The type of the item. Always `apply_patch_call`. + The URL of the page searched for the pattern. - - `id: optional string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The status of the web search tool call. - - `agent: optional object { agent_name }` + - `"in_progress"` - The agent that produced this item. + - `"searching"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"failed"` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "web_search_call"` - The execution context that produced this tool call. + The type of the web search tool call. Always `web_search_call`. - - `direct: object { type }` + - `agent: optional object { agent_name }` - - `program: object { caller_id, type }` + The agent that produced this item. - - `caller_id: string` + - `agent_name: string` - The call ID of the program item that produced this tool call. + The canonical name of the agent that produced this item. - - `type: "program"` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The caller type. Always `program`. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `arguments: string` - The streamed output emitted by an apply patch tool call. + A JSON string of the arguments to pass to the function. - `call_id: string` - The unique ID of the apply patch tool call generated by the model. - - - `status: "completed" or "failed"` - - The status of the apply patch tool call output. One of `completed` or `failed`. + The unique ID of the function tool call generated by the model. - - `"completed"` + - `name: string` - - `"failed"` + The name of the function to run. - - `type: "apply_patch_call_output"` + - `type: "function_call"` - The type of the item. Always `apply_patch_call_output`. + The type of the function tool call. Always `function_call`. - `id: optional string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -66768,147 +77730,146 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `output: optional string` + - `namespace: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The namespace of the function to run. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A list of tools available on an MCP server. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `id: string` + - `"in_progress"` - The unique ID of the list. + - `"completed"` - - `server_label: string` + - `"incomplete"` - The label of the MCP server. + - `function_call_output: object { call_id, output, type, 4 more }` - - `tools: array of object { input_schema, name, annotations, description }` + The output of a function tool call. - The tools available on the server. + - `call_id: string` - - `input_schema: unknown` + The unique ID of the function tool call generated by the model. - The JSON schema describing the tool's input. + - `output: string or BetaResponseFunctionCallOutputItemList` - - `name: string` + Text, image, or file output of the function tool call. - The name of the tool. + - `union_member_0: string` - - `annotations: optional unknown` + A JSON string of the output of the function tool call. - Additional annotations about the tool. + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - - `description: optional string` + An array of content outputs (text, image, file) for the function tool call. - The description of the tool. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `type: "mcp_list_tools"` + A text input to the model. - The type of the item. Always `mcp_list_tools`. + - `text: string` - - `agent: optional object { agent_name }` + The text input to the model. - The agent that produced this item. + - `type: "input_text"` - - `agent_name: string` + The type of the input item. Always `input_text`. - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `error: optional string` + 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. - Error message if the server could not list tools. + - `mode: "explicit"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The breakpoint mode. Always `explicit`. - A request for human approval of a tool invocation. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The unique ID of the approval request. + - `type: "input_image"` - - `arguments: string` + The type of the input item. Always `input_image`. - A JSON string of arguments for the tool. + - `detail: optional "low" or "high" or "auto" or "original"` - - `name: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The name of the tool to run. + - `"low"` - - `server_label: string` + - `"high"` - The label of the MCP server making the request. + - `"auto"` - - `type: "mcp_approval_request"` + - `"original"` - The type of the item. Always `mcp_approval_request`. + - `file_id: optional string` - - `agent: optional object { agent_name }` + The ID of the file to be sent to the model. - The agent that produced this item. + - `image_url: optional string` - - `agent_name: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + 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. - A response to an MCP approval request. + - `mode: "explicit"` - - `approval_request_id: string` + The breakpoint mode. Always `explicit`. - The ID of the approval request being answered. + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `approve: boolean` + A file input to the model. - Whether the request was approved. + - `type: "input_file"` - - `type: "mcp_approval_response"` + The type of the input item. Always `input_file`. - The type of the item. Always `mcp_approval_response`. + - `detail: optional "auto" or "low" or "high"` - - `id: optional string` + 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`. - The unique ID of the approval response + - `"auto"` - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `"high"` - - `agent_name: string` + - `file_data: optional string` - The canonical name of the agent that produced this item. + The base64-encoded data of the file to be sent to the model. - - `reason: optional string` + - `file_id: optional string` - Optional reason for the decision. + The ID of the file to be sent to the model. - - `mcp_call: object { id, arguments, name, 7 more }` + - `file_url: optional string` - An invocation of a tool on an MCP server. + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - The unique ID of the tool call. + The name of the file to be sent to the model. - - `arguments: string` + - `prompt_cache_breakpoint: optional object { mode }` - A JSON string of the arguments passed to the tool. + 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. - - `name: string` + - `mode: "explicit"` - The name of the tool that was run. + The breakpoint mode. Always `explicit`. - - `server_label: string` + - `type: "function_call_output"` - The label of the MCP server running the tool. + The type of the function tool call output. Always `function_call_output`. - - `type: "mcp_call"` + - `id: optional string` - The type of the item. Always `mcp_call`. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -66918,22 +77879,25 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - - `error: optional string` + - `direct: object { type }` - The error from the tool call, if any. + - `program: object { caller_id, type }` - - `output: optional string` + - `caller_id: string` - The output from the tool call. + The call ID of the program item that produced this tool call. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `type: "program"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The caller type. Always `program`. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -66941,32 +77905,19 @@ openai beta:responses compact \ - `"incomplete"` - - `"calling"` - - - `"failed"` - - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - The output of a custom tool call from your code, being sent back to the model. - - - `call_id: string` - - The call ID, used to map this custom tool call output to a custom tool call. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `agent_message: object { author, content, recipient, 3 more }` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + A message routed between agents. - - `string output: string` + - `author: string` - A string of the output of the custom tool call. + The sending agent identity. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - Text, image, or file output of the custom tool call. + Plaintext, image, or encrypted content sent between agents. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -66982,18 +77933,18 @@ openai beta:responses compact \ 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. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` The type of the input item. Always `input_image`. + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `file_id: optional string` The ID of the file to be sent to the model. @@ -67006,45 +77957,71 @@ openai beta:responses compact \ 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. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `encrypted_content: object { encrypted_content, type }` - A file input to the model. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: "input_file"` + - `encrypted_content: string` - The type of the input item. Always `input_file`. + Opaque encrypted content. - - `detail: optional "auto" or "low" or "high"` + - `type: "encrypted_content"` - 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`. + The type of the input item. Always `encrypted_content`. - - `file_data: optional string` + - `recipient: string` - The content of the file to be sent to the model. + The destination agent identity. - - `file_id: optional string` + - `type: "agent_message"` - The ID of the file to be sent to the model. + The item type. Always `agent_message`. - - `file_url: optional string` + - `id: optional string` - The URL of the file to be sent to the model. + The unique ID of this agent message item. - - `filename: optional string` + - `agent: optional object { agent_name }` - The name of the file to be sent to the model. + The agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - - `type: "custom_tool_call_output"` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The action arguments as a JSON string. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. - `id: optional string` - The unique ID of the custom tool call output in the OpenAI platform. + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -67054,95 +78031,117 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - The execution context that produced this tool call. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of object { text, type, annotations }` + + Text output returned by the multi-agent action. - - `direct: object { type }` + - `text: string` - - `program: object { caller_id, type }` + The text content. - - `caller_id: string` + - `type: "output_text"` - The call ID of the program item that produced this tool call. + The content type. Always `output_text`. - - `type: "program"` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - The caller type. Always `program`. + Citations associated with the text content. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `union_member_0: array of object { file_id, filename, index, type }` - A call to a custom tool created by the model. + - `file_id: string` - - `call_id: string` + The ID of the file. - An identifier used to map this custom tool call to a tool call output. + - `filename: string` - - `input: string` + The filename of the file cited. - The input for the custom tool call generated by the model. + - `index: number` - - `name: string` + The index of the file in the list of files. - The name of the custom tool being called. + - `type: "file_citation"` - - `type: "custom_tool_call"` + The citation type. Always `file_citation`. - The type of the custom tool call. Always `custom_tool_call`. + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - `id: optional string` + - `end_index: number` - The unique ID of the custom tool call in the OpenAI platform. + The index of the last character of the citation in the message. - - `agent: optional object { agent_name }` + - `start_index: number` - The agent that produced this item. + The index of the first character of the citation in the message. - - `agent_name: string` + - `title: string` - The canonical name of the agent that produced this item. + The title of the cited resource. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "url_citation"` - The execution context that produced this tool call. + The citation type. Always `url_citation`. - - `direct: object { type }` + - `url: string` - - `program: object { caller_id, type }` + The URL of the cited resource. - - `caller_id: string` + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - The call ID of the program item that produced this tool call. + - `container_id: string` - - `type: "program"` + The ID of the container. - - `namespace: optional string` + - `end_index: number` - The namespace of the custom tool being called. + The index of the last character of the citation in the message. - - `compaction_trigger: object { type, agent }` + - `file_id: string` - Compacts the current context. Must be the final input item. + The ID of the container file. - - `type: "compaction_trigger"` + - `filename: string` - The type of the item. Always `compaction_trigger`. + The filename of the container file cited. - - `agent: optional object { agent_name }` + - `start_index: number` - The agent that produced this item. + The index of the first character of the citation in the message. - - `agent_name: string` + - `type: "container_file_citation"` - The canonical name of the agent that produced this item. + The citation type. Always `container_file_citation`. - - `item_reference: object { id, agent, type }` + - `type: "multi_agent_call_output"` - An internal identifier for an item to reference. + The item type. Always `multi_agent_call_output`. - - `id: string` + - `id: optional string` - The ID of the item to reference. + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -67152,33 +78151,19 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `type: optional "item_reference"` - - The type of item to reference. Always `item_reference`. - - - `"item_reference"` - - - `program: object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of this program item. - - - `call_id: string` - - The stable call ID of the program item. + - `tool_search_call: object { arguments, type, id, 4 more }` - - `code: string` + - `arguments: unknown` - The JavaScript source executed by programmatic tool calling. + The arguments supplied to the tool search call. - - `fingerprint: string` + - `type: "tool_search_call"` - Opaque program replay fingerprint that must be round-tripped. + The item type. Always `tool_search_call`. - - `type: "program"` + - `id: optional string` - The item type. Always `program`. + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -67188,1060 +78173,1079 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `program_output: object { id, call_id, result, 3 more }` + - `call_id: optional string` - - `id: string` + The unique ID of the tool search call generated by the model. - The unique ID of this program output item. + - `execution: optional "server" or "client"` - - `call_id: string` + Whether tool search was executed by the server or by the client. - The call ID of the program item. + - `"server"` - - `result: string` + - `"client"` - The result produced by the program item. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `status: "completed" or "incomplete"` + The status of the tool search call. - The terminal status of the program output. + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - The item type. Always `program_output`. + - `tools: array of BetaTool` - - `agent: optional object { agent_name }` + The loaded tool definitions returned by the tool search output. - The agent that produced this item. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `name: string` - - `metadata: map[string]` + The name of the function to call. - 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. + - `parameters: map[unknown]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A JSON schema object describing the parameters of the function. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `strict: boolean` - Model ID used to generate the response, like `gpt-4o` 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. + Whether strict parameter validation is enforced for this function tool. - - `"gpt-5.6-sol"` + - `type: "function"` - - `"gpt-5.6-terra"` + The type of the function tool. Always `function`. - - `"gpt-5.6-luna"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.4"` + The tool invocation context(s). - - `"gpt-5.4-mini"` + - `"direct"` - - `"gpt-5.4-nano"` + - `"programmatic"` - - `"gpt-5.4-mini-2026-03-17"` + - `defer_loading: optional boolean` - - `"gpt-5.4-nano-2026-03-17"` + Whether this function is deferred and loaded via tool search. - - `"gpt-5.3-chat-latest"` + - `description: optional string` - - `"gpt-5.2"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"gpt-5.2-2025-12-11"` + - `output_schema: optional map[unknown]` - - `"gpt-5.2-chat-latest"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"gpt-5.2-pro"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"gpt-5.2-pro-2025-12-11"` + 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). - - `"gpt-5.1"` + - `type: "file_search"` - - `"gpt-5.1-2025-11-13"` + The type of the file search tool. Always `file_search`. - - `"gpt-5.1-codex"` + - `vector_store_ids: array of string` - - `"gpt-5.1-mini"` + The IDs of the vector stores to search. - - `"gpt-5.1-chat-latest"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"gpt-5"` + A filter to apply. - - `"gpt-5-mini"` + - `Comparison Filter: object { key, type, value }` - - `"gpt-5-nano"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-5-2025-08-07"` + - `key: string` - - `"gpt-5-mini-2025-08-07"` + The key to compare against the value. - - `"gpt-5-nano-2025-08-07"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-5-chat-latest"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4.1"` + - `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 - - `"gpt-4.1-mini"` + - `"eq"` - - `"gpt-4.1-nano"` + - `"ne"` - - `"gpt-4.1-2025-04-14"` + - `"gt"` - - `"gpt-4.1-mini-2025-04-14"` + - `"gte"` - - `"gpt-4.1-nano-2025-04-14"` + - `"lt"` - - `"o4-mini"` + - `"lte"` - - `"o4-mini-2025-04-16"` + - `"in"` - - `"o3"` + - `"nin"` - - `"o3-2025-04-16"` + - `value: string or number or boolean or array of string or number` - - `"o3-mini"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"o3-mini-2025-01-31"` + - `union_member_0: string` - - `"o1"` + - `union_member_1: number` - - `"o1-2024-12-17"` + - `union_member_2: boolean` - - `"o1-preview"` + - `union_member_3: array of string or number` - - `"o1-preview-2024-09-12"` + - `union_member_0: string` - - `"o1-mini"` + - `union_member_1: number` - - `"o1-mini-2024-09-12"` + - `Compound Filter: object { filters, type }` - - `"gpt-4o"` + Combine multiple filters using `and` or `or`. - - `"gpt-4o-2024-11-20"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-4o-2024-08-06"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-4o-2024-05-13"` + - `Comparison Filter: object { key, type, value }` - - `"gpt-4o-audio-preview"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4o-audio-preview-2024-10-01"` + - `key: string` - - `"gpt-4o-audio-preview-2024-12-17"` + The key to compare against the value. - - `"gpt-4o-audio-preview-2025-06-03"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4o-mini-audio-preview"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `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 - - `"gpt-4o-search-preview"` + - `"eq"` - - `"gpt-4o-mini-search-preview"` + - `"ne"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"gt"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"gte"` - - `"chatgpt-4o-latest"` + - `"lt"` - - `"codex-mini-latest"` + - `"lte"` - - `"gpt-4o-mini"` + - `"in"` - - `"gpt-4o-mini-2024-07-18"` + - `"nin"` - - `"gpt-4-turbo"` + - `value: string or number or boolean or array of string or number` - - `"gpt-4-turbo-2024-04-09"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-4-0125-preview"` + - `union_member_0: string` - - `"gpt-4-turbo-preview"` + - `union_member_1: number` - - `"gpt-4-1106-preview"` + - `union_member_2: boolean` - - `"gpt-4-vision-preview"` + - `union_member_3: array of string or number` - - `"gpt-4"` + - `union_member_0: string` - - `"gpt-4-0314"` + - `union_member_1: number` - - `"gpt-4-0613"` + - `union_member_1: unknown` - - `"gpt-4-32k"` + - `type: "and" or "or"` - - `"gpt-4-32k-0314"` + Type of operation: `and` or `or`. - - `"gpt-4-32k-0613"` + - `"and"` - - `"gpt-3.5-turbo"` + - `"or"` - - `"gpt-3.5-turbo-16k"` + - `max_num_results: optional number` - - `"gpt-3.5-turbo-0301"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-3.5-turbo-0613"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"gpt-3.5-turbo-1106"` + Ranking options for search. - - `"gpt-3.5-turbo-0125"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"gpt-3.5-turbo-16k-0613"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"o1-pro"` + - `embedding_weight: number` - - `"o1-pro-2025-03-19"` + The weight of the embedding in the reciprocal ranking fusion. - - `"o3-pro"` + - `text_weight: number` - - `"o3-pro-2025-06-10"` + The weight of the text in the reciprocal ranking fusion. - - `"o3-deep-research"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"o3-deep-research-2025-06-26"` + The ranker to use for the file search. - - `"o4-mini-deep-research"` + - `"auto"` - - `"o4-mini-deep-research-2025-06-26"` + - `"default-2024-11-15"` - - `"computer-use-preview"` + - `score_threshold: optional number` - - `"computer-use-preview-2025-03-11"` + 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. - - `"gpt-5-codex"` + - `beta_computer_tool: object { type }` - - `"gpt-5-pro"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-5-pro-2025-10-06"` + - `type: "computer"` - - `"gpt-5.1-codex-max"` + The type of the computer tool. Always `computer`. - - `object: "response"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The object type of this resource - always set to `response`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `output: array of BetaResponseOutputItem` + - `display_height: number` - An array of content items generated by the model. + The height of the computer display. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `display_width: number` - - `beta_response_output_message: object { id, content, role, 4 more }` + The width of the computer display. - An output message from the model. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `id: string` + The type of computer environment to control. - The unique ID of the output message. + - `"windows"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"mac"` - The content of the output message. + - `"linux"` - - `role: "assistant"` + - `"ubuntu"` - The role of the output message. Always `assistant`. + - `"browser"` - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "computer_use_preview"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The type of the computer use tool. Always `computer_use_preview`. - - `type: "message"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the output message. Always `message`. + 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). - - `agent: optional object { agent_name }` + - `type: "web_search" or "web_search_2025_08_26"` - The agent that produced this item. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `phase: optional "commentary"` + - `"web_search"` - 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. + - `"web_search_2025_08_26"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `filters: optional object { allowed_domains }` - 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. + Filters for the search. - - `id: string` + - `allowed_domains: optional array of string` - The unique ID of the file search tool call. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `queries: array of string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The queries used to search for files. + - `search_context_size: optional "low" or "medium" or "high"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + 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. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"low"` - - `type: "file_search_call"` + - `"medium"` - The type of the file search tool call. Always `file_search_call`. + - `"high"` - - `agent: optional object { agent_name }` + - `user_location: optional object { city, country, region, 2 more }` - The agent that produced this item. + The approximate location of the user. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `city: optional string` - The results of the file search tool call. + Free text input for the city of the user, e.g. `San Francisco`. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `country: optional string` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `arguments: string` + - `region: optional string` - A JSON string of the arguments to pass to the function. + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The unique ID of the function tool call generated by the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `name: string` + - `type: optional "approximate"` - The name of the function to run. + The type of location approximation. Always `approximate`. - - `type: "function_call"` + - `"approximate"` - The type of the function tool call. Always `function_call`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `id: optional string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The unique ID of the function tool call. + - `server_label: string` - - `agent: optional object { agent_name }` + A label for this MCP server, used to identify it in tool calls. - The agent that produced this item. + - `type: "mcp"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the MCP tool. Always `mcp`. - The execution context that produced this tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `namespace: optional string` + The tool invocation context(s). - The namespace of the function to run. + - `"direct"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"programmatic"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + List of allowed tool names or a filter object. - - `id: string` + - `MCP allowed tools: array of string` - The unique ID of the function call tool output. + A string array of allowed tool names - - `call_id: string` + - `MCP tool filter: object { read_only, tool_names }` - The unique ID of the function tool call generated by the model. + A filter object to specify which tools are allowed. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `read_only: optional boolean` - The output from the function call generated by your code. - Can be a string or an list of output content. + 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. - - `string output: string` + - `tool_names: optional array of string` - A string of the output of the function call. + List of allowed tool names. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `authorization: optional string` - Text, image, or file output of the function call. + 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. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - A text input to the model. + 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). - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + Currently supported `connector_id` values are: - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - 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` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"connector_dropbox"` - A file input to the model. + - `"connector_gmail"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"connector_googlecalendar"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"connector_googledrive"` - - `"in_progress"` + - `"connector_microsoftteams"` - - `"completed"` + - `"connector_outlookcalendar"` - - `"incomplete"` + - `"connector_outlookemail"` - - `type: "function_call_output"` + - `"connector_sharepoint"` - The type of the function tool call output. Always `function_call_output`. + - `defer_loading: optional boolean` - - `agent: optional object { agent_name }` + Whether this MCP tool is deferred and discovered via tool search. - The agent that produced this item. + - `headers: optional map[string]` - - `agent_name: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The canonical name of the agent that produced this item. + - `require_approval: optional object { always, never } or "always" or "never"` - - `caller: optional object { type } or object { caller_id, type }` + Specify which of the MCP server's tools require approval. - The execution context that produced this tool call. + - `MCP tool approval filter: object { always, never }` - - `direct: object { type }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `program: object { caller_id, type }` + - `always: optional object { read_only, tool_names }` - - `caller_id: string` + A filter object to specify which tools are allowed. - The call ID of the program item that produced this tool call. + - `read_only: optional boolean` - - `type: "program"` + 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. - The caller type. Always `program`. + - `tool_names: optional array of string` - - `created_by: optional string` + List of allowed tool names. - The identifier of the actor that created the item. + - `never: optional object { read_only, tool_names }` - - `agent_message: object { id, author, content, 3 more }` + A filter object to specify which tools are allowed. - - `id: string` + - `read_only: optional boolean` - The unique ID of the agent message. + 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. - - `author: string` + - `tool_names: optional array of string` - The sending agent identity. + List of allowed tool names. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `MCP tool approval setting: "always" or "never"` - Encrypted content sent between agents. + 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. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"always"` - A text input to the model. + - `"never"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `server_description: optional string` - A text output from the model. + Optional description of the MCP server, used to provide more context. - - `text: object { text, type }` + - `server_url: optional string` - A text content. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `text: string` + - `tunnel_id: optional string` - - `type: "text"` + 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. - - `summary_text: object { text, type }` + - `code_interpreter: object { container, type, allowed_callers }` - A summary text from the model. + A tool that runs Python code to help generate a response to a prompt. - - `text: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - A summary of the reasoning output from the model so far. + 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. - - `type: "summary_text"` + - `union_member_0: string` - The type of the object. Always `summary_text`. + The container ID. - - `reasoning_text: object { text, type }` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - Reasoning text from the model. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `text: string` + - `type: "auto"` - The reasoning text from the model. + Always `auto`. - - `type: "reasoning_text"` + - `file_ids: optional array of string` - The type of the reasoning text. Always `reasoning_text`. + An optional list of uploaded files to make available to your code. - - `beta_response_output_refusal: object { refusal, type }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - A refusal from the model. + The memory limit for the code interpreter container. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"1g"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"4g"` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `"16g"` - A screenshot of a computer. + - `"64g"` - - `detail: "low" or "high" or "auto" or "original"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Network access policy for the container. - - `"low"` + - `beta_container_network_policy_disabled: object { type }` - - `"high"` + - `type: "disabled"` - - `"auto"` + Disable outbound network access. Always `disabled`. - - `"original"` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `file_id: string` + - `allowed_domains: array of string` - The identifier of an uploaded file that contains the screenshot. + A list of allowed domains when type is `allowlist`. - - `image_url: string` + - `type: "allowlist"` - The URL of the screenshot image. + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "computer_screenshot"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Optional domain-scoped secrets for allowlisted domains. - - `prompt_cache_breakpoint: optional object { mode }` + - `domain: string` - 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. + The domain associated with the secret. - - `mode: "explicit"` + - `name: string` - The breakpoint mode. Always `explicit`. + The name of the secret to inject for the domain. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `value: string` - A file input to the model. + The secret value to inject for the domain. - - `encrypted_content: object { encrypted_content, type }` + - `type: "code_interpreter"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The type of the code interpreter tool. Always `code_interpreter`. - - `encrypted_content: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Opaque encrypted content. + The tool invocation context(s). - - `type: "encrypted_content"` + - `"direct"` - The type of the input item. Always `encrypted_content`. + - `"programmatic"` - - `recipient: string` + - `programmatic_tool_calling: object { type }` - The destination agent identity. + - `image_generation: object { type, action, background, 9 more }` - - `type: "agent_message"` + A tool that generates images using the GPT image models. - The type of the item. Always `agent_message`. + - `type: "image_generation"` - - `agent: optional object { agent_name }` + The type of the image generation tool. Always `image_generation`. - The agent that produced this item. + - `action: optional "generate" or "edit" or "auto"` - - `agent_name: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The canonical name of the agent that produced this item. + - `"generate"` - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `"edit"` - - `id: string` + - `"auto"` - The unique ID of the multi-agent call item. + - `background: optional "transparent" or "opaque" or "auto"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + 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. - The multi-agent action to execute. + `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. - - `"spawn_agent"` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `"interrupt_agent"` + - `"transparent"` - - `"list_agents"` + - `"opaque"` - - `"send_message"` + - `"auto"` - - `"followup_task"` + - `input_fidelity: optional "high" or "low"` - - `"wait_agent"` + 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`. - - `arguments: string` + - `"high"` - The JSON string of arguments generated for the action. + - `"low"` - - `call_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The unique ID linking this call to its output. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "multi_agent_call"` + - `file_id: optional string` - The type of the multi-agent call. Always `multi_agent_call`. + File ID for the mask image. - - `agent: optional object { agent_name }` + - `image_url: optional string` - The agent that produced this item. + Base64-encoded mask image. - - `agent_name: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - The canonical name of the agent that produced this item. + The image generation model to use. Default: `gpt-image-1`. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `"gpt-image-1"` - - `id: string` + - `"gpt-image-1-mini"` - The unique ID of the multi-agent call output item. + - `"gpt-image-2"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"gpt-image-2-2026-04-21"` - The multi-agent action that produced this result. + - `"gpt-image-1.5"` - - `"spawn_agent"` + - `"chatgpt-image-latest"` - - `"interrupt_agent"` + - `moderation: optional "auto" or "low"` - - `"list_agents"` + Moderation level for the generated image. Default: `auto`. - - `"send_message"` + - `"auto"` - - `"followup_task"` + - `"low"` - - `"wait_agent"` + - `output_compression: optional number` - - `call_id: string` + Compression level for the output image. Default: 100. - The unique ID of the multi-agent call. + - `output_format: optional "png" or "webp" or "jpeg"` - - `output: array of BetaResponseOutputText` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Text output returned by the multi-agent action. + - `"png"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"webp"` - The annotations of the text output. + - `"jpeg"` - - `text: string` + - `partial_images: optional number` - The text output from the model. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "output_text"` + - `quality: optional "low" or "medium" or "high" or "auto"` - The type of the output text. Always `output_text`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"low"` - - `type: "multi_agent_call_output"` + - `"medium"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"high"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `agent_name: string` + 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`. - The canonical name of the agent that produced this item. + - `"1024x1024"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `"1024x1536"` - 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. + - `"1536x1024"` - - `id: string` + - `"auto"` - The unique ID of the web search tool call. + - `local_shell: object { type }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + A tool that allows the model to execute shell commands in a local environment. - 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). + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + A tool that allows the model to execute shell commands. - The status of the web search tool call. + - `type: "shell"` - - `type: "web_search_call"` + The type of the shell tool. Always `shell`. - The type of the web search tool call. Always `web_search_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `"programmatic"` - 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. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: string` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - The unique ID of the computer call. + - `type: "container_auto"` - - `call_id: string` + Automatically creates a container for this request - An identifier used when responding to the tool call with output. + - `file_ids: optional array of string` - - `pending_safety_checks: array of object { id, code, message }` + An optional list of uploaded files to make available to your code. - The pending safety checks for the computer call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `status: "in_progress" or "completed" or "incomplete"` + The memory limit for the container. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"1g"` - - `type: "computer_call"` + - `"4g"` - The type of the computer call. Always `computer_call`. + - `"16g"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `"64g"` - A click action. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `actions: optional array of BetaComputerAction` + Network access policy for the container. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `beta_container_network_policy_disabled: object { type }` - - `agent: optional object { agent_name }` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The agent that produced this item. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + An optional list of skills referenced by id or inline data. - - `id: string` + - `beta_skill_reference: object { skill_id, type, version }` - The unique ID of the computer call tool output. + - `skill_id: string` - - `call_id: string` + The ID of the referenced skill. - The ID of the computer tool call that produced the output. + - `type: "skill_reference"` - - `output: object { type, file_id, image_url }` + References a skill created with the /v1/skills endpoint. - A computer screenshot image used with the computer use tool. + - `version: optional string` - - `type: "computer_screenshot"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `beta_inline_skill: object { description, name, source, type }` - - `file_id: optional string` + - `description: string` - The identifier of an uploaded file that contains the screenshot. + The description of the skill. - - `image_url: optional string` + - `name: string` - The URL of the screenshot image. + The name of the skill. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `source: object { data, media_type, type }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Inline skill payload - - `"completed"` + - `data: string` - - `"incomplete"` + Base64-encoded skill zip bundle. - - `"failed"` + - `media_type: "application/zip"` - - `"in_progress"` + The media type of the inline skill payload. Must be `application/zip`. - - `type: "computer_call_output"` + - `type: "base64"` - The type of the computer tool call output. Always `computer_call_output`. + The type of the inline skill source. Must be `base64`. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "inline"` - The safety checks reported by the API that have been acknowledged by the - developer. + Defines an inline skill for this request. - - `id: string` + - `beta_local_environment: object { type, skills }` - The ID of the pending safety check. + - `type: "local"` - - `code: optional string` + Use a local computer environment. - The type of the pending safety check. + - `skills: optional array of BetaLocalSkill` - - `message: optional string` + An optional list of skills. - Details about the pending safety check. + - `description: string` - - `agent: optional object { agent_name }` + The description of the skill. - The agent that produced this item. + - `name: string` - - `agent_name: string` + The name of the skill. - The canonical name of the agent that produced this item. + - `path: string` - - `created_by: optional string` + The path to the directory containing the skill. - The identifier of the actor that created the item. + - `beta_container_reference: object { container_id, type }` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `container_id: string` - 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). + The ID of the referenced container. - - `id: string` + - `type: "container_reference"` - The unique identifier of the reasoning content. + References a container created with the /v1/containers endpoint - - `summary: array of object { text, type }` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Reasoning summary content. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: "reasoning"` + - `name: string` - The type of the object. Always `reasoning`. + The name of the custom tool, used to identify it in tool calls. - - `agent: optional object { agent_name }` + - `type: "custom"` - The agent that produced this item. + The type of the custom tool. Always `custom`. - - `content: optional array of object { text, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Reasoning text content. + The tool invocation context(s). - - `encrypted_content: optional string` + - `"direct"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"programmatic"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `defer_loading: optional boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Whether this tool should be deferred and discovered via tool search. - - `program: object { id, call_id, code, 3 more }` + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the program item. + - `format: optional object { type } or object { definition, syntax, type }` - - `call_id: string` + The input format for the custom tool. Default is unconstrained text. - The stable call ID of the program item. + - `text: object { type }` - - `code: string` + Unconstrained free-form text. - The JavaScript source executed by programmatic tool calling. + - `grammar: object { definition, syntax, type }` - - `fingerprint: string` + A grammar defined by the user. - Opaque program replay fingerprint that must be round-tripped. + - `definition: string` - - `type: "program"` + The grammar definition. - The type of the item. Always `program`. + - `syntax: "lark" or "regex"` - - `agent: optional object { agent_name }` + The syntax of the grammar definition. One of `lark` or `regex`. - The agent that produced this item. + - `"lark"` - - `agent_name: string` + - `"regex"` - The canonical name of the agent that produced this item. + - `type: "grammar"` - - `program_output: object { id, call_id, result, 3 more }` + Grammar format. Always `grammar`. - - `id: string` + - `beta_namespace_tool: object { description, name, tools, type }` - The unique ID of the program output item. + Groups function/custom tools under a shared namespace. - - `call_id: string` + - `description: string` - The call ID of the program item. + A description of the namespace shown to the model. - - `result: string` + - `name: string` - The result produced by the program item. + The namespace name used in tool calls (for example, `crm`). - - `status: "completed" or "incomplete"` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - The terminal status of the program output item. + The function/custom tools available inside this namespace. - - `"completed"` + - `function: object { name, type, allowed_callers, 5 more }` - - `"incomplete"` + - `name: string` - - `type: "program_output"` + - `type: "function"` - The type of the item. Always `program_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `defer_loading: optional boolean` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + Whether this function should be deferred and discovered via tool search. - - `id: string` + - `description: optional string` - The unique ID of the tool search call item. + - `output_schema: optional map[unknown]` - - `arguments: unknown` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Arguments used for the tool search call. + - `parameters: optional unknown` - - `call_id: string` + - `strict: optional boolean` - The unique ID of the tool search call generated by the model. + 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. - - `execution: "server" or "client"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Whether tool search was executed by the server or by the client. + 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) - - `"server"` + - `name: string` - - `"client"` + The name of the custom tool, used to identify it in tool calls. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "custom"` - The status of the tool search call item that was recorded. + The type of the custom tool. Always `custom`. - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `defer_loading: optional boolean` - - `type: "tool_search_call"` + Whether this tool should be deferred and discovered via tool search. - The type of the item. Always `tool_search_call`. + - `description: optional string` - - `agent: optional object { agent_name }` + Optional description of the custom tool, used to provide more context. - The agent that produced this item. + - `format: optional object { type } or object { definition, syntax, type }` - - `agent_name: string` + The input format for the custom tool. Default is unconstrained text. - The canonical name of the agent that produced this item. + - `type: "namespace"` - - `created_by: optional string` + The type of the tool. Always `namespace`. - The identifier of the actor that created the item. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + Hosted or BYOT tool search configuration for deferred tools. - - `id: string` + - `type: "tool_search"` - The unique ID of the tool search output item. + The type of the tool. Always `tool_search`. - - `call_id: string` + - `description: optional string` - The unique ID of the tool search call generated by the model. + Description shown to the model for a client-executed tool search tool. - - `execution: "server" or "client"` + - `execution: optional "server" or "client"` - Whether tool search was executed by the server or by the client. + Whether tool search is executed by the server or by the client. - `"server"` - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` + - `parameters: optional unknown` - The status of the tool search output item that was recorded. + Parameter schema for a client-executed tool search tool. - - `"in_progress"` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"completed"` + 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). - - `"incomplete"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `tools: array of BetaTool` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The loaded tool definitions returned by tool search. + - `"web_search_preview"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `"web_search_preview_2025_03_11"` - 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). + - `search_content_types: optional array of "text" or "image"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `"text"` - 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). + - `"image"` - - `beta_computer_tool: object { type }` + - `search_context_size: optional "low" or "medium" or "high"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `"low"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"medium"` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `"high"` - 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). + - `user_location: optional object { type, city, country, 2 more }` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The user's location. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "approximate"` - - `code_interpreter: object { container, type, allowed_callers }` + The type of location approximation. Always `approximate`. - A tool that runs Python code to help generate a response to a prompt. + - `city: optional string` - - `programmatic_tool_calling: object { type }` + Free text input for the city of the user, e.g. `San Francisco`. - - `image_generation: object { type, action, background, 9 more }` + - `country: optional string` - A tool that generates images using the GPT image models. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `local_shell: object { type }` + - `region: optional string` - A tool that allows the model to execute shell commands in a local environment. + Free text input for the region of the user, e.g. `California`. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `timezone: optional string` - A tool that allows the model to execute shell commands. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - 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) + Allows the assistant to create, delete, or update files using unified diffs. - - `beta_namespace_tool: object { description, name, tools, type }` + - `type: "apply_patch"` - Groups function/custom tools under a shared namespace. + The type of the tool. Always `apply_patch`. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Hosted or BYOT tool search configuration for deferred tools. + The tool invocation context(s). - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `"direct"` - 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). + - `"programmatic"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `type: "tool_search_output"` - Allows the assistant to create, delete, or update files using unified diffs. + The item type. Always `tool_search_output`. - - `type: "tool_search_output"` + - `id: optional string` - The type of the item. Always `tool_search_output`. + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -68251,39 +79255,37 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `call_id: optional string` - - `additional_tools: object { id, role, tools, 2 more }` + The unique ID of the tool search call generated by the model. - - `id: string` + - `execution: optional "server" or "client"` - The unique ID of the additional tools item. + Whether tool search was executed by the server or by the client. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"server"` - The role that provided the additional tools. + - `"client"` - - `"unknown"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"user"` + The status of the tool search output. - - `"assistant"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"critic"` + - `"incomplete"` - - `"discriminator"` + - `additional_tools: object { role, tools, type, 2 more }` - - `"developer"` + - `role: "developer"` - - `"tool"` + The role that provided the additional tools. Only `developer` is supported. - `tools: array of BetaTool` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -68351,7 +79353,11 @@ openai beta:responses compact \ - `type: "additional_tools"` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -68361,22 +79367,85 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` - The unique ID of the compaction item. + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: string` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `type: "compaction"` The type of the item. Always `compaction`. + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -68385,10 +79454,6 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -68446,10 +79511,44 @@ openai beta:responses compact \ The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + - `type: "code_interpreter_call"` The type of the code interpreter tool call. Always `code_interpreter_call`. @@ -68458,6 +79557,10 @@ openai beta:responses compact \ The agent that produced this item. + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `local_shell_call: object { id, action, call_id, 3 more }` A tool call to run a command on the local shell. @@ -68554,13 +79657,9 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: string` + - `shell_call: object { action, call_id, type, 5 more }` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - `action: object { commands, max_output_length, timeout_ms }` @@ -68568,54 +79667,28 @@ openai beta:responses compact \ - `commands: array of string` - - `max_output_length: number` + Ordered shell commands for the execution environment to run. - Optional maximum number of characters to return from each command. + - `max_output_length: optional number` - - `timeout_ms: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Optional timeout in milliseconds for the commands. + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `beta_response_local_environment: object { type }` - - Represents the use of a local environment to perform shell actions. - - - `type: "local"` - - The environment type. Always `local`. - - - `beta_response_container_reference: object { container_id, type }` - - Represents a container created with /v1/containers. - - - `container_id: string` - - - `type: "container_reference"` - - The environment type. Always `container_reference`. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: "shell_call"` The type of the item. Always `shell_call`. + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -68638,33 +79711,41 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The ID of the entity that created this tool call. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + The environment to execute the shell commands in. - The output of a shell tool call that was emitted. + - `beta_local_environment: object { type, skills }` - - `id: string` + - `beta_container_reference: object { container_id, type }` - The unique ID of the shell call output. Populated when this item is returned via API. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `call_id: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the shell tool call generated by the model. + - `"in_progress"` - - `max_output_length: number` + - `"completed"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"incomplete"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `shell_call_output: object { call_id, output, type, 5 more }` - An array of shell call output contents + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. - `outcome: object { type } or object { exit_code, type }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `timeout: object { type }` @@ -68676,7 +79757,7 @@ openai beta:responses compact \ - `exit_code: number` - Exit code from the shell process. + The exit code returned by the shell process. - `type: "exit"` @@ -68684,29 +79765,19 @@ openai beta:responses compact \ - `stderr: string` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: string` - The standard output that was captured. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` + Captured stdout output for the shell call. - - `"completed"` + - `type: "shell_call_output"` - - `"incomplete"` + The type of the item. Always `shell_call_output`. - - `type: "shell_call_output"` + - `id: optional string` - The type of the shell call output. Always `shell_call_output`. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -68730,17 +79801,25 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` + The caller type. Always `program`. - The identifier of the actor that created the item. + - `max_output_length: optional number` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + The maximum number of UTF-8 characters captured for this shell call's combined output. - A tool call that applies file diffs by creating, deleting, or updating files. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the shell call output. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` @@ -68748,51 +79827,51 @@ openai beta:responses compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `create_file: object { diff, path, type }` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply when creating the file. - `path: string` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: "create_file"` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `delete_file: object { path, type }` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: string` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: "delete_file"` - Delete the specified file. + The operation type. Always `delete_file`. - `update_file: object { diff, path, type }` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply to the existing file. - `path: string` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: "update_file"` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `status: "in_progress" or "completed"` @@ -68806,6 +79885,10 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call`. + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -68828,17 +79911,11 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` - - The ID of the entity that created this tool call. - - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - The output emitted by an apply patch tool call. + The caller type. Always `program`. - - `id: string` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. - `call_id: string` @@ -68856,6 +79933,10 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call_output`. + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -68878,13 +79959,123 @@ openai beta:responses compact \ - `type: "program"` - - `created_by: optional string` - - The ID of the entity that created this tool call output. + The caller type. Always `program`. - `output: optional string` - Optional textual output returned by the apply patch tool. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `mcp_approval_request: object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. - `mcp_call: object { id, arguments, name, 7 more }` @@ -68945,1052 +80136,1360 @@ openai beta:responses compact \ - `"failed"` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - A list of tools available on an MCP server. + The output of a custom tool call from your code, being sent back to the model. - - `id: string` + - `call_id: string` - The unique ID of the list. + The call ID, used to map this custom tool call output to a custom tool call. - - `server_label: string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The label of the MCP server. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `tools: array of object { input_schema, name, annotations, description }` + - `string output: string` - The tools available on the server. + A string of the output of the custom tool call. - - `input_schema: unknown` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The JSON schema describing the tool's input. + Text, image, or file output of the custom tool call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. - `name: string` - The name of the tool. + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `compaction_trigger: object { type, agent }` + + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `item_reference: object { id, agent, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Input Audio + +- `beta_response_input_audio: object { input_audio, type }` + + An audio input to the model. + + - `input_audio: object { data, format }` + + - `data: string` + + Base64-encoded audio data. + + - `format: "mp3" or "wav"` + + The format of the audio data. Currently supported formats are `mp3` and + `wav`. + + - `"mp3"` + + - `"wav"` + + - `type: "input_audio"` + + The type of the input item. Always `input_audio`. + +### Beta Response Input Content + +- `beta_response_input_content: BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + A text input to the model. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. - - `annotations: optional unknown` + - `prompt_cache_breakpoint: optional object { mode }` - Additional annotations about the tool. + 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. - - `description: optional string` + - `mode: "explicit"` - The description of the tool. + The breakpoint mode. Always `explicit`. - - `type: "mcp_list_tools"` +### Beta Response Input File - The type of the item. Always `mcp_list_tools`. +- `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `agent: optional object { agent_name }` + A file input to the model. - The agent that produced this item. + - `type: "input_file"` - - `agent_name: string` + The type of the input item. Always `input_file`. - The canonical name of the agent that produced this item. + - `detail: optional "auto" or "low" or "high"` - - `error: optional string` + 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`. - Error message if the server could not list tools. + - `"auto"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `"low"` - A request for human approval of a tool invocation. + - `"high"` - - `id: string` + - `file_data: optional string` - The unique ID of the approval request. + The content of the file to be sent to the model. - - `arguments: string` + - `file_id: optional string` - A JSON string of arguments for the tool. + The ID of the file to be sent to the model. - - `name: string` + - `file_url: optional string` - The name of the tool to run. + The URL of the file to be sent to the model. - - `server_label: string` + - `filename: optional string` - The label of the MCP server making the request. + The name of the file to be sent to the model. - - `type: "mcp_approval_request"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the item. Always `mcp_approval_request`. + 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. - - `agent: optional object { agent_name }` + - `mode: "explicit"` - The agent that produced this item. + The breakpoint mode. Always `explicit`. - - `agent_name: string` +### Beta Response Input File Content - The canonical name of the agent that produced this item. +- `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + A file input to the model. - A response to an MCP approval request. + - `type: "input_file"` - - `id: string` + The type of the input item. Always `input_file`. - The unique ID of the approval response + - `detail: optional "auto" or "low" or "high"` - - `approval_request_id: string` + 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`. - The ID of the approval request being answered. + - `"auto"` - - `approve: boolean` + - `"low"` - Whether the request was approved. + - `"high"` - - `type: "mcp_approval_response"` + - `file_data: optional string` - The type of the item. Always `mcp_approval_response`. + The base64-encoded data of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `file_id: optional string` - The agent that produced this item. + The ID of the file to be sent to the model. - - `agent_name: string` + - `file_url: optional string` - The canonical name of the agent that produced this item. + The URL of the file to be sent to the model. - - `reason: optional string` + - `filename: optional string` - Optional reason for the decision. + The name of the file to be sent to the model. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `prompt_cache_breakpoint: optional object { mode }` - A call to a custom tool created by the model. + 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. - - `call_id: string` + - `mode: "explicit"` - An identifier used to map this custom tool call to a tool call output. + The breakpoint mode. Always `explicit`. - - `input: string` +### Beta Response Input Image - The input for the custom tool call generated by the model. +- `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `name: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The name of the custom tool being called. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "custom_tool_call"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of the custom tool call. Always `custom_tool_call`. + - `"low"` - - `id: optional string` + - `"high"` - The unique ID of the custom tool call in the OpenAI platform. + - `"auto"` - - `agent: optional object { agent_name }` + - `"original"` - The agent that produced this item. + - `type: "input_image"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the input item. Always `input_image`. - The execution context that produced this tool call. + - `file_id: optional string` - - `namespace: optional string` + The ID of the file to be sent to the model. - The namespace of the custom tool being called. + - `image_url: optional string` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The output of a custom tool call from your code, being sent back to the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `id: string` + 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. - The unique ID of the custom tool call output item. + - `mode: "explicit"` - - `status: "in_progress" or "completed" or "incomplete"` + The breakpoint mode. Always `explicit`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +### Beta Response Input Image Content - - `"in_progress"` +- `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `"completed"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"incomplete"` + - `type: "input_image"` - - `created_by: optional string` + The type of the input item. Always `input_image`. - The identifier of the actor that created the item. + - `detail: optional "low" or "high" or "auto" or "original"` - - `parallel_tool_calls: boolean` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Whether to allow the model to run tool calls in parallel. + - `"low"` - - `temperature: number` + - `"high"` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `"auto"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"original"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `file_id: optional string` - - `beta_tool_choice_options: "none" or "auto" or "required"` + The ID of the file to be sent to the model. - Controls which (if any) tool is called by the model. + - `image_url: optional string` - `none` means the model will not call any tool and instead generates a message. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `prompt_cache_breakpoint: optional object { mode }` - `required` means the model must call one or more tools. + 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. - - `"none"` + - `mode: "explicit"` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `"required"` +### Beta Response Input Item - - `beta_tool_choice_allowed: object { mode, tools, type }` +- `beta_response_input_item: BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - Constrains the tools available to the model to a pre-defined set. + 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. - - `mode: "auto" or "required"` + - `beta_easy_input_message: object { content, role, phase, type }` - Constrains the tools available to the model to a pre-defined set. + 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. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `content: string or BetaResponseInputMessageContentList` - `required` requires the model to call one or more of the allowed tools. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"auto"` + - `Text input: string` - - `"required"` + A text input to the model. - - `tools: array of map[unknown]` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - A list of tool definitions that the model should be allowed to call. + A list of one or many input items to the model, containing different content + types. - For the Responses API, the list of tool definitions might look like: + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + A text input to the model. - - `type: "allowed_tools"` + - `text: string` - Allowed tool configuration type. Always `allowed_tools`. + The text input to the model. - - `beta_tool_choice_types: object { type }` + - `type: "input_text"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + The type of the input item. Always `input_text`. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `prompt_cache_breakpoint: optional object { mode }` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + 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. - Allowed values are: + - `mode: "explicit"` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The breakpoint mode. Always `explicit`. - - `"file_search"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"web_search_preview"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"computer"` + - `detail: "low" or "high" or "auto" or "original"` - - `"computer_use_preview"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"computer_use"` + - `"low"` - - `"web_search_preview_2025_03_11"` + - `"high"` - - `"image_generation"` + - `"auto"` - - `"code_interpreter"` + - `"original"` - - `beta_tool_choice_function: object { name, type }` + - `type: "input_image"` - Use this option to force the model to call a specific function. + The type of the input item. Always `input_image`. - - `name: string` + - `file_id: optional string` - The name of the function to call. + The ID of the file to be sent to the model. - - `type: "function"` + - `image_url: optional string` - For function calling, the type is always `function`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `beta_tool_choice_mcp: object { server_label, type, name }` + - `prompt_cache_breakpoint: optional object { mode }` - Use this option to force the model to call a specific tool on a remote MCP server. + 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. - - `server_label: string` + - `mode: "explicit"` - The label of the MCP server to use. + The breakpoint mode. Always `explicit`. - - `type: "mcp"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - For MCP tools, the type is always `mcp`. + A file input to the model. - - `name: optional string` + - `type: "input_file"` - The name of the tool to call on the server. + The type of the input item. Always `input_file`. - - `beta_tool_choice_custom: object { name, type }` + - `detail: optional "auto" or "low" or "high"` - Use this option to force the model to call a specific custom tool. + 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`. - - `name: string` + - `"auto"` - The name of the custom tool to call. + - `"low"` - - `type: "custom"` + - `"high"` - For custom tool calling, the type is always `custom`. + - `file_data: optional string` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + The content of the file to be sent to the model. - - `beta_tool_choice_apply_patch: object { type }` + - `file_id: optional string` - Forces the model to call the apply_patch tool when executing a tool call. + The ID of the file to be sent to the model. - - `type: "apply_patch"` + - `file_url: optional string` - The tool to call. Always `apply_patch`. + The URL of the file to be sent to the model. - - `beta_tool_choice_shell: object { type }` + - `filename: optional string` - Forces the model to call the shell tool when a tool call is required. + The name of the file to be sent to the model. - - `type: "shell"` + - `prompt_cache_breakpoint: optional object { mode }` - The tool to call. Always `shell`. + 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. - - `tools: array of BetaTool` + - `mode: "explicit"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The breakpoint mode. Always `explicit`. - We support the following categories of tools: + - `role: "user" or "assistant" or "system" or "developer"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `"user"` - 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). + - `"assistant"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `"system"` - 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). + - `"developer"` - - `beta_computer_tool: object { type }` + - `phase: optional "commentary" or "final_answer"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `"commentary"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"final_answer"` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `type: optional "message"` - 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). + The type of the message input. Always `message`. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `"message"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `message: object { content, role, agent, 2 more }` - - `code_interpreter: object { container, type, allowed_callers }` + 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. - A tool that runs Python code to help generate a response to a prompt. + - `content: array of BetaResponseInputContent` - - `programmatic_tool_calling: object { type }` + A list of one or many input items to the model, containing different content + types. - - `image_generation: object { type, action, background, 9 more }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - A tool that generates images using the GPT image models. + A text input to the model. - - `local_shell: object { type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - A tool that allows the model to execute shell commands in a local environment. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - A tool that allows the model to execute shell commands. + A file input to the model. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `role: "user" or "system" or "developer"` - 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) + The role of the message input. One of `user`, `system`, or `developer`. - - `beta_namespace_tool: object { description, name, tools, type }` + - `"user"` - Groups function/custom tools under a shared namespace. + - `"system"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `"developer"` - Hosted or BYOT tool search configuration for deferred tools. + - `agent: optional object { agent_name }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The agent that produced this item. - 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). + - `agent_name: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The canonical name of the agent that produced this item. - Allows the assistant to create, delete, or update files using unified diffs. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `top_p: number` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `"in_progress"` - We generally recommend altering this or `temperature` but not both. + - `"completed"` - - `background: optional boolean` + - `"incomplete"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `type: optional "message"` - - `completed_at: optional number` + The type of the message input. Always set to `message`. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `"message"` - - `conversation: optional object { id }` + - `beta_response_output_message: object { id, content, role, 4 more }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + An output message from the model. - `id: string` - The unique ID of the conversation that this response was associated with. - - - `max_output_tokens: optional number` + The unique ID of the output message. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `max_tool_calls: optional number` + The content of the output message. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `moderation: optional object { input, output }` + A text output from the model. - Moderation results for the response input and output, if moderated completions were requested. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The annotations of the text output. - Moderation for the response input. + - `file_citation: object { file_id, filename, index, type }` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + A citation to a file. - A moderation result produced for the response input or output. + - `file_id: string` - - `categories: map[boolean]` + The ID of the file. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `filename: string` - - `category_applied_input_types: map[array of "text" or "image"]` + The filename of the file cited. - Which modalities of input are reflected by the score for each category. + - `index: number` - - `"text"` + The index of the file in the list of files. - - `"image"` + - `type: "file_citation"` - - `category_scores: map[number]` + The type of the file citation. Always `file_citation`. - A dictionary of moderation categories to scores. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `flagged: boolean` + A citation for a web resource used to generate a model response. - A boolean indicating whether the content was flagged by any category. + - `end_index: number` - - `model: string` + The index of the last character of the URL citation in the message. - The moderation model that produced this result. + - `start_index: number` - - `type: "moderation_result"` + The index of the first character of the URL citation in the message. - The object type, which was always `moderation_result` for successful moderation results. + - `title: string` - - `error: object { code, message, type }` + The title of the web resource. - An error produced while attempting moderation for the response input or output. + - `type: "url_citation"` - - `code: string` + The type of the URL citation. Always `url_citation`. - The error code. + - `url: string` - - `message: string` + The URL of the web resource. - The error message. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `type: "error"` + A citation for a container file used to generate a model response. - The object type, which was always `error` for moderation failures. + - `container_id: string` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The ID of the container file. - Moderation for the response output. + - `end_index: number` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + The index of the last character of the container file citation in the message. - A moderation result produced for the response input or output. + - `file_id: string` - - `categories: map[boolean]` + The ID of the file. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `filename: string` - - `category_applied_input_types: map[array of "text" or "image"]` + The filename of the container file cited. - Which modalities of input are reflected by the score for each category. + - `start_index: number` - - `"text"` + The index of the first character of the container file citation in the message. - - `"image"` + - `type: "container_file_citation"` - - `category_scores: map[number]` + The type of the container file citation. Always `container_file_citation`. - A dictionary of moderation categories to scores. + - `file_path: object { file_id, index, type }` - - `flagged: boolean` + A path to a file. - A boolean indicating whether the content was flagged by any category. + - `file_id: string` - - `model: string` + The ID of the file. - The moderation model that produced this result. + - `index: number` - - `type: "moderation_result"` + The index of the file in the list of files. - The object type, which was always `moderation_result` for successful moderation results. + - `type: "file_path"` - - `error: object { code, message, type }` + The type of the file path. Always `file_path`. - An error produced while attempting moderation for the response input or output. + - `text: string` - - `code: string` + The text output from the model. - The error code. + - `type: "output_text"` - - `message: string` + The type of the output text. Always `output_text`. - The error message. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "error"` + - `token: string` - The object type, which was always `error` for moderation failures. + - `bytes: array of number` - - `previous_response_id: optional string` + - `logprob: number` - 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`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `prompt: optional object { id, variables, version }` + - `token: string` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `bytes: array of number` - - `id: string` + - `logprob: number` - The unique identifier of the prompt template to use. + - `beta_response_output_refusal: object { refusal, type }` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + A refusal from the model. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `refusal: string` - - `union_member_0: string` + The refusal explanation from the model. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `type: "refusal"` - A text input to the model. + The type of the refusal. Always `refusal`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `role: "assistant"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The role of the output message. Always `assistant`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `status: "in_progress" or "completed" or "incomplete"` - A file input to the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `version: optional string` + - `"in_progress"` - Optional version of the prompt template. + - `"completed"` - - `prompt_cache_key: optional string` + - `"incomplete"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `type: "message"` - - `prompt_cache_options: optional object { mode, ttl }` + The type of the output message. Always `message`. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `agent: optional object { agent_name }` - - `mode: "implicit" or "explicit"` + The agent that produced this item. - Whether implicit prompt-cache breakpoints were enabled. + - `agent_name: string` - - `"implicit"` + The canonical name of the agent that produced this item. - - `"explicit"` + - `phase: optional "commentary" or "final_answer"` - - `ttl: "30m"` + 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. - The minimum lifetime applied to each cache breakpoint. + - `"commentary"` - - `"30m"` + - `"final_answer"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - Deprecated. Use `prompt_cache_options.ttl` instead. + 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. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `id: string` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The unique ID of the file search tool call. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `queries: array of string` - - `"in_memory"` + The queries used to search for files. - - `"24h"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - **gpt-5 and o-series models only** + - `"in_progress"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"searching"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `"completed"` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"incomplete"` - - `"auto"` + - `"failed"` - - `"current_turn"` + - `type: "file_search_call"` - - `"all_turns"` + The type of the file search tool call. Always `file_search_call`. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `agent: optional object { agent_name }` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The agent that produced this item. - - `"none"` + - `agent_name: string` - - `"minimal"` + The canonical name of the agent that produced this item. - - `"low"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"medium"` + The results of the file search tool call. - - `"high"` + - `attributes: optional map[string or number or boolean]` - - `"xhigh"` + 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. - - `"max"` + - `union_member_0: string` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `union_member_1: number` - **Deprecated:** use `summary` instead. + - `union_member_2: boolean` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `file_id: optional string` - - `"auto"` + The unique ID of the file. - - `"concise"` + - `filename: optional string` - - `"detailed"` + The name of the file. - - `mode: optional string or "standard" or "pro"` + - `score: optional number` - Controls the reasoning execution mode for the request. + The relevance score of the file - a value between 0 and 1. - When returned on a response, this is the effective execution mode. + - `text: optional string` - - `"standard"` + The text that was retrieved from the file. - - `"pro"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `summary: optional "auto" or "concise" or "detailed"` + 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. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `id: string` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The unique ID of the computer call. - - `"auto"` + - `call_id: string` - - `"concise"` + An identifier used when responding to the tool call with output. - - `"detailed"` + - `pending_safety_checks: array of object { id, code, message }` - - `safety_identifier: optional string` + The pending safety checks for the computer call. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `id: string` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The ID of the pending safety check. - Specifies the processing type used for serving the request. + - `code: optional string` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The type of the pending safety check. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `message: optional string` - - `"auto"` + Details about the pending safety check. - - `"default"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"flex"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"scale"` + - `"in_progress"` - - `"priority"` + - `"completed"` - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `"incomplete"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `type: "computer_call"` - - `"completed"` + The type of the computer call. Always `computer_call`. - - `"failed"` + - `"computer_call"` - - `"in_progress"` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `"cancelled"` + A click action. - - `"queued"` + - `click: object { button, type, x, 2 more }` - - `"incomplete"` + A click action. - - `text: optional object { format, verbosity }` + - `button: "left" or "right" or "wheel" or 2 more` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"left"` - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `"right"` - An object specifying the format that the model must output. + - `"wheel"` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `"back"` - The default format is `{ "type": "text" }` with no additional options. + - `"forward"` - **Not recommended for gpt-4o and newer models:** + - `type: "click"` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + Specifies the event type. For a click action, this property is always `click`. - - `text: object { type }` + - `x: number` - Default response format. Used to generate text responses. + The x-coordinate where the click occurred. - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + - `y: number` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The y-coordinate where the click occurred. - - `name: string` + - `keys: optional array of string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The keys being held while clicking. - - `schema: map[unknown]` + - `double_click: object { keys, type, x, y }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A double click action. - - `type: "json_schema"` + - `keys: array of string` - The type of response format being defined. Always `json_schema`. + The keys being held while double-clicking. - - `description: optional string` + - `type: "double_click"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `strict: optional boolean` + - `x: number` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The x-coordinate where the double click occurred. - - `json_object: object { type }` + - `y: number` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The y-coordinate where the double click occurred. - - `verbosity: optional "low" or "medium" or "high"` + - `drag: object { path, type, keys }` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + A drag action. - - `"low"` + - `path: array of object { x, y }` - - `"medium"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"high"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `top_logprobs: optional number` + - `x: number` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The x-coordinate. - - `truncation: optional "auto" or "disabled"` + - `y: number` - The truncation strategy to use for the model response. + The y-coordinate. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `type: "drag"` - - `"auto"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"disabled"` + - `keys: optional array of string` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + The keys being held while dragging the mouse. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `keypress: object { keys, type }` - - `input_tokens: number` + A collection of keypresses the model would like to perform. - The number of input tokens. + - `keys: array of string` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A detailed breakdown of the input tokens. + - `type: "keypress"` - - `cache_write_tokens: number` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The number of input tokens that were written to the cache. + - `move: object { type, x, y, keys }` - - `cached_tokens: number` + A mouse move action. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `type: "move"` - - `output_tokens: number` + Specifies the event type. For a move action, this property is always set to `move`. - The number of output tokens. + - `x: number` - - `output_tokens_details: object { reasoning_tokens }` + The x-coordinate to move to. - A detailed breakdown of the output tokens. + - `y: number` - - `reasoning_tokens: number` + The y-coordinate to move to. - The number of reasoning tokens. + - `keys: optional array of string` - - `total_tokens: number` + The keys being held while moving the mouse. - The total number of tokens used. + - `screenshot: object { type }` - - `user: optional string` + A screenshot action. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `sequence_number: number` + A scroll action. - The sequence number of this event. + - `scroll_x: number` - - `type: "response.failed"` + The horizontal scroll distance. - The type of the event. Always `response.failed`. + - `scroll_y: number` - - `agent: optional object { agent_name }` + The vertical scroll distance. - The agent that owns this multi-agent streaming event. + - `type: "scroll"` - - `agent_name: string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The canonical name of the agent that produced this item. + - `x: number` -### Beta Response File Search Call Completed Event + The x-coordinate where the scroll occurred. -- `beta_response_file_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `y: number` - Emitted when a file search call is completed (results found). + The y-coordinate where the scroll occurred. - - `item_id: string` + - `keys: optional array of string` - The ID of the output item that the file search call is initiated. + The keys being held while scrolling. - - `output_index: number` + - `type: object { text, type }` - The index of the output item that the file search call is initiated. + An action to type in text. - - `sequence_number: number` + - `text: string` - The sequence number of this event. + The text to type. - - `type: "response.file_search_call.completed"` + - `type: "type"` - The type of the event. Always `response.file_search_call.completed`. + Specifies the event type. For a type action, this property is always set to `type`. - - `agent: optional object { agent_name }` + - `wait: object { type }` - The agent that owns this multi-agent streaming event. + A wait action. - - `agent_name: string` + - `actions: optional array of BetaComputerAction` - The canonical name of the agent that produced this item. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. -### Beta Response File Search Call In Progress Event + - `click: object { button, type, x, 2 more }` -- `beta_response_file_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + A click action. - Emitted when a file search call is initiated. + - `double_click: object { keys, type, x, y }` - - `item_id: string` + A double click action. - The ID of the output item that the file search call is initiated. + - `drag: object { path, type, keys }` - - `output_index: number` + A drag action. - The index of the output item that the file search call is initiated. + - `keypress: object { keys, type }` - - `sequence_number: number` + A collection of keypresses the model would like to perform. - The sequence number of this event. + - `move: object { type, x, y, keys }` - - `type: "response.file_search_call.in_progress"` + A mouse move action. - The type of the event. Always `response.file_search_call.in_progress`. + - `screenshot: object { type }` - - `agent: optional object { agent_name }` + A screenshot action. - The agent that owns this multi-agent streaming event. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `agent_name: string` + A scroll action. - The canonical name of the agent that produced this item. + - `type: object { text, type }` -### Beta Response File Search Call Searching Event + An action to type in text. -- `beta_response_file_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` + - `wait: object { type }` - Emitted when a file search is currently searching. + A wait action. - - `item_id: string` + - `agent: optional object { agent_name }` - The ID of the output item that the file search call is initiated. + The agent that produced this item. - - `output_index: number` + - `agent_name: string` - The index of the output item that the file search call is searching. + The canonical name of the agent that produced this item. - - `sequence_number: number` + - `computer_call_output: object { call_id, output, type, 4 more }` - The sequence number of this event. + The output of a computer tool call. - - `type: "response.file_search_call.searching"` + - `call_id: string` - The type of the event. Always `response.file_search_call.searching`. + The ID of the computer tool call that produced the output. - - `agent: optional object { agent_name }` + - `output: object { type, file_id, image_url }` - The agent that owns this multi-agent streaming event. + A computer screenshot image used with the computer use tool. - - `agent_name: string` + - `type: "computer_screenshot"` - The canonical name of the agent that produced this item. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. -### Beta Response File Search Tool Call + - `file_id: optional string` -- `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + The identifier of an uploaded file that contains the screenshot. - 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. + - `image_url: optional string` - - `id: string` + The URL of the screenshot image. - The unique ID of the file search tool call. + - `type: "computer_call_output"` - - `queries: array of string` + The type of the computer tool call output. Always `computer_call_output`. - The queries used to search for files. + - `id: optional string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The ID of the computer tool call output. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"in_progress"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"searching"` + - `id: string` - - `"completed"` + The ID of the pending safety check. - - `"incomplete"` + - `code: optional string` - - `"failed"` + The type of the pending safety check. - - `type: "file_search_call"` + - `message: optional string` - The type of the file search tool call. Always `file_search_call`. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -70000,210 +81499,191 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `attributes: optional map[string or number or boolean]` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - 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. + - `"in_progress"` - - `union_member_0: string` + - `"completed"` - - `union_member_1: number` + - `"incomplete"` - - `union_member_2: boolean` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `file_id: optional string` + 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. - The unique ID of the file. + - `id: string` - - `filename: optional string` + The unique ID of the web search tool call. - The name of the file. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `score: optional number` + 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). - The relevance score of the file - a value between 0 and 1. + - `search: object { type, queries, query, sources }` - - `text: optional string` + Action type "search" - Performs a web search query. - The text that was retrieved from the file. + - `type: "search"` -### Beta Response Format Text Config + The action type. -- `beta_response_format_text_config: object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `queries: optional array of string` - An object specifying the format that the model must output. + The search queries. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `query: optional string` - The default format is `{ "type": "text" }` with no additional options. + The search query. - **Not recommended for gpt-4o and newer models:** + - `sources: optional array of object { type, url }` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The sources used in the search. - - `text: object { type }` + - `type: "url"` - Default response format. Used to generate text responses. + The type of source. Always `url`. - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + - `url: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The URL of the source. - - `name: string` + - `open_page: object { type, url }` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + Action type "open_page" - Opens a specific URL from search results. - - `schema: map[unknown]` + - `type: "open_page"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The action type. - - `type: "json_schema"` + - `url: optional string` - The type of response format being defined. Always `json_schema`. + The URL opened by the model. - - `description: optional string` + - `find_in_page: object { pattern, type, url }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `strict: optional boolean` + - `pattern: string` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The pattern or text to search for within the page. - - `json_object: object { type }` + - `type: "find_in_page"` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The action type. -### Beta Response Format Text JSON Schema Config + - `url: string` -- `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + The URL of the page searched for the pattern. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `name: string` + The status of the web search tool call. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `"in_progress"` - - `schema: map[unknown]` + - `"searching"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"completed"` - - `type: "json_schema"` + - `"failed"` - The type of response format being defined. Always `json_schema`. + - `type: "web_search_call"` - - `description: optional string` + The type of the web search tool call. Always `web_search_call`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `agent: optional object { agent_name }` - - `strict: optional boolean` + The agent that produced this item. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `agent_name: string` -### Beta Response Function Call Arguments Delta Event + The canonical name of the agent that produced this item. -- `beta_response_function_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - Emitted when there is a partial function-call arguments delta. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `delta: string` + - `arguments: string` - The function-call arguments delta that is added. + A JSON string of the arguments to pass to the function. - - `item_id: string` + - `call_id: string` - The ID of the output item that the function-call arguments delta is added to. + The unique ID of the function tool call generated by the model. - - `output_index: number` + - `name: string` - The index of the output item that the function-call arguments delta is added to. + The name of the function to run. - - `sequence_number: number` + - `type: "function_call"` - The sequence number of this event. + The type of the function tool call. Always `function_call`. - - `type: "response.function_call_arguments.delta"` + - `id: optional string` - The type of the event. Always `response.function_call_arguments.delta`. + The unique ID of the function tool call. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Function Call Arguments Done Event + - `caller: optional object { type } or object { caller_id, type }` -- `beta_response_function_call_arguments_done_event: object { arguments, item_id, name, 4 more }` + The execution context that produced this tool call. - Emitted when function-call arguments are finalized. + - `direct: object { type }` - - `arguments: string` + - `program: object { caller_id, type }` - The function-call arguments. + - `caller_id: string` - - `item_id: string` + The call ID of the program item that produced this tool call. - The ID of the item. + - `type: "program"` - - `name: string` + - `namespace: optional string` - The name of the function that was called. + The namespace of the function to run. - - `output_index: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The index of the output item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `sequence_number: number` + - `"in_progress"` - The sequence number of this event. + - `"completed"` - - `type: "response.function_call_arguments.done"` + - `"incomplete"` - - `agent: optional object { agent_name }` + - `function_call_output: object { call_id, output, type, 4 more }` - The agent that owns this multi-agent streaming event. + The output of a function tool call. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + The unique ID of the function tool call generated by the model. -### Beta Response Function Call Output Item + - `output: string or BetaResponseFunctionCallOutputItemList` -- `beta_response_function_call_output_item: BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + Text, image, or file output of the function tool call. - A piece of message content, such as text, an image, or a file. + - `union_member_0: string` + + A JSON string of the output of the function tool call. + + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + + An array of content outputs (text, image, file) for the function tool call. - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` @@ -70303,301 +81783,307 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. -### Beta Response Function Call Output Item List - -- `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + - `type: "function_call_output"` - An array of content outputs (text, image, file) for the function tool call. + The type of the function tool call output. Always `function_call_output`. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `id: optional string` - A text input to the model. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `text: string` + - `agent: optional object { agent_name }` - The text input to the model. + The agent that produced this item. - - `type: "input_text"` + - `agent_name: string` - The type of the input item. Always `input_text`. + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - - `mode: "explicit"` + - `direct: object { type }` - The breakpoint mode. Always `explicit`. + - `program: object { caller_id, type }` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `caller_id: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The call ID of the program item that produced this tool call. - - `type: "input_image"` + - `type: "program"` - The type of the input item. Always `input_image`. + The caller type. Always `program`. - - `detail: optional "low" or "high" or "auto" or "original"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"low"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"original"` + - `agent_message: object { author, content, recipient, 3 more }` - - `file_id: optional string` + A message routed between agents. - The ID of the file to be sent to the model. + - `author: string` - - `image_url: optional string` + The sending agent identity. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `prompt_cache_breakpoint: optional object { mode }` + Plaintext, image, or encrypted content sent between agents. - 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. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `mode: "explicit"` + A text input to the model. - The breakpoint mode. Always `explicit`. + - `text: string` - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + The text input to the model. - A file input to the model. + - `type: "input_text"` - - `type: "input_file"` + The type of the input item. Always `input_text`. - The type of the input item. Always `input_file`. + - `prompt_cache_breakpoint: optional object { mode }` - - `detail: optional "auto" or "low" or "high"` + 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. - 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`. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `"auto"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `"low"` + - `type: "input_image"` - - `"high"` + The type of the input item. Always `input_image`. - - `file_data: optional string` + - `detail: optional "low" or "high" or "auto" or "original"` - The base64-encoded data of the file to be sent to the model. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `file_id: optional string` The ID of the file to be sent to the model. - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` + - `image_url: optional string` - The name of the file to be sent to the model. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `prompt_cache_breakpoint: optional object { mode }` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` + - `encrypted_content: object { encrypted_content, type }` - The breakpoint mode. Always `explicit`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. -### Beta Response Function Shell Call Output Content + - `encrypted_content: string` -- `beta_response_function_shell_call_output_content: object { outcome, stderr, stdout }` + Opaque encrypted content. - Captured stdout and stderr for a portion of a shell tool call output. + - `type: "encrypted_content"` - - `outcome: object { type } or object { exit_code, type }` + The type of the input item. Always `encrypted_content`. - The exit or timeout outcome associated with this shell call. + - `recipient: string` - - `timeout: object { type }` + The destination agent identity. - Indicates that the shell call exceeded its configured time limit. + - `type: "agent_message"` - - `exit: object { exit_code, type }` + The item type. Always `agent_message`. - Indicates that the shell commands finished and returned an exit code. + - `id: optional string` - - `exit_code: number` + The unique ID of this agent message item. - The exit code returned by the shell process. + - `agent: optional object { agent_name }` - - `type: "exit"` + The agent that produced this item. - The outcome type. Always `exit`. + - `agent_name: string` - - `stderr: string` + The canonical name of the agent that produced this item. - Captured stderr output for the shell call. + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - `stdout: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Captured stdout output for the shell call. + The multi-agent action that was executed. -### Beta Response Function Shell Tool Call + - `"spawn_agent"` -- `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `"interrupt_agent"` - A tool call that executes one or more shell commands in a managed environment. + - `"list_agents"` - - `id: string` + - `"send_message"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"followup_task"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"wait_agent"` - The shell commands and limits that describe how to run the tool call. + - `arguments: string` - - `commands: array of string` + The action arguments as a JSON string. - - `max_output_length: number` + - `call_id: string` - Optional maximum number of characters to return from each command. + The unique ID linking this call to its output. - - `timeout_ms: number` + - `type: "multi_agent_call"` - Optional timeout in milliseconds for the commands. + The item type. Always `multi_agent_call`. - - `call_id: string` + - `id: optional string` - The unique ID of the shell tool call generated by the model. + The unique ID of this multi-agent call. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `agent: optional object { agent_name }` - Represents the use of a local environment to perform shell actions. + The agent that produced this item. - - `beta_response_local_environment: object { type }` + - `agent_name: string` - Represents the use of a local environment to perform shell actions. + The canonical name of the agent that produced this item. - - `type: "local"` + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - The environment type. Always `local`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `beta_response_container_reference: object { container_id, type }` + The multi-agent action that produced this result. - Represents a container created with /v1/containers. + - `"spawn_agent"` - - `container_id: string` + - `"interrupt_agent"` - - `type: "container_reference"` + - `"list_agents"` - The environment type. Always `container_reference`. + - `"send_message"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"followup_task"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"wait_agent"` - - `"in_progress"` + - `call_id: string` - - `"completed"` + The unique ID of the multi-agent call. - - `"incomplete"` + - `output: array of object { text, type, annotations }` - - `type: "shell_call"` + Text output returned by the multi-agent action. - The type of the item. Always `shell_call`. + - `text: string` - - `agent: optional object { agent_name }` + The text content. - The agent that produced this item. + - `type: "output_text"` - - `agent_name: string` + The content type. Always `output_text`. - The canonical name of the agent that produced this item. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `caller: optional object { type } or object { caller_id, type }` + Citations associated with the text content. - The execution context that produced this tool call. + - `union_member_0: array of object { file_id, filename, index, type }` - - `direct: object { type }` + - `file_id: string` - - `program: object { caller_id, type }` + The ID of the file. - - `caller_id: string` + - `filename: string` - The call ID of the program item that produced this tool call. + The filename of the file cited. - - `type: "program"` + - `index: number` - - `created_by: optional string` + The index of the file in the list of files. - The ID of the entity that created this tool call. + - `type: "file_citation"` -### Beta Response Function Shell Tool Call Output + The citation type. Always `file_citation`. -- `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - The output of a shell tool call that was emitted. + - `end_index: number` - - `id: string` + The index of the last character of the citation in the message. - The unique ID of the shell call output. Populated when this item is returned via API. + - `start_index: number` - - `call_id: string` + The index of the first character of the citation in the message. - The unique ID of the shell tool call generated by the model. + - `title: string` - - `max_output_length: number` + The title of the cited resource. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `type: "url_citation"` - - `output: array of object { outcome, stderr, stdout, created_by }` + The citation type. Always `url_citation`. - An array of shell call output contents + - `url: string` - - `outcome: object { type } or object { exit_code, type }` + The URL of the cited resource. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `timeout: object { type }` + - `container_id: string` - Indicates that the shell call exceeded its configured time limit. + The ID of the container. - - `exit: object { exit_code, type }` + - `end_index: number` - Indicates that the shell commands finished and returned an exit code. + The index of the last character of the citation in the message. - - `exit_code: number` + - `file_id: string` - Exit code from the shell process. + The ID of the container file. - - `type: "exit"` + - `filename: string` - The outcome type. Always `exit`. + The filename of the container file cited. - - `stderr: string` + - `start_index: number` - The standard error output that was captured. + The index of the first character of the citation in the message. - - `stdout: string` + - `type: "container_file_citation"` - The standard output that was captured. + The citation type. Always `container_file_citation`. - - `created_by: optional string` + - `type: "multi_agent_call_output"` - The identifier of the actor that created the item. + The item type. Always `multi_agent_call_output`. - - `status: "in_progress" or "completed" or "incomplete"` + - `id: optional string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The unique ID of this multi-agent call output. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `"incomplete"` + - `agent_name: string` - - `type: "shell_call_output"` + The canonical name of the agent that produced this item. - The type of the shell call output. Always `shell_call_output`. + - `tool_search_call: object { arguments, type, id, 4 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `id: optional string` + + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -70607,1093 +82093,1103 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `call_id: optional string` - The execution context that produced this tool call. + The unique ID of the tool search call generated by the model. - - `direct: object { type }` + - `execution: optional "server" or "client"` - - `program: object { caller_id, type }` + Whether tool search was executed by the server or by the client. - - `caller_id: string` + - `"server"` - The call ID of the program item that produced this tool call. + - `"client"` - - `type: "program"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `created_by: optional string` + The status of the tool search call. - The identifier of the actor that created the item. + - `"in_progress"` -### Beta Response Function Tool Call + - `"completed"` -- `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `"incomplete"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `arguments: string` + - `tools: array of BetaTool` - A JSON string of the arguments to pass to the function. + The loaded tool definitions returned by the tool search output. - - `call_id: string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The unique ID of the function tool call generated by the model. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `name: string` - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `id: optional string` - - The unique ID of the function tool call. + The name of the function to call. - - `agent: optional object { agent_name }` + - `parameters: map[unknown]` - The agent that produced this item. + A JSON schema object describing the parameters of the function. - - `agent_name: string` + - `strict: boolean` - The canonical name of the agent that produced this item. + Whether strict parameter validation is enforced for this function tool. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "function"` - The execution context that produced this tool call. + The type of the function tool. Always `function`. - - `direct: object { type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `program: object { caller_id, type }` + The tool invocation context(s). - - `caller_id: string` + - `"direct"` - The call ID of the program item that produced this tool call. + - `"programmatic"` - - `type: "program"` + - `defer_loading: optional boolean` - - `namespace: optional string` + Whether this function is deferred and loaded via tool search. - The namespace of the function to run. + - `description: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + A description of the function. Used by the model to determine whether or not to call the function. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output_schema: optional map[unknown]` - - `"in_progress"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"completed"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"incomplete"` + 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). -### Beta Response Function Tool Call Item + - `type: "file_search"` -- `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` + The type of the file search tool. Always `file_search`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `vector_store_ids: array of string` - - `id: string` + The IDs of the vector stores to search. - The unique ID of the function tool call. + - `filters: optional object { key, type, value } or object { filters, type }` - - `status: "in_progress" or "completed" or "incomplete"` + A filter to apply. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Comparison Filter: object { key, type, value }` - - `"in_progress"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"completed"` + - `key: string` - - `"incomplete"` + The key to compare against the value. - - `created_by: optional string` + - `type: "eq" or "ne" or "gt" or 5 more` - The identifier of the actor that created the item. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. -### Beta Response Function Tool Call Output Item + - `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 -- `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `"eq"` - - `id: string` + - `"ne"` - The unique ID of the function call tool output. + - `"gt"` - - `call_id: string` + - `"gte"` - The unique ID of the function tool call generated by the model. + - `"lt"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"lte"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `"in"` - - `string output: string` + - `"nin"` - A string of the output of the function call. + - `value: string or number or boolean or array of string or number` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The value to compare against the attribute key; supports string, number, or boolean types. - Text, image, or file output of the function call. + - `union_member_0: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `union_member_1: number` - A text input to the model. + - `union_member_2: boolean` - - `text: string` + - `union_member_3: array of string or number` - The text input to the model. + - `union_member_0: string` - - `type: "input_text"` + - `union_member_1: number` - The type of the input item. Always `input_text`. + - `Compound Filter: object { filters, type }` - - `prompt_cache_breakpoint: optional object { mode }` + Combine multiple filters using `and` or `or`. - 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. + - `filters: array of object { key, type, value } or unknown` - - `mode: "explicit"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The breakpoint mode. Always `explicit`. + - `Comparison Filter: object { key, type, value }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `key: string` - - `detail: "low" or "high" or "auto" or "original"` + The key to compare against the value. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"low"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"high"` + - `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 - - `"auto"` + - `"eq"` - - `"original"` + - `"ne"` - - `type: "input_image"` + - `"gt"` - The type of the input item. Always `input_image`. + - `"gte"` - - `file_id: optional string` + - `"lt"` - The ID of the file to be sent to the model. + - `"lte"` - - `image_url: optional string` + - `"in"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"nin"` - - `prompt_cache_breakpoint: optional object { mode }` + - `value: string or number or boolean or array of string or number` - 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. + The value to compare against the attribute key; supports string, number, or boolean types. - - `mode: "explicit"` + - `union_member_0: string` - The breakpoint mode. Always `explicit`. + - `union_member_1: number` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `union_member_2: boolean` - A file input to the model. + - `union_member_3: array of string or number` - - `type: "input_file"` + - `union_member_0: string` - The type of the input item. Always `input_file`. + - `union_member_1: number` - - `detail: optional "auto" or "low" or "high"` + - `union_member_1: unknown` - 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`. + - `type: "and" or "or"` - - `"auto"` + Type of operation: `and` or `or`. - - `"low"` + - `"and"` - - `"high"` + - `"or"` - - `file_data: optional string` + - `max_num_results: optional number` - The content of the file to be sent to the model. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `file_id: optional string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The ID of the file to be sent to the model. + Ranking options for search. - - `file_url: optional string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The URL of the file to be sent to the model. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `filename: optional string` + - `embedding_weight: number` - The name of the file to be sent to the model. + The weight of the embedding in the reciprocal ranking fusion. - - `prompt_cache_breakpoint: optional object { mode }` + - `text_weight: number` - 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. + The weight of the text in the reciprocal ranking fusion. - - `mode: "explicit"` + - `ranker: optional "auto" or "default-2024-11-15"` - The breakpoint mode. Always `explicit`. + The ranker to use for the file search. - - `status: "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"default-2024-11-15"` - - `"in_progress"` + - `score_threshold: optional number` - - `"completed"` + 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. - - `"incomplete"` + - `beta_computer_tool: object { type }` - - `type: "function_call_output"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the function tool call output. Always `function_call_output`. + - `type: "computer"` - - `agent: optional object { agent_name }` + The type of the computer tool. Always `computer`. - The agent that produced this item. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `agent_name: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The canonical name of the agent that produced this item. + - `display_height: number` - - `caller: optional object { type } or object { caller_id, type }` + The height of the computer display. - The execution context that produced this tool call. + - `display_width: number` - - `direct: object { type }` + The width of the computer display. - - `program: object { caller_id, type }` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `caller_id: string` + The type of computer environment to control. - The call ID of the program item that produced this tool call. + - `"windows"` - - `type: "program"` + - `"mac"` - The caller type. Always `program`. + - `"linux"` - - `created_by: optional string` + - `"ubuntu"` - The identifier of the actor that created the item. + - `"browser"` -### Beta Response Function Web Search + - `type: "computer_use_preview"` -- `beta_response_function_web_search: object { id, action, status, 2 more }` + The type of the computer use tool. Always `computer_use_preview`. - 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. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `id: string` + 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). - The unique ID of the web search tool call. + - `type: "web_search" or "web_search_2025_08_26"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - 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). + - `"web_search"` - - `search: object { type, queries, query, sources }` + - `"web_search_2025_08_26"` - Action type "search" - Performs a web search query. + - `filters: optional object { allowed_domains }` - - `type: "search"` + Filters for the search. - The action type. + - `allowed_domains: optional array of string` - - `queries: optional array of string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The search queries. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `query: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - The search query. + 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. - - `sources: optional array of object { type, url }` + - `"low"` - The sources used in the search. + - `"medium"` - - `type: "url"` + - `"high"` - The type of source. Always `url`. + - `user_location: optional object { city, country, region, 2 more }` - - `url: string` + The approximate location of the user. - The URL of the source. + - `city: optional string` - - `open_page: object { type, url }` + Free text input for the city of the user, e.g. `San Francisco`. - Action type "open_page" - Opens a specific URL from search results. + - `country: optional string` - - `type: "open_page"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The action type. + - `region: optional string` - - `url: optional string` + Free text input for the region of the user, e.g. `California`. - The URL opened by the model. + - `timezone: optional string` - - `find_in_page: object { pattern, type, url }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: optional "approximate"` - - `pattern: string` + The type of location approximation. Always `approximate`. - The pattern or text to search for within the page. + - `"approximate"` - - `type: "find_in_page"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The action type. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `url: string` + - `server_label: string` - The URL of the page searched for the pattern. + A label for this MCP server, used to identify it in tool calls. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `type: "mcp"` - The status of the web search tool call. + The type of the MCP tool. Always `mcp`. - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"searching"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"failed"` + - `"programmatic"` - - `type: "web_search_call"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The type of the web search tool call. Always `web_search_call`. + List of allowed tool names or a filter object. - - `agent: optional object { agent_name }` + - `MCP allowed tools: array of string` - The agent that produced this item. + A string array of allowed tool names - - `agent_name: string` + - `MCP tool filter: object { read_only, tool_names }` - The canonical name of the agent that produced this item. + A filter object to specify which tools are allowed. -### Beta Response Image Gen Call Completed Event + - `read_only: optional boolean` -- `beta_response_image_gen_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + 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. - Emitted when an image generation tool call has completed and the final image is available. + - `tool_names: optional array of string` - - `item_id: string` + List of allowed tool names. - The unique identifier of the image generation item being processed. + - `authorization: optional string` - - `output_index: number` + 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. - The index of the output item in the response's output array. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `sequence_number: number` + 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). - The sequence number of this event. + Currently supported `connector_id` values are: - - `type: "response.image_generation_call.completed"` + - 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` - The type of the event. Always 'response.image_generation_call.completed'. + - `"connector_dropbox"` - - `agent: optional object { agent_name }` + - `"connector_gmail"` - The agent that owns this multi-agent streaming event. + - `"connector_googlecalendar"` - - `agent_name: string` + - `"connector_googledrive"` - The canonical name of the agent that produced this item. + - `"connector_microsoftteams"` -### Beta Response Image Gen Call Generating Event + - `"connector_outlookcalendar"` -- `beta_response_image_gen_call_generating_event: object { item_id, output_index, sequence_number, 2 more }` + - `"connector_outlookemail"` - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `"connector_sharepoint"` - - `item_id: string` + - `defer_loading: optional boolean` - The unique identifier of the image generation item being processed. + Whether this MCP tool is deferred and discovered via tool search. - - `output_index: number` + - `headers: optional map[string]` - The index of the output item in the response's output array. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `sequence_number: number` + - `require_approval: optional object { always, never } or "always" or "never"` - The sequence number of the image generation item being processed. + Specify which of the MCP server's tools require approval. - - `type: "response.image_generation_call.generating"` + - `MCP tool approval filter: object { always, never }` - The type of the event. Always 'response.image_generation_call.generating'. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `agent: optional object { agent_name }` + - `always: optional object { read_only, tool_names }` - The agent that owns this multi-agent streaming event. + A filter object to specify which tools are allowed. - - `agent_name: string` + - `read_only: optional boolean` - The canonical name of the agent that produced this item. + 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. -### Beta Response Image Gen Call In Progress Event + - `tool_names: optional array of string` -- `beta_response_image_gen_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + List of allowed tool names. - Emitted when an image generation tool call is in progress. + - `never: optional object { read_only, tool_names }` - - `item_id: string` + A filter object to specify which tools are allowed. - The unique identifier of the image generation item being processed. + - `read_only: optional boolean` - - `output_index: number` + 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. - The index of the output item in the response's output array. + - `tool_names: optional array of string` - - `sequence_number: number` + List of allowed tool names. - The sequence number of the image generation item being processed. + - `MCP tool approval setting: "always" or "never"` - - `type: "response.image_generation_call.in_progress"` + 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. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `"always"` - - `agent: optional object { agent_name }` + - `"never"` - The agent that owns this multi-agent streaming event. + - `server_description: optional string` - - `agent_name: string` + Optional description of the MCP server, used to provide more context. - The canonical name of the agent that produced this item. + - `server_url: optional string` -### Beta Response Image Gen Call Partial Image Event + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. -- `beta_response_image_gen_call_partial_image_event: object { item_id, output_index, partial_image_b64, 4 more }` + - `tunnel_id: optional string` - Emitted when a partial image is available during image generation streaming. + 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. - - `item_id: string` + - `code_interpreter: object { container, type, allowed_callers }` - The unique identifier of the image generation item being processed. + A tool that runs Python code to help generate a response to a prompt. - - `output_index: number` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The index of the output item in the response's output array. + 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. - - `partial_image_b64: string` + - `union_member_0: string` - Base64-encoded partial image data, suitable for rendering as an image. + The container ID. - - `partial_image_index: number` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `sequence_number: number` + - `type: "auto"` - The sequence number of the image generation item being processed. + Always `auto`. - - `type: "response.image_generation_call.partial_image"` + - `file_ids: optional array of string` - The type of the event. Always 'response.image_generation_call.partial_image'. + An optional list of uploaded files to make available to your code. - - `agent: optional object { agent_name }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The agent that owns this multi-agent streaming event. + The memory limit for the code interpreter container. - - `agent_name: string` + - `"1g"` - The canonical name of the agent that produced this item. + - `"4g"` -### Beta Response In Progress Event + - `"16g"` -- `beta_response_in_progress_event: object { response, sequence_number, type, agent }` + - `"64g"` - Emitted when the response is in progress. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `response: object { id, created_at, error, 31 more }` + Network access policy for the container. - The response that is in progress. + - `beta_container_network_policy_disabled: object { type }` - - `id: string` + - `type: "disabled"` - Unique identifier for this Response. + Disable outbound network access. Always `disabled`. - - `created_at: number` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - Unix timestamp (in seconds) of when this Response was created. + - `allowed_domains: array of string` - - `error: object { code, message }` + A list of allowed domains when type is `allowlist`. - An error object returned when the model fails to generate a Response. + - `type: "allowlist"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + Allow outbound network access only to specified domains. Always `allowlist`. - The error code for the response. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"server_error"` + Optional domain-scoped secrets for allowlisted domains. - - `"rate_limit_exceeded"` + - `domain: string` - - `"invalid_prompt"` + The domain associated with the secret. - - `"bio_policy"` + - `name: string` - - `"vector_store_timeout"` + The name of the secret to inject for the domain. - - `"invalid_image"` + - `value: string` - - `"invalid_image_format"` + The secret value to inject for the domain. - - `"invalid_base64_image"` + - `type: "code_interpreter"` - - `"invalid_image_url"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"image_too_large"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"image_too_small"` + The tool invocation context(s). - - `"image_parse_error"` + - `"direct"` - - `"image_content_policy_violation"` + - `"programmatic"` - - `"invalid_image_mode"` + - `programmatic_tool_calling: object { type }` - - `"image_file_too_large"` + - `image_generation: object { type, action, background, 9 more }` - - `"unsupported_image_media_type"` + A tool that generates images using the GPT image models. - - `"empty_image_file"` + - `type: "image_generation"` - - `"failed_to_download_image"` + The type of the image generation tool. Always `image_generation`. - - `"image_file_not_found"` + - `action: optional "generate" or "edit" or "auto"` - - `message: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - A human-readable description of the error. + - `"generate"` - - `incomplete_details: object { reason }` + - `"edit"` - Details about why the response is incomplete. + - `"auto"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `background: optional "transparent" or "opaque" or "auto"` - The reason why the response is incomplete. + 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. - - `"max_output_tokens"` + `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. - - `"content_filter"` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `instructions: string or array of BetaResponseInputItem` + - `"transparent"` - A system (or developer) message inserted into the model's context. + - `"opaque"` - When using 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. + - `"auto"` - - `union_member_0: string` + - `input_fidelity: optional "high" or "low"` - A text input to the model, equivalent to a text input with the - `developer` role. + 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`. - - `Input item list: array of BetaResponseInputItem` + - `"high"` - A list of one or many input items to the model, containing - different content types. + - `"low"` - - `beta_easy_input_message: object { content, role, phase, type }` + - `input_image_mask: optional object { file_id, image_url }` - 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. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `content: string or BetaResponseInputMessageContentList` + - `file_id: optional string` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + File ID for the mask image. - - `Text input: string` + - `image_url: optional string` - A text input to the model. + Base64-encoded mask image. - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - A list of one or many input items to the model, containing different content - types. + The image generation model to use. Default: `gpt-image-1`. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"gpt-image-1"` - A text input to the model. + - `"gpt-image-1-mini"` - - `text: string` + - `"gpt-image-2"` - The text input to the model. + - `"gpt-image-2-2026-04-21"` - - `type: "input_text"` + - `"gpt-image-1.5"` - The type of the input item. Always `input_text`. + - `"chatgpt-image-latest"` - - `prompt_cache_breakpoint: optional object { mode }` + - `moderation: optional "auto" or "low"` - 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. + Moderation level for the generated image. Default: `auto`. - - `mode: "explicit"` + - `"auto"` - The breakpoint mode. Always `explicit`. + - `"low"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `output_compression: optional number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Compression level for the output image. Default: 100. - - `detail: "low" or "high" or "auto" or "original"` + - `output_format: optional "png" or "webp" or "jpeg"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"low"` + - `"png"` - - `"high"` + - `"webp"` - - `"auto"` + - `"jpeg"` - - `"original"` + - `partial_images: optional number` - - `type: "input_image"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of the input item. Always `input_image`. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `file_id: optional string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The ID of the file to be sent to the model. + - `"low"` - - `image_url: optional string` + - `"medium"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"high"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"auto"` - 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. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `mode: "explicit"` + 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`. - The breakpoint mode. Always `explicit`. + - `"1024x1024"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"1024x1536"` - A file input to the model. + - `"1536x1024"` - - `type: "input_file"` + - `"auto"` - The type of the input item. Always `input_file`. + - `local_shell: object { type }` - - `detail: optional "auto" or "low" or "high"` + A tool that allows the model to execute shell commands in a local environment. - 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`. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"auto"` + A tool that allows the model to execute shell commands. - - `"low"` + - `type: "shell"` - - `"high"` + The type of the shell tool. Always `shell`. - - `file_data: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The content of the file to be sent to the model. + The tool invocation context(s). - - `file_id: optional string` + - `"direct"` - The ID of the file to be sent to the model. + - `"programmatic"` - - `file_url: optional string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The URL of the file to be sent to the model. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `filename: optional string` + - `type: "container_auto"` - The name of the file to be sent to the model. + Automatically creates a container for this request - - `prompt_cache_breakpoint: optional object { mode }` + - `file_ids: optional array of string` - 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. + An optional list of uploaded files to make available to your code. - - `mode: "explicit"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The breakpoint mode. Always `explicit`. + The memory limit for the container. - - `role: "user" or "assistant" or "system" or "developer"` + - `"1g"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"4g"` - - `"user"` + - `"16g"` - - `"assistant"` + - `"64g"` - - `"system"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"developer"` + Network access policy for the container. - - `phase: optional "commentary"` + - `beta_container_network_policy_disabled: object { type }` - 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. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `"commentary"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `type: optional "message"` + An optional list of skills referenced by id or inline data. - The type of the message input. Always `message`. + - `beta_skill_reference: object { skill_id, type, version }` - - `"message"` + - `skill_id: string` - - `message: object { content, role, agent, 2 more }` + The ID of the referenced skill. - 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. + - `type: "skill_reference"` - - `content: array of BetaResponseInputContent` + References a skill created with the /v1/skills endpoint. - A list of one or many input items to the model, containing different content - types. + - `version: optional string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A text input to the model. + - `beta_inline_skill: object { description, name, source, type }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `description: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The description of the skill. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `name: string` - A file input to the model. + The name of the skill. - - `role: "user" or "system" or "developer"` + - `source: object { data, media_type, type }` - The role of the message input. One of `user`, `system`, or `developer`. + Inline skill payload - - `"user"` + - `data: string` - - `"system"` + Base64-encoded skill zip bundle. - - `"developer"` + - `media_type: "application/zip"` - - `agent: optional object { agent_name }` + The media type of the inline skill payload. Must be `application/zip`. - The agent that produced this item. + - `type: "base64"` - - `agent_name: string` + The type of the inline skill source. Must be `base64`. - The canonical name of the agent that produced this item. + - `type: "inline"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Defines an inline skill for this request. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_local_environment: object { type, skills }` - - `"in_progress"` + - `type: "local"` - - `"completed"` + Use a local computer environment. - - `"incomplete"` + - `skills: optional array of BetaLocalSkill` - - `type: optional "message"` + An optional list of skills. - The type of the message input. Always set to `message`. + - `description: string` - - `"message"` + The description of the skill. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `name: string` - An output message from the model. + The name of the skill. - - `id: string` + - `path: string` - The unique ID of the output message. + The path to the directory containing the skill. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `beta_container_reference: object { container_id, type }` - The content of the output message. + - `container_id: string` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + The ID of the referenced container. - A text output from the model. + - `type: "container_reference"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + References a container created with the /v1/containers endpoint - The annotations of the text output. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `file_citation: object { file_id, filename, index, type }` + 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) - A citation to a file. + - `name: string` - - `file_id: string` + The name of the custom tool, used to identify it in tool calls. - The ID of the file. + - `type: "custom"` - - `filename: string` + The type of the custom tool. Always `custom`. - The filename of the file cited. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `index: number` + The tool invocation context(s). - The index of the file in the list of files. + - `"direct"` - - `type: "file_citation"` + - `"programmatic"` - The type of the file citation. Always `file_citation`. + - `defer_loading: optional boolean` - - `url_citation: object { end_index, start_index, title, 2 more }` + Whether this tool should be deferred and discovered via tool search. - A citation for a web resource used to generate a model response. + - `description: optional string` - - `end_index: number` + Optional description of the custom tool, used to provide more context. - The index of the last character of the URL citation in the message. + - `format: optional object { type } or object { definition, syntax, type }` - - `start_index: number` + The input format for the custom tool. Default is unconstrained text. - The index of the first character of the URL citation in the message. + - `text: object { type }` - - `title: string` + Unconstrained free-form text. - The title of the web resource. + - `grammar: object { definition, syntax, type }` - - `type: "url_citation"` + A grammar defined by the user. - The type of the URL citation. Always `url_citation`. + - `definition: string` - - `url: string` + The grammar definition. - The URL of the web resource. + - `syntax: "lark" or "regex"` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + The syntax of the grammar definition. One of `lark` or `regex`. - A citation for a container file used to generate a model response. + - `"lark"` - - `container_id: string` + - `"regex"` - The ID of the container file. + - `type: "grammar"` - - `end_index: number` + Grammar format. Always `grammar`. - The index of the last character of the container file citation in the message. + - `beta_namespace_tool: object { description, name, tools, type }` - - `file_id: string` + Groups function/custom tools under a shared namespace. - The ID of the file. + - `description: string` - - `filename: string` + A description of the namespace shown to the model. - The filename of the container file cited. + - `name: string` - - `start_index: number` + The namespace name used in tool calls (for example, `crm`). - The index of the first character of the container file citation in the message. + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `type: "container_file_citation"` + The function/custom tools available inside this namespace. - The type of the container file citation. Always `container_file_citation`. + - `function: object { name, type, allowed_callers, 5 more }` - - `file_path: object { file_id, index, type }` + - `name: string` - A path to a file. + - `type: "function"` - - `file_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ID of the file. + The tool invocation context(s). - - `index: number` + - `"direct"` - The index of the file in the list of files. + - `"programmatic"` - - `type: "file_path"` + - `defer_loading: optional boolean` - The type of the file path. Always `file_path`. + Whether this function should be deferred and discovered via tool search. - - `text: string` + - `description: optional string` - The text output from the model. + - `output_schema: optional map[unknown]` - - `type: "output_text"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The type of the output text. Always `output_text`. + - `parameters: optional unknown` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `strict: optional boolean` - - `token: string` + 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. - - `bytes: array of number` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `logprob: number` + 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) - - `top_logprobs: array of object { token, bytes, logprob }` + - `name: string` - - `token: string` + The name of the custom tool, used to identify it in tool calls. - - `bytes: array of number` + - `type: "custom"` - - `logprob: number` + The type of the custom tool. Always `custom`. - - `beta_response_output_refusal: object { refusal, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A refusal from the model. + The tool invocation context(s). - - `refusal: string` + - `defer_loading: optional boolean` - The refusal explanation from the model. + Whether this tool should be deferred and discovered via tool search. - - `type: "refusal"` + - `description: optional string` - The type of the refusal. Always `refusal`. + Optional description of the custom tool, used to provide more context. - - `role: "assistant"` + - `format: optional object { type } or object { definition, syntax, type }` - The role of the output message. Always `assistant`. + The input format for the custom tool. Default is unconstrained text. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "namespace"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The type of the tool. Always `namespace`. - - `"in_progress"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `"completed"` + Hosted or BYOT tool search configuration for deferred tools. - - `"incomplete"` + - `type: "tool_search"` - - `type: "message"` + The type of the tool. Always `tool_search`. - The type of the output message. Always `message`. + - `description: optional string` - - `agent: optional object { agent_name }` + Description shown to the model for a client-executed tool search tool. - The agent that produced this item. + - `execution: optional "server" or "client"` - - `agent_name: string` + Whether tool search is executed by the server or by the client. - The canonical name of the agent that produced this item. + - `"server"` - - `phase: optional "commentary"` + - `"client"` - 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. + - `parameters: optional unknown` - - `"commentary"` + Parameter schema for a client-executed tool search tool. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - 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. + 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). - - `id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The unique ID of the file search tool call. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `queries: array of string` + - `"web_search_preview"` - The queries used to search for files. + - `"web_search_preview_2025_03_11"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `search_content_types: optional array of "text" or "image"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"text"` - - `"in_progress"` + - `"image"` - - `"searching"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"completed"` + 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. - - `"incomplete"` + - `"low"` - - `"failed"` + - `"medium"` - - `type: "file_search_call"` + - `"high"` - The type of the file search tool call. Always `file_search_call`. + - `user_location: optional object { type, city, country, 2 more }` - - `agent: optional object { agent_name }` + The user's location. - The agent that produced this item. + - `type: "approximate"` - - `agent_name: string` + The type of location approximation. Always `approximate`. - The canonical name of the agent that produced this item. + - `city: optional string` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Free text input for the city of the user, e.g. `San Francisco`. - The results of the file search tool call. + - `country: optional string` - - `attributes: optional map[string or number or boolean]` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - 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. + - `region: optional string` - - `union_member_0: string` + Free text input for the region of the user, e.g. `California`. - - `union_member_1: number` + - `timezone: optional string` - - `union_member_2: boolean` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `file_id: optional string` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The unique ID of the file. + Allows the assistant to create, delete, or update files using unified diffs. - - `filename: optional string` + - `type: "apply_patch"` - The name of the file. + The type of the tool. Always `apply_patch`. - - `score: optional number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The relevance score of the file - a value between 0 and 1. + The tool invocation context(s). - - `text: optional string` + - `"direct"` - The text that was retrieved from the file. + - `"programmatic"` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `type: "tool_search_output"` - 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. + The item type. Always `tool_search_output`. - - `id: string` + - `id: optional string` - The unique ID of the computer call. + The unique ID of this tool search output. - - `call_id: string` + - `agent: optional object { agent_name }` - An identifier used when responding to the tool call with output. + The agent that produced this item. - - `pending_safety_checks: array of object { id, code, message }` + - `agent_name: string` - The pending safety checks for the computer call. + The canonical name of the agent that produced this item. - - `id: string` + - `call_id: optional string` - The ID of the pending safety check. + The unique ID of the tool search call generated by the model. - - `code: optional string` + - `execution: optional "server" or "client"` - The type of the pending safety check. + Whether tool search was executed by the server or by the client. - - `message: optional string` + - `"server"` - Details about the pending safety check. + - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool search output. - `"in_progress"` @@ -71701,278 +83197,281 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "computer_call"` + - `additional_tools: object { role, tools, type, 2 more }` - The type of the computer call. Always `computer_call`. + - `role: "developer"` - - `"computer_call"` + The role that provided the additional tools. Only `developer` is supported. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `tools: array of BetaTool` - A click action. + A list of additional tools made available at this item. - - `click: object { button, type, x, 2 more }` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - A click action. + 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). - - `button: "left" or "right" or "wheel" or 2 more` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + 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). - - `"left"` + - `beta_computer_tool: object { type }` - - `"right"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"wheel"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `"back"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"forward"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `type: "click"` + 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). - Specifies the event type. For a click action, this property is always `click`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `x: number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The x-coordinate where the click occurred. + - `code_interpreter: object { container, type, allowed_callers }` - - `y: number` + A tool that runs Python code to help generate a response to a prompt. - The y-coordinate where the click occurred. + - `programmatic_tool_calling: object { type }` - - `keys: optional array of string` + - `image_generation: object { type, action, background, 9 more }` - The keys being held while clicking. + A tool that generates images using the GPT image models. - - `double_click: object { keys, type, x, y }` + - `local_shell: object { type }` - A double click action. + A tool that allows the model to execute shell commands in a local environment. - - `keys: array of string` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - The keys being held while double-clicking. + A tool that allows the model to execute shell commands. - - `type: "double_click"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + 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) - - `x: number` + - `beta_namespace_tool: object { description, name, tools, type }` - The x-coordinate where the double click occurred. + Groups function/custom tools under a shared namespace. - - `y: number` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The y-coordinate where the double click occurred. + Hosted or BYOT tool search configuration for deferred tools. - - `drag: object { path, type, keys }` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - A drag action. + 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). - - `path: array of object { x, y }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Allows the assistant to create, delete, or update files using unified diffs. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `type: "additional_tools"` - - `x: number` + The item type. Always `additional_tools`. - The x-coordinate. + - `id: optional string` - - `y: number` + The unique ID of this additional tools item. - The y-coordinate. + - `agent: optional object { agent_name }` - - `type: "drag"` + The agent that produced this item. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `agent_name: string` - - `keys: optional array of string` + The canonical name of the agent that produced this item. - The keys being held while dragging the mouse. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `keypress: object { keys, type }` + 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). - A collection of keypresses the model would like to perform. + - `id: string` - - `keys: array of string` + The unique identifier of the reasoning content. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `summary: array of object { text, type }` - - `type: "keypress"` + Reasoning summary content. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `text: string` - - `move: object { type, x, y, keys }` + A summary of the reasoning output from the model so far. - A mouse move action. + - `type: "summary_text"` - - `type: "move"` + The type of the object. Always `summary_text`. - Specifies the event type. For a move action, this property is always set to `move`. + - `type: "reasoning"` - - `x: number` + The type of the object. Always `reasoning`. - The x-coordinate to move to. + - `agent: optional object { agent_name }` - - `y: number` + The agent that produced this item. - The y-coordinate to move to. + - `agent_name: string` - - `keys: optional array of string` + The canonical name of the agent that produced this item. - The keys being held while moving the mouse. + - `content: optional array of object { text, type }` - - `screenshot: object { type }` + Reasoning text content. - A screenshot action. + - `text: string` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + The reasoning text from the model. - A scroll action. + - `type: "reasoning_text"` - - `scroll_x: number` + The type of the reasoning text. Always `reasoning_text`. - The horizontal scroll distance. + - `encrypted_content: optional string` - - `scroll_y: number` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The vertical scroll distance. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "scroll"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"in_progress"` - - `x: number` + - `"completed"` - The x-coordinate where the scroll occurred. + - `"incomplete"` - - `y: number` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - The y-coordinate where the scroll occurred. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `keys: optional array of string` + - `encrypted_content: string` - The keys being held while scrolling. + The encrypted content of the compaction summary. - - `type: object { text, type }` + - `type: "compaction"` - An action to type in text. + The type of the item. Always `compaction`. - - `text: string` + - `id: optional string` - The text to type. + The ID of the compaction item. - - `type: "type"` + - `agent: optional object { agent_name }` - Specifies the event type. For a type action, this property is always set to `type`. + The agent that produced this item. - - `wait: object { type }` + - `agent_name: string` - A wait action. + The canonical name of the agent that produced this item. - - `actions: optional array of BetaComputerAction` + - `image_generation_call: object { id, result, status, 2 more }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + An image generation request made by the model. - - `click: object { button, type, x, 2 more }` + - `id: string` - A click action. + The unique ID of the image generation call. - - `double_click: object { keys, type, x, y }` + - `result: string` - A double click action. + The generated image encoded in base64. - - `drag: object { path, type, keys }` + - `status: "in_progress" or "completed" or "generating" or "failed"` - A drag action. + The status of the image generation call. - - `keypress: object { keys, type }` + - `"in_progress"` - A collection of keypresses the model would like to perform. + - `"completed"` - - `move: object { type, x, y, keys }` + - `"generating"` - A mouse move action. + - `"failed"` - - `screenshot: object { type }` + - `type: "image_generation_call"` - A screenshot action. + The type of the image generation call. Always `image_generation_call`. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `agent: optional object { agent_name }` - A scroll action. + The agent that produced this item. - - `type: object { text, type }` + - `agent_name: string` - An action to type in text. + The canonical name of the agent that produced this item. - - `wait: object { type }` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - A wait action. + A tool call to run code. - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + The unique ID of the code interpreter tool call. - - `agent_name: string` + - `code: string` - The canonical name of the agent that produced this item. + The code to run, or null if not available. - - `computer_call_output: object { call_id, output, type, 4 more }` + - `container_id: string` - The output of a computer tool call. + The ID of the container used to run the code. - - `call_id: string` + - `outputs: array of object { logs, type } or object { type, url }` - The ID of the computer tool call that produced the output. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `output: object { type, file_id, image_url }` + - `logs: object { logs, type }` - A computer screenshot image used with the computer use tool. + The logs output from the code interpreter. - - `type: "computer_screenshot"` + - `logs: string` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The logs output from the code interpreter. - - `file_id: optional string` + - `type: "logs"` - The identifier of an uploaded file that contains the screenshot. + The type of the output. Always `logs`. - - `image_url: optional string` + - `image: object { type, url }` - The URL of the screenshot image. + The image output from the code interpreter. - - `type: "computer_call_output"` + - `type: "image"` - The type of the computer tool call output. Always `computer_call_output`. + The type of the output. Always `image`. - - `id: optional string` + - `url: string` - The ID of the computer tool call output. + The URL of the image output from the code interpreter. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The safety checks reported by the API that have been acknowledged by the developer. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `id: string` + - `"in_progress"` - The ID of the pending safety check. + - `"completed"` - - `code: optional string` + - `"incomplete"` - The type of the pending safety check. + - `"interpreting"` - - `message: optional string` + - `"failed"` - Details about the pending safety check. + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. - `agent: optional object { agent_name }` @@ -71982,134 +83481,133 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `local_shell_call: object { id, action, call_id, 3 more }` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + A tool call to run a command on the local shell. - - `"in_progress"` + - `id: string` - - `"completed"` + The unique ID of the local shell call. - - `"incomplete"` + - `action: object { command, env, type, 3 more }` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + Execute a shell command on the server. - 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. + - `command: array of string` - - `id: string` + The command to run. - The unique ID of the web search tool call. + - `env: map[string]` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Environment variables to set for the command. - 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). + - `type: "exec"` - - `search: object { type, queries, query, sources }` + The type of the local shell action. Always `exec`. - Action type "search" - Performs a web search query. + - `timeout_ms: optional number` - - `type: "search"` + Optional timeout in milliseconds for the command. - The action type. + - `user: optional string` - - `queries: optional array of string` + Optional user to run the command as. - The search queries. + - `working_directory: optional string` - - `query: optional string` + Optional working directory to run the command in. - The search query. + - `call_id: string` - - `sources: optional array of object { type, url }` + The unique ID of the local shell tool call generated by the model. - The sources used in the search. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "url"` + The status of the local shell call. - The type of source. Always `url`. + - `"in_progress"` - - `url: string` + - `"completed"` - The URL of the source. + - `"incomplete"` - - `open_page: object { type, url }` + - `type: "local_shell_call"` - Action type "open_page" - Opens a specific URL from search results. + The type of the local shell call. Always `local_shell_call`. - - `type: "open_page"` + - `agent: optional object { agent_name }` - The action type. + The agent that produced this item. - - `url: optional string` + - `agent_name: string` - The URL opened by the model. + The canonical name of the agent that produced this item. - - `find_in_page: object { pattern, type, url }` + - `local_shell_call_output: object { id, output, type, 2 more }` - Action type "find_in_page": Searches for a pattern within a loaded page. + The output of a local shell tool call. - - `pattern: string` + - `id: string` - The pattern or text to search for within the page. + The unique ID of the local shell tool call generated by the model. - - `type: "find_in_page"` + - `output: string` - The action type. + A JSON string of the output of the local shell tool call. - - `url: string` + - `type: "local_shell_call_output"` - The URL of the page searched for the pattern. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `agent: optional object { agent_name }` - The status of the web search tool call. + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - - `"searching"` - - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: "web_search_call"` + - `shell_call: object { action, call_id, type, 5 more }` - The type of the web search tool call. Always `web_search_call`. + A tool representing a request to execute one or more shell commands. - - `agent: optional object { agent_name }` + - `action: object { commands, max_output_length, timeout_ms }` - The agent that produced this item. + The shell commands and limits that describe how to run the tool call. - - `agent_name: string` + - `commands: array of string` - The canonical name of the agent that produced this item. + Ordered shell commands for the execution environment to run. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `max_output_length: optional number` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `arguments: string` + - `timeout_ms: optional number` - A JSON string of the arguments to pass to the function. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - `call_id: string` - The unique ID of the function tool call generated by the model. - - - `name: string` - - The name of the function to run. + The unique ID of the shell tool call generated by the model. - - `type: "function_call"` + - `type: "shell_call"` - The type of the function tool call. Always `function_call`. + The type of the item. Always `shell_call`. - `id: optional string` - The unique ID of the function tool call. + The unique ID of the shell tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -72133,14 +83631,19 @@ openai beta:responses compact \ - `type: "program"` - - `namespace: optional string` + The caller type. Always `program`. - The namespace of the function to run. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `beta_local_environment: object { type, skills }` + + - `beta_container_reference: object { container_id, type }` - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -72148,131 +83651,163 @@ openai beta:responses compact \ - `"incomplete"` - - `function_call_output: object { call_id, output, type, 4 more }` + - `shell_call_output: object { call_id, output, type, 5 more }` - The output of a function tool call. + The streamed output items emitted by a shell tool call. - `call_id: string` - The unique ID of the function tool call generated by the model. + The unique ID of the shell tool call generated by the model. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output: array of BetaResponseFunctionShellCallOutputContent` - Text, image, or file output of the function tool call. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `union_member_0: string` + - `outcome: object { type } or object { exit_code, type }` - A JSON string of the output of the function tool call. + The exit or timeout outcome associated with this shell call. - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + - `timeout: object { type }` - An array of content outputs (text, image, file) for the function tool call. + Indicates that the shell call exceeded its configured time limit. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `exit: object { exit_code, type }` - A text input to the model. + Indicates that the shell commands finished and returned an exit code. - - `text: string` + - `exit_code: number` - The text input to the model. + The exit code returned by the shell process. - - `type: "input_text"` + - `type: "exit"` - The type of the input item. Always `input_text`. + The outcome type. Always `exit`. - - `prompt_cache_breakpoint: optional object { mode }` + - `stderr: string` - 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. + Captured stderr output for the shell call. - - `mode: "explicit"` + - `stdout: string` - The breakpoint mode. Always `explicit`. + Captured stdout output for the shell call. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `type: "shell_call_output"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The type of the item. Always `shell_call_output`. - - `type: "input_image"` + - `id: optional string` - The type of the input item. Always `input_image`. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `detail: optional "low" or "high" or "auto" or "original"` + - `agent: optional object { agent_name }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` + - `caller: optional object { type } or object { caller_id, type }` - - `"original"` + The execution context that produced this tool call. - - `file_id: optional string` + - `direct: object { type }` - The ID of the file to be sent to the model. + - `program: object { caller_id, type }` - - `image_url: optional string` + - `caller_id: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The call ID of the program item that produced this tool call. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "program"` - 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. + The caller type. Always `program`. - - `mode: "explicit"` + - `max_output_length: optional number` - The breakpoint mode. Always `explicit`. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A file input to the model. + The status of the shell call output. - - `type: "input_file"` + - `"in_progress"` - The type of the input item. Always `input_file`. + - `"completed"` - - `detail: optional "auto" or "low" or "high"` + - `"incomplete"` - 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`. + - `apply_patch_call: object { call_id, operation, status, 4 more }` - - `"auto"` + A tool call representing a request to create, delete, or update files using diff patches. - - `"low"` + - `call_id: string` - - `"high"` + The unique ID of the apply patch tool call generated by the model. - - `file_data: optional string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The base64-encoded data of the file to be sent to the model. + The specific create, delete, or update instruction for the apply_patch tool call. - - `file_id: optional string` + - `create_file: object { diff, path, type }` - The ID of the file to be sent to the model. + Instruction for creating a new file via the apply_patch tool. - - `file_url: optional string` + - `diff: string` - The URL of the file to be sent to the model. + Unified diff content to apply when creating the file. - - `filename: optional string` + - `path: string` - The name of the file to be sent to the model. + Path of the file to create relative to the workspace root. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "create_file"` - 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. + The operation type. Always `create_file`. - - `mode: "explicit"` + - `delete_file: object { path, type }` - The breakpoint mode. Always `explicit`. + Instruction for deleting an existing file via the apply_patch tool. - - `type: "function_call_output"` + - `path: string` - The type of the function tool call output. Always `function_call_output`. + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `update_file: object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. - `id: optional string` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -72298,91 +83833,93 @@ openai beta:responses compact \ The caller type. Always `program`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The streamed output emitted by an apply patch tool call. - - `"in_progress"` + - `call_id: string` - - `"completed"` + The unique ID of the apply patch tool call generated by the model. - - `"incomplete"` + - `status: "completed" or "failed"` - - `agent_message: object { author, content, recipient, 3 more }` + The status of the apply patch tool call output. One of `completed` or `failed`. - A message routed between agents. + - `"completed"` - - `author: string` + - `"failed"` - The sending agent identity. + - `type: "apply_patch_call_output"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The type of the item. Always `apply_patch_call_output`. - Plaintext, image, or encrypted content sent between agents. + - `id: optional string` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A text input to the model. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The text input to the model. + - `agent_name: string` - - `type: "input_text"` + The canonical name of the agent that produced this item. - The type of the input item. Always `input_text`. + - `caller: optional object { type } or object { caller_id, type }` - - `prompt_cache_breakpoint: optional object { mode }` + The execution context that produced this tool call. - 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. + - `direct: object { type }` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `program: object { caller_id, type }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `caller_id: string` - - `type: "input_image"` + The call ID of the program item that produced this tool call. - The type of the input item. Always `input_image`. + - `type: "program"` - - `detail: optional "low" or "high" or "auto" or "original"` + The caller type. Always `program`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `output: optional string` - - `file_id: optional string` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - The ID of the file to be sent to the model. + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `image_url: optional string` + A list of tools available on an MCP server. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique ID of the list. - 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. + - `server_label: string` - - `encrypted_content: object { encrypted_content, type }` + The label of the MCP server. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `tools: array of object { input_schema, name, annotations, description }` - - `encrypted_content: string` + The tools available on the server. - Opaque encrypted content. + - `input_schema: unknown` - - `type: "encrypted_content"` + The JSON schema describing the tool's input. - The type of the input item. Always `encrypted_content`. + - `name: string` - - `recipient: string` + The name of the tool. - The destination agent identity. + - `annotations: optional unknown` - - `type: "agent_message"` + Additional annotations about the tool. - The item type. Always `agent_message`. + - `description: optional string` - - `id: optional string` + The description of the tool. - The unique ID of this agent message item. + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. - `agent: optional object { agent_name }` @@ -72392,39 +83929,33 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. - - - `"spawn_agent"` + - `error: optional string` - - `"interrupt_agent"` + Error message if the server could not list tools. - - `"list_agents"` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `"send_message"` + A request for human approval of a tool invocation. - - `"followup_task"` + - `id: string` - - `"wait_agent"` + The unique ID of the approval request. - `arguments: string` - The action arguments as a JSON string. + A JSON string of arguments for the tool. - - `call_id: string` + - `name: string` - The unique ID linking this call to its output. + The name of the tool to run. - - `type: "multi_agent_call"` + - `server_label: string` - The item type. Always `multi_agent_call`. + The label of the MCP server making the request. - - `id: optional string` + - `type: "mcp_approval_request"` - The unique ID of this multi-agent call. + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` @@ -72434,1360 +83965,1325 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - - `"spawn_agent"` + A response to an MCP approval request. - - `"interrupt_agent"` + - `approval_request_id: string` - - `"list_agents"` + The ID of the approval request being answered. - - `"send_message"` + - `approve: boolean` - - `"followup_task"` + Whether the request was approved. - - `"wait_agent"` + - `type: "mcp_approval_response"` - - `call_id: string` + The type of the item. Always `mcp_approval_response`. - The unique ID of the multi-agent call. + - `id: optional string` - - `output: array of object { text, type, annotations }` + The unique ID of the approval response - Text output returned by the multi-agent action. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The text content. + - `agent_name: string` - - `type: "output_text"` + The canonical name of the agent that produced this item. - The content type. Always `output_text`. + - `reason: optional string` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + Optional reason for the decision. - Citations associated with the text content. + - `mcp_call: object { id, arguments, name, 7 more }` - - `union_member_0: array of object { file_id, filename, index, type }` + An invocation of a tool on an MCP server. - - `file_id: string` + - `id: string` - The ID of the file. + The unique ID of the tool call. - - `filename: string` + - `arguments: string` - The filename of the file cited. + A JSON string of the arguments passed to the tool. - - `index: number` + - `name: string` - The index of the file in the list of files. + The name of the tool that was run. - - `type: "file_citation"` + - `server_label: string` - The citation type. Always `file_citation`. + The label of the MCP server running the tool. - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + - `type: "mcp_call"` - - `end_index: number` + The type of the item. Always `mcp_call`. - The index of the last character of the citation in the message. + - `agent: optional object { agent_name }` - - `start_index: number` + The agent that produced this item. - The index of the first character of the citation in the message. + - `agent_name: string` - - `title: string` + The canonical name of the agent that produced this item. - The title of the cited resource. + - `approval_request_id: optional string` - - `type: "url_citation"` + 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. - The citation type. Always `url_citation`. + - `error: optional string` - - `url: string` + The error from the tool call, if any. - The URL of the cited resource. + - `output: optional string` - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + The output from the tool call. - - `container_id: string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The ID of the container. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `end_index: number` + - `"in_progress"` - The index of the last character of the citation in the message. + - `"completed"` - - `file_id: string` + - `"incomplete"` - The ID of the container file. + - `"calling"` - - `filename: string` + - `"failed"` - The filename of the container file cited. + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `start_index: number` + The output of a custom tool call from your code, being sent back to the model. - The index of the first character of the citation in the message. + - `call_id: string` - - `type: "container_file_citation"` + The call ID, used to map this custom tool call output to a custom tool call. - The citation type. Always `container_file_citation`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `type: "multi_agent_call_output"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The item type. Always `multi_agent_call_output`. + - `string output: string` - - `id: optional string` + A string of the output of the custom tool call. - The unique ID of this multi-agent call output. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `agent: optional object { agent_name }` + Text, image, or file output of the custom tool call. - The agent that produced this item. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `agent_name: string` + A text input to the model. - The canonical name of the agent that produced this item. + - `text: string` - - `tool_search_call: object { arguments, type, id, 4 more }` + The text input to the model. - - `arguments: unknown` + - `type: "input_text"` - The arguments supplied to the tool search call. + The type of the input item. Always `input_text`. - - `type: "tool_search_call"` + - `prompt_cache_breakpoint: optional object { mode }` - The item type. Always `tool_search_call`. + 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. - - `id: optional string` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The unique ID of this tool search call. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `agent: optional object { agent_name }` + - `detail: "low" or "high" or "auto" or "original"` - The agent that produced this item. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `agent_name: string` + - `type: "input_image"` - The canonical name of the agent that produced this item. + The type of the input item. Always `input_image`. - - `call_id: optional string` + - `file_id: optional string` - The unique ID of the tool search call generated by the model. + The ID of the file to be sent to the model. - - `execution: optional "server" or "client"` + - `image_url: optional string` - Whether tool search was executed by the server or by the client. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"server"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"client"` + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The status of the tool search call. + A file input to the model. - - `"in_progress"` + - `type: "input_file"` - - `"completed"` + The type of the input item. Always `input_file`. - - `"incomplete"` + - `detail: optional "auto" or "low" or "high"` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + 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`. - - `tools: array of BetaTool` + - `file_data: optional string` - The loaded tool definitions returned by the tool search output. + The content of the file to be sent to the model. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `file_id: optional string` - 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). + The ID of the file to be sent to the model. - - `name: string` + - `file_url: optional string` - The name of the function to call. + The URL of the file to be sent to the model. - - `parameters: map[unknown]` + - `filename: optional string` - A JSON schema object describing the parameters of the function. + The name of the file to be sent to the model. - - `strict: boolean` + - `prompt_cache_breakpoint: optional object { mode }` - Whether strict parameter validation is enforced for this function tool. + 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. - - `type: "function"` + - `type: "custom_tool_call_output"` - The type of the function tool. Always `function`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: optional string` - The tool invocation context(s). + The unique ID of the custom tool call output in the OpenAI platform. - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that produced this item. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this function is deferred and loaded via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `caller: optional object { type } or object { caller_id, type }` - A description of the function. Used by the model to determine whether or not to call the function. + The execution context that produced this tool call. - - `output_schema: optional map[unknown]` + - `direct: object { type }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `program: object { caller_id, type }` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `caller_id: string` - 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). + The call ID of the program item that produced this tool call. - - `type: "file_search"` + - `type: "program"` - The type of the file search tool. Always `file_search`. + The caller type. Always `program`. - - `vector_store_ids: array of string` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - The IDs of the vector stores to search. + A call to a custom tool created by the model. - - `filters: optional object { key, type, value } or object { filters, type }` + - `call_id: string` - A filter to apply. + An identifier used to map this custom tool call to a tool call output. - - `Comparison Filter: object { key, type, value }` + - `input: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The input for the custom tool call generated by the model. - - `key: string` + - `name: string` - The key to compare against the value. + The name of the custom tool being called. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "custom_tool_call"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the custom tool call. Always `custom_tool_call`. - - `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 + - `id: optional string` - - `"eq"` + The unique ID of the custom tool call in the OpenAI platform. - - `"ne"` + - `agent: optional object { agent_name }` - - `"gt"` + The agent that produced this item. - - `"gte"` + - `agent_name: string` - - `"lt"` + The canonical name of the agent that produced this item. - - `"lte"` + - `caller: optional object { type } or object { caller_id, type }` - - `"in"` + The execution context that produced this tool call. - - `"nin"` + - `direct: object { type }` - - `value: string or number or boolean or array of unknown` + - `program: object { caller_id, type }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `caller_id: string` - - `union_member_0: string` + The call ID of the program item that produced this tool call. - - `union_member_1: number` + - `type: "program"` - - `union_member_2: boolean` + - `namespace: optional string` - - `union_member_3: array of unknown` + The namespace of the custom tool being called. - - `Compound Filter: object { filters, type }` + - `compaction_trigger: object { type, agent }` - Combine multiple filters using `and` or `or`. + Compacts the current context. Must be the final input item. - - `filters: array of object { key, type, value } or unknown` + - `type: "compaction_trigger"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The type of the item. Always `compaction_trigger`. - - `Comparison Filter: object { key, type, value }` + - `agent: optional object { agent_name }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The agent that produced this item. - - `key: string` + - `agent_name: string` - The key to compare against the value. + The canonical name of the agent that produced this item. - - `type: "eq" or "ne" or "gt" or 5 more` + - `item_reference: object { id, agent, type }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + An internal identifier for an item to reference. - - `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 + - `id: string` - - `"eq"` + The ID of the item to reference. - - `"ne"` + - `agent: optional object { agent_name }` - - `"gt"` + The agent that produced this item. - - `"gte"` + - `agent_name: string` - - `"lt"` + The canonical name of the agent that produced this item. - - `"lte"` + - `type: optional "item_reference"` - - `"in"` + The type of item to reference. Always `item_reference`. - - `"nin"` + - `"item_reference"` - - `value: string or number or boolean or array of unknown` + - `program: object { id, call_id, code, 3 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `id: string` - - `union_member_0: string` + The unique ID of this program item. - - `union_member_1: number` + - `call_id: string` - - `union_member_2: boolean` + The stable call ID of the program item. - - `union_member_3: array of unknown` + - `code: string` - - `union_member_1: unknown` + The JavaScript source executed by programmatic tool calling. - - `type: "and" or "or"` + - `fingerprint: string` - Type of operation: `and` or `or`. + Opaque program replay fingerprint that must be round-tripped. - - `"and"` + - `type: "program"` - - `"or"` + The item type. Always `program`. - - `max_num_results: optional number` + - `agent: optional object { agent_name }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The agent that produced this item. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `agent_name: string` - Ranking options for search. + The canonical name of the agent that produced this item. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `program_output: object { id, call_id, result, 3 more }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `id: string` - - `embedding_weight: number` + The unique ID of this program output item. - The weight of the embedding in the reciprocal ranking fusion. + - `call_id: string` - - `text_weight: number` + The call ID of the program item. - The weight of the text in the reciprocal ranking fusion. + - `result: string` - - `ranker: optional "auto" or "default-2024-11-15"` + The result produced by the program item. - The ranker to use for the file search. + - `status: "completed" or "incomplete"` - - `"auto"` + The terminal status of the program output. - - `"default-2024-11-15"` + - `"completed"` - - `score_threshold: optional number` + - `"incomplete"` - 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. + - `type: "program_output"` - - `beta_computer_tool: object { type }` + The item type. Always `program_output`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent: optional object { agent_name }` - - `type: "computer"` + The agent that produced this item. - The type of the computer tool. Always `computer`. + - `agent_name: string` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +### Beta Response Input Message Content List - - `display_height: number` +- `beta_response_input_message_content_list: array of BetaResponseInputContent` - The height of the computer display. + A list of one or many input items to the model, containing different content + types. - - `display_width: number` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The width of the computer display. + A text input to the model. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `text: string` - The type of computer environment to control. + The text input to the model. - - `"windows"` + - `type: "input_text"` - - `"mac"` + The type of the input item. Always `input_text`. - - `"linux"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"ubuntu"` + 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. - - `"browser"` + - `mode: "explicit"` - - `type: "computer_use_preview"` + The breakpoint mode. Always `explicit`. - The type of the computer use tool. Always `computer_use_preview`. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - 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). + - `detail: "low" or "high" or "auto" or "original"` - - `type: "web_search" or "web_search_2025_08_26"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"low"` - - `"web_search"` + - `"high"` - - `"web_search_2025_08_26"` + - `"auto"` - - `filters: optional object { allowed_domains }` + - `"original"` - Filters for the search. + - `type: "input_image"` - - `allowed_domains: optional array of string` + The type of the input item. Always `input_image`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `file_id: optional string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The ID of the file to be sent to the model. - - `search_context_size: optional "low" or "medium" or "high"` + - `image_url: optional string` - 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. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"low"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"medium"` + 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. - - `"high"` + - `mode: "explicit"` - - `user_location: optional object { city, country, region, 2 more }` + The breakpoint mode. Always `explicit`. - The approximate location of the user. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `city: optional string` + A file input to the model. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "input_file"` - - `country: optional string` + The type of the input item. Always `input_file`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `detail: optional "auto" or "low" or "high"` - - `region: optional string` + 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`. - Free text input for the region of the user, e.g. `California`. + - `"auto"` - - `timezone: optional string` + - `"low"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"high"` - - `type: optional "approximate"` + - `file_data: optional string` - The type of location approximation. Always `approximate`. + The content of the file to be sent to the model. - - `"approximate"` + - `file_id: optional string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The ID of the file to be sent to the model. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `file_url: optional string` - - `server_label: string` + The URL of the file to be sent to the model. - A label for this MCP server, used to identify it in tool calls. + - `filename: optional string` - - `type: "mcp"` + The name of the file to be sent to the model. - The type of the MCP tool. Always `mcp`. + - `prompt_cache_breakpoint: optional object { mode }` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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. - The tool invocation context(s). + - `mode: "explicit"` - - `"direct"` + The breakpoint mode. Always `explicit`. - - `"programmatic"` +### Beta Response Input Message Item - - `allowed_tools: optional array of string or object { read_only, tool_names }` +- `beta_response_input_message_item: object { id, content, role, 3 more }` - List of allowed tool names or a filter object. + - `id: string` - - `MCP allowed tools: array of string` + The unique ID of the message input. - A string array of allowed tool names + - `content: array of BetaResponseInputContent` - - `MCP tool filter: object { read_only, tool_names }` + A list of one or many input items to the model, containing different content + types. - A filter object to specify which tools are allowed. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `read_only: optional boolean` + A text input to the model. - 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. + - `text: string` - - `tool_names: optional array of string` + The text input to the model. - List of allowed tool names. + - `type: "input_text"` - - `authorization: optional string` + The type of the input item. Always `input_text`. - 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. + - `prompt_cache_breakpoint: optional object { mode }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + 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. - 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). + - `mode: "explicit"` - Currently supported `connector_id` values are: + The breakpoint mode. Always `explicit`. - - 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` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"connector_dropbox"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"connector_gmail"` + - `detail: "low" or "high" or "auto" or "original"` - - `"connector_googlecalendar"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"connector_googledrive"` + - `"low"` - - `"connector_microsoftteams"` + - `"high"` - - `"connector_outlookcalendar"` + - `"auto"` - - `"connector_outlookemail"` + - `"original"` - - `"connector_sharepoint"` + - `type: "input_image"` - - `defer_loading: optional boolean` + The type of the input item. Always `input_image`. - Whether this MCP tool is deferred and discovered via tool search. + - `file_id: optional string` - - `headers: optional map[string]` + The ID of the file to be sent to the model. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `image_url: optional string` - - `require_approval: optional object { always, never } or "always" or "never"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Specify which of the MCP server's tools require approval. + - `prompt_cache_breakpoint: optional object { mode }` - - `MCP tool approval filter: object { always, never }` + 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. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `mode: "explicit"` - - `always: optional object { read_only, tool_names }` + The breakpoint mode. Always `explicit`. - A filter object to specify which tools are allowed. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `read_only: optional boolean` + A file input to the model. - 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. + - `type: "input_file"` - - `tool_names: optional array of string` + The type of the input item. Always `input_file`. - List of allowed tool names. + - `detail: optional "auto" or "low" or "high"` - - `never: optional object { read_only, tool_names }` + 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`. - A filter object to specify which tools are allowed. + - `"auto"` - - `read_only: optional boolean` + - `"low"` - 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. + - `"high"` - - `tool_names: optional array of string` + - `file_data: optional string` - List of allowed tool names. + The content of the file to be sent to the model. - - `MCP tool approval setting: "always" or "never"` + - `file_id: optional string` - 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. + The ID of the file to be sent to the model. - - `"always"` + - `file_url: optional string` - - `"never"` + The URL of the file to be sent to the model. - - `server_description: optional string` + - `filename: optional string` - Optional description of the MCP server, used to provide more context. + The name of the file to be sent to the model. - - `server_url: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + 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. - - `tunnel_id: optional string` + - `mode: "explicit"` - 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. + The breakpoint mode. Always `explicit`. - - `code_interpreter: object { container, type, allowed_callers }` + - `role: "user" or "system" or "developer"` - A tool that runs Python code to help generate a response to a prompt. + The role of the message input. One of `user`, `system`, or `developer`. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"user"` - 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. + - `"system"` - - `union_member_0: string` + - `"developer"` - The container ID. + - `type: "message"` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + The type of the message input. Always set to `message`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `agent: optional object { agent_name }` - - `type: "auto"` + The agent that produced this item. - Always `auto`. + - `agent_name: string` - - `file_ids: optional array of string` + The canonical name of the agent that produced this item. - An optional list of uploaded files to make available to your code. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The memory limit for the code interpreter container. + - `"in_progress"` - - `"1g"` + - `"completed"` - - `"4g"` + - `"incomplete"` - - `"16g"` +### Beta Response Input Text - - `"64g"` +- `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A text input to the model. - Network access policy for the container. + - `text: string` - - `beta_container_network_policy_disabled: object { type }` + The text input to the model. - - `type: "disabled"` + - `type: "input_text"` - Disable outbound network access. Always `disabled`. + The type of the input item. Always `input_text`. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `prompt_cache_breakpoint: optional object { mode }` - - `allowed_domains: array of string` + 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. - A list of allowed domains when type is `allowlist`. + - `mode: "explicit"` - - `type: "allowlist"` + The breakpoint mode. Always `explicit`. - Allow outbound network access only to specified domains. Always `allowlist`. +### Beta Response Input Text Content - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` +- `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - Optional domain-scoped secrets for allowlisted domains. + A text input to the model. - - `domain: string` + - `text: string` - The domain associated with the secret. + The text input to the model. - - `name: string` + - `type: "input_text"` - The name of the secret to inject for the domain. + The type of the input item. Always `input_text`. - - `value: string` + - `prompt_cache_breakpoint: optional object { mode }` - The secret value to inject for the domain. + 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. - - `type: "code_interpreter"` + - `mode: "explicit"` - The type of the code interpreter tool. Always `code_interpreter`. + The breakpoint mode. Always `explicit`. - - `allowed_callers: optional array of "direct" or "programmatic"` +### Beta Response Item - The tool invocation context(s). +- `beta_response_item: BetaResponseInputMessageItem or BetaResponseOutputMessage or BetaResponseFileSearchToolCall or 29 more` - - `"direct"` + Content item used to generate a response. - - `"programmatic"` + - `beta_response_input_message_item: object { id, content, role, 3 more }` - - `programmatic_tool_calling: object { type }` + - `id: string` - - `image_generation: object { type, action, background, 9 more }` + The unique ID of the message input. - A tool that generates images using the GPT image models. + - `content: array of BetaResponseInputContent` - - `type: "image_generation"` + A list of one or many input items to the model, containing different content + types. - The type of the image generation tool. Always `image_generation`. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `action: optional "generate" or "edit" or "auto"` + A text input to the model. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `text: string` - - `"generate"` + The text input to the model. - - `"edit"` + - `type: "input_text"` - - `"auto"` + The type of the input item. Always `input_text`. - - `background: optional "transparent" or "opaque" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - 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. + 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. - `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. + - `mode: "explicit"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The breakpoint mode. Always `explicit`. - - `"transparent"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"opaque"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"auto"` + - `detail: "low" or "high" or "auto" or "original"` - - `input_fidelity: optional "high" or "low"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - 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`. + - `"low"` - `"high"` - - `"low"` + - `"auto"` - - `input_image_mask: optional object { file_id, image_url }` + - `"original"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: "input_image"` + + The type of the input item. Always `input_image`. - `file_id: optional string` - File ID for the mask image. + The ID of the file to be sent to the model. - `image_url: optional string` - Base64-encoded mask image. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `prompt_cache_breakpoint: optional object { mode }` - The image generation model to use. Default: `gpt-image-1`. + 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. - - `"gpt-image-1"` + - `mode: "explicit"` - - `"gpt-image-1-mini"` + The breakpoint mode. Always `explicit`. - - `"gpt-image-2"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"gpt-image-2-2026-04-21"` + A file input to the model. - - `"gpt-image-1.5"` + - `type: "input_file"` - - `"chatgpt-image-latest"` + The type of the input item. Always `input_file`. - - `moderation: optional "auto" or "low"` + - `detail: optional "auto" or "low" or "high"` - Moderation level for the generated image. Default: `auto`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` - `"low"` - - `output_compression: optional number` + - `"high"` - Compression level for the output image. Default: 100. + - `file_data: optional string` - - `output_format: optional "png" or "webp" or "jpeg"` + The content of the file to be sent to the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `file_id: optional string` - - `"png"` + The ID of the file to be sent to the model. - - `"webp"` + - `file_url: optional string` - - `"jpeg"` + The URL of the file to be sent to the model. - - `partial_images: optional number` + - `filename: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The name of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + 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. - - `"low"` + - `mode: "explicit"` - - `"medium"` + The breakpoint mode. Always `explicit`. - - `"high"` + - `role: "user" or "system" or "developer"` - - `"auto"` + The role of the message input. One of `user`, `system`, or `developer`. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"user"` - 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`. + - `"system"` - - `"1024x1024"` + - `"developer"` - - `"1024x1536"` + - `type: "message"` - - `"1536x1024"` + The type of the message input. Always set to `message`. - - `"auto"` + - `agent: optional object { agent_name }` - - `local_shell: object { type }` + The agent that produced this item. - A tool that allows the model to execute shell commands in a local environment. + - `agent_name: string` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "shell"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the shell tool. Always `shell`. + - `"in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `beta_response_output_message: object { id, content, role, 4 more }` - - `"programmatic"` + An output message from the model. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `id: string` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + The unique ID of the output message. - - `type: "container_auto"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Automatically creates a container for this request + The content of the output message. - - `file_ids: optional array of string` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - An optional list of uploaded files to make available to your code. + A text output from the model. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The memory limit for the container. + The annotations of the text output. - - `"1g"` + - `file_citation: object { file_id, filename, index, type }` - - `"4g"` + A citation to a file. - - `"16g"` + - `file_id: string` - - `"64g"` + The ID of the file. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `filename: string` - Network access policy for the container. + The filename of the file cited. - - `beta_container_network_policy_disabled: object { type }` + - `index: number` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The index of the file in the list of files. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `type: "file_citation"` - An optional list of skills referenced by id or inline data. + The type of the file citation. Always `file_citation`. - - `beta_skill_reference: object { skill_id, type, version }` + - `url_citation: object { end_index, start_index, title, 2 more }` - - `skill_id: string` + A citation for a web resource used to generate a model response. - The ID of the referenced skill. + - `end_index: number` - - `type: "skill_reference"` + The index of the last character of the URL citation in the message. - References a skill created with the /v1/skills endpoint. + - `start_index: number` - - `version: optional string` + The index of the first character of the URL citation in the message. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `title: string` - - `beta_inline_skill: object { description, name, source, type }` + The title of the web resource. - - `description: string` + - `type: "url_citation"` - The description of the skill. + The type of the URL citation. Always `url_citation`. - - `name: string` + - `url: string` - The name of the skill. + The URL of the web resource. - - `source: object { data, media_type, type }` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - Inline skill payload + A citation for a container file used to generate a model response. - - `data: string` + - `container_id: string` - Base64-encoded skill zip bundle. + The ID of the container file. - - `media_type: "application/zip"` + - `end_index: number` - The media type of the inline skill payload. Must be `application/zip`. + The index of the last character of the container file citation in the message. - - `type: "base64"` + - `file_id: string` - The type of the inline skill source. Must be `base64`. + The ID of the file. - - `type: "inline"` + - `filename: string` - Defines an inline skill for this request. + The filename of the container file cited. - - `beta_local_environment: object { type, skills }` + - `start_index: number` - - `type: "local"` + The index of the first character of the container file citation in the message. - Use a local computer environment. + - `type: "container_file_citation"` - - `skills: optional array of BetaLocalSkill` + The type of the container file citation. Always `container_file_citation`. - An optional list of skills. + - `file_path: object { file_id, index, type }` - - `description: string` + A path to a file. - The description of the skill. + - `file_id: string` - - `name: string` + The ID of the file. - The name of the skill. + - `index: number` - - `path: string` + The index of the file in the list of files. - The path to the directory containing the skill. + - `type: "file_path"` - - `beta_container_reference: object { container_id, type }` + The type of the file path. Always `file_path`. - - `container_id: string` + - `text: string` - The ID of the referenced container. + The text output from the model. - - `type: "container_reference"` + - `type: "output_text"` - References a container created with the /v1/containers endpoint + The type of the output text. Always `output_text`. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - 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) + - `token: string` - - `name: string` + - `bytes: array of number` - The name of the custom tool, used to identify it in tool calls. + - `logprob: number` - - `type: "custom"` + - `top_logprobs: array of object { token, bytes, logprob }` - The type of the custom tool. Always `custom`. + - `token: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `bytes: array of number` - The tool invocation context(s). + - `logprob: number` - - `"direct"` + - `beta_response_output_refusal: object { refusal, type }` - - `"programmatic"` + A refusal from the model. - - `defer_loading: optional boolean` + - `refusal: string` - Whether this tool should be deferred and discovered via tool search. + The refusal explanation from the model. - - `description: optional string` + - `type: "refusal"` - Optional description of the custom tool, used to provide more context. + The type of the refusal. Always `refusal`. - - `format: optional object { type } or object { definition, syntax, type }` + - `role: "assistant"` - The input format for the custom tool. Default is unconstrained text. + The role of the output message. Always `assistant`. - - `text: object { type }` + - `status: "in_progress" or "completed" or "incomplete"` - Unconstrained free-form text. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `grammar: object { definition, syntax, type }` + - `"in_progress"` - A grammar defined by the user. + - `"completed"` - - `definition: string` + - `"incomplete"` - The grammar definition. + - `type: "message"` - - `syntax: "lark" or "regex"` + The type of the output message. Always `message`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent: optional object { agent_name }` - - `"lark"` + The agent that produced this item. - - `"regex"` + - `agent_name: string` - - `type: "grammar"` + The canonical name of the agent that produced this item. - Grammar format. Always `grammar`. + - `phase: optional "commentary" or "final_answer"` - - `beta_namespace_tool: object { description, name, tools, type }` + 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. - Groups function/custom tools under a shared namespace. + - `"commentary"` - - `description: string` + - `"final_answer"` - A description of the namespace shown to the model. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `name: string` + 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. - The namespace name used in tool calls (for example, `crm`). + - `id: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + The unique ID of the file search tool call. - The function/custom tools available inside this namespace. + - `queries: array of string` - - `function: object { name, type, allowed_callers, 5 more }` + The queries used to search for files. - - `name: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `type: "function"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"in_progress"` - The tool invocation context(s). + - `"searching"` - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `defer_loading: optional boolean` + - `"failed"` - Whether this function should be deferred and discovered via tool search. + - `type: "file_search_call"` - - `description: optional string` + The type of the file search tool call. Always `file_search_call`. - - `output_schema: optional map[unknown]` + - `agent: optional object { agent_name }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The agent that produced this item. - - `parameters: optional unknown` + - `agent_name: string` - - `strict: optional boolean` + The canonical name of the agent that produced this item. - 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. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The results of the file search tool call. - 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) + - `attributes: optional map[string or number or boolean]` - - `name: string` + 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. - The name of the custom tool, used to identify it in tool calls. + - `union_member_0: string` - - `type: "custom"` + - `union_member_1: number` - The type of the custom tool. Always `custom`. + - `union_member_2: boolean` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `file_id: optional string` - The tool invocation context(s). + The unique ID of the file. - - `defer_loading: optional boolean` + - `filename: optional string` - Whether this tool should be deferred and discovered via tool search. + The name of the file. - - `description: optional string` + - `score: optional number` - Optional description of the custom tool, used to provide more context. + The relevance score of the file - a value between 0 and 1. - - `format: optional object { type } or object { definition, syntax, type }` + - `text: optional string` - The input format for the custom tool. Default is unconstrained text. + The text that was retrieved from the file. - - `type: "namespace"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - The type of the tool. Always `namespace`. + 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. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `id: string` - Hosted or BYOT tool search configuration for deferred tools. + The unique ID of the computer call. - - `type: "tool_search"` + - `call_id: string` - The type of the tool. Always `tool_search`. + An identifier used when responding to the tool call with output. - - `description: optional string` + - `pending_safety_checks: array of object { id, code, message }` - Description shown to the model for a client-executed tool search tool. + The pending safety checks for the computer call. - - `execution: optional "server" or "client"` + - `id: string` - Whether tool search is executed by the server or by the client. + The ID of the pending safety check. - - `"server"` + - `code: optional string` - - `"client"` + The type of the pending safety check. - - `parameters: optional unknown` + - `message: optional string` - Parameter schema for a client-executed tool search tool. + Details about the pending safety check. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `status: "in_progress" or "completed" or "incomplete"` - 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). + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"in_progress"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"completed"` - - `"web_search_preview"` + - `"incomplete"` - - `"web_search_preview_2025_03_11"` + - `type: "computer_call"` - - `search_content_types: optional array of "text" or "image"` + The type of the computer call. Always `computer_call`. - - `"text"` + - `"computer_call"` - - `"image"` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `search_context_size: optional "low" or "medium" or "high"` + A click action. - 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. + - `click: object { button, type, x, 2 more }` - - `"low"` + A click action. - - `"medium"` + - `button: "left" or "right" or "wheel" or 2 more` - - `"high"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `user_location: optional object { type, city, country, 2 more }` + - `"left"` - The user's location. + - `"right"` - - `type: "approximate"` + - `"wheel"` - The type of location approximation. Always `approximate`. + - `"back"` - - `city: optional string` + - `"forward"` - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "click"` - - `country: optional string` + Specifies the event type. For a click action, this property is always `click`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `x: number` - - `region: optional string` + The x-coordinate where the click occurred. - Free text input for the region of the user, e.g. `California`. + - `y: number` - - `timezone: optional string` + The y-coordinate where the click occurred. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `keys: optional array of string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The keys being held while clicking. - Allows the assistant to create, delete, or update files using unified diffs. + - `double_click: object { keys, type, x, y }` - - `type: "apply_patch"` + A double click action. - The type of the tool. Always `apply_patch`. + - `keys: array of string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The keys being held while double-clicking. - The tool invocation context(s). + - `type: "double_click"` - - `"direct"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"programmatic"` + - `x: number` - - `type: "tool_search_output"` + The x-coordinate where the double click occurred. - The item type. Always `tool_search_output`. + - `y: number` - - `id: optional string` + The y-coordinate where the double click occurred. - The unique ID of this tool search output. + - `drag: object { path, type, keys }` - - `agent: optional object { agent_name }` + A drag action. - The agent that produced this item. + - `path: array of object { x, y }` - - `agent_name: string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The canonical name of the agent that produced this item. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `call_id: optional string` + - `x: number` - The unique ID of the tool search call generated by the model. + The x-coordinate. - - `execution: optional "server" or "client"` + - `y: number` - Whether tool search was executed by the server or by the client. + The y-coordinate. - - `"server"` + - `type: "drag"` - - `"client"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `keys: optional array of string` - The status of the tool search output. + The keys being held while dragging the mouse. - - `"in_progress"` + - `keypress: object { keys, type }` - - `"completed"` + A collection of keypresses the model would like to perform. - - `"incomplete"` + - `keys: array of string` - - `additional_tools: object { role, tools, type, 2 more }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `role: "developer"` + - `type: "keypress"` - The role that provided the additional tools. Only `developer` is supported. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `tools: array of BetaTool` + - `move: object { type, x, y, keys }` - A list of additional tools made available at this item. + A mouse move action. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `type: "move"` - 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). + Specifies the event type. For a move action, this property is always set to `move`. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `x: number` - 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). + The x-coordinate to move to. - - `beta_computer_tool: object { type }` + - `y: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The y-coordinate to move to. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `keys: optional array of string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The keys being held while moving the mouse. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `screenshot: object { type }` - 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). + A screenshot action. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + A scroll action. - - `code_interpreter: object { container, type, allowed_callers }` + - `scroll_x: number` - A tool that runs Python code to help generate a response to a prompt. + The horizontal scroll distance. - - `programmatic_tool_calling: object { type }` + - `scroll_y: number` - - `image_generation: object { type, action, background, 9 more }` + The vertical scroll distance. - A tool that generates images using the GPT image models. + - `type: "scroll"` - - `local_shell: object { type }` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - A tool that allows the model to execute shell commands in a local environment. + - `x: number` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The x-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands. + - `y: number` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The y-coordinate where the scroll occurred. - 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) + - `keys: optional array of string` - - `beta_namespace_tool: object { description, name, tools, type }` + The keys being held while scrolling. - Groups function/custom tools under a shared namespace. + - `type: object { text, type }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + An action to type in text. - Hosted or BYOT tool search configuration for deferred tools. + - `text: string` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The text to type. - 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"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + Specifies the event type. For a type action, this property is always set to `type`. - Allows the assistant to create, delete, or update files using unified diffs. + - `wait: object { type }` - - `type: "additional_tools"` + A wait action. - The item type. Always `additional_tools`. + - `actions: optional array of BetaComputerAction` - - `id: optional string` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The unique ID of this additional tools item. + - `click: object { button, type, x, 2 more }` - - `agent: optional object { agent_name }` + A click action. - The agent that produced this item. + - `double_click: object { keys, type, x, y }` - - `agent_name: string` + A double click action. - The canonical name of the agent that produced this item. + - `drag: object { path, type, keys }` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + A drag action. - 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). + - `keypress: object { keys, type }` - - `id: string` + A collection of keypresses the model would like to perform. - The unique identifier of the reasoning content. + - `move: object { type, x, y, keys }` - - `summary: array of object { text, type }` + A mouse move action. - Reasoning summary content. + - `screenshot: object { type }` - - `text: string` + A screenshot action. - A summary of the reasoning output from the model so far. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `type: "summary_text"` + A scroll action. - The type of the object. Always `summary_text`. + - `type: object { text, type }` - - `type: "reasoning"` + An action to type in text. - The type of the object. Always `reasoning`. + - `wait: object { type }` + + A wait action. - `agent: optional object { agent_name }` @@ -73797,156 +85293,164 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - Reasoning text content. + - `id: string` - - `text: string` + The unique ID of the computer call tool output. - The reasoning text from the model. + - `call_id: string` - - `type: "reasoning_text"` + The ID of the computer tool call that produced the output. - The type of the reasoning text. Always `reasoning_text`. + - `output: object { type, file_id, image_url }` - - `encrypted_content: optional string` + A computer screenshot image used with the computer use tool. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: "computer_screenshot"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_id: optional string` - - `"in_progress"` + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - `"incomplete"` - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `"failed"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `"in_progress"` - - `encrypted_content: string` + - `type: "computer_call_output"` - The encrypted content of the compaction summary. + The type of the computer tool call output. Always `computer_call_output`. - - `type: "compaction"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The type of the item. Always `compaction`. + The safety checks reported by the API that have been acknowledged by the + developer. - - `id: optional string` + - `id: string` - The ID of the compaction item. + The ID of the pending safety check. - - `agent: optional object { agent_name }` + - `code: optional string` - The agent that produced this item. + The type of the pending safety check. - - `agent_name: string` + - `message: optional string` - The canonical name of the agent that produced this item. + Details about the pending safety check. - - `image_generation_call: object { id, result, status, 2 more }` + - `agent: optional object { agent_name }` - An image generation request made by the model. + The agent that produced this item. - - `id: string` + - `agent_name: string` - The unique ID of the image generation call. + The canonical name of the agent that produced this item. - - `result: string` + - `created_by: optional string` - The generated image encoded in base64. + The identifier of the actor that created the item. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - The status of the image generation call. + 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. - - `"in_progress"` + - `id: string` - - `"completed"` + The unique ID of the web search tool call. - - `"generating"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"failed"` + 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). - - `type: "image_generation_call"` + - `search: object { type, queries, query, sources }` - The type of the image generation call. Always `image_generation_call`. + Action type "search" - Performs a web search query. - - `agent: optional object { agent_name }` + - `type: "search"` - The agent that produced this item. + The action type. - - `agent_name: string` + - `queries: optional array of string` - The canonical name of the agent that produced this item. + The search queries. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `query: optional string` - A tool call to run code. + The search query. - - `id: string` + - `sources: optional array of object { type, url }` - The unique ID of the code interpreter tool call. + The sources used in the search. - - `code: string` + - `type: "url"` - The code to run, or null if not available. + The type of source. Always `url`. - - `container_id: string` + - `url: string` - The ID of the container used to run the code. + The URL of the source. - - `outputs: array of object { logs, type } or object { type, url }` + - `open_page: object { type, url }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Action type "open_page" - Opens a specific URL from search results. - - `logs: object { logs, type }` + - `type: "open_page"` - The logs output from the code interpreter. + The action type. - - `logs: string` + - `url: optional string` - The logs output from the code interpreter. + The URL opened by the model. - - `type: "logs"` + - `find_in_page: object { pattern, type, url }` - The type of the output. Always `logs`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `image: object { type, url }` + - `pattern: string` - The image output from the code interpreter. + The pattern or text to search for within the page. - - `type: "image"` + - `type: "find_in_page"` - The type of the output. Always `image`. + The action type. - `url: string` - The URL of the image output from the code interpreter. + The URL of the page searched for the pattern. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the web search tool call. - `"in_progress"` - - `"completed"` - - - `"incomplete"` + - `"searching"` - - `"interpreting"` + - `"completed"` - `"failed"` - - `type: "code_interpreter_call"` + - `type: "web_search_call"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the web search tool call. Always `web_search_call`. - `agent: optional object { agent_name }` @@ -73956,133 +85460,139 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` - A tool call to run a command on the local shell. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `id: string` - The unique ID of the local shell call. + The unique ID of the function tool call. - - `action: object { command, env, type, 3 more }` + - `status: "in_progress" or "completed" or "incomplete"` - Execute a shell command on the server. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `command: array of string` + - `"in_progress"` - The command to run. + - `"completed"` - - `env: map[string]` + - `"incomplete"` - Environment variables to set for the command. + - `created_by: optional string` - - `type: "exec"` + The identifier of the actor that created the item. - The type of the local shell action. Always `exec`. + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `timeout_ms: optional number` + - `id: string` - Optional timeout in milliseconds for the command. + The unique ID of the function call tool output. - - `user: optional string` + - `call_id: string` - Optional user to run the command as. + The unique ID of the function tool call generated by the model. - - `working_directory: optional string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Optional working directory to run the command in. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `call_id: string` + - `string output: string` - The unique ID of the local shell tool call generated by the model. + A string of the output of the function call. - - `status: "in_progress" or "completed" or "incomplete"` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The status of the local shell call. + Text, image, or file output of the function call. - - `"in_progress"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"completed"` + A text input to the model. - - `"incomplete"` + - `text: string` - - `type: "local_shell_call"` + The text input to the model. - The type of the local shell call. Always `local_shell_call`. + - `type: "input_text"` - - `agent: optional object { agent_name }` + The type of the input item. Always `input_text`. - The agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `local_shell_call_output: object { id, output, type, 2 more }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The output of a local shell tool call. + - `detail: "low" or "high" or "auto" or "original"` - - `id: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The unique ID of the local shell tool call generated by the model. + - `type: "input_image"` - - `output: string` + The type of the input item. Always `input_image`. - A JSON string of the output of the local shell tool call. + - `file_id: optional string` - - `type: "local_shell_call_output"` + The ID of the file to be sent to the model. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `image_url: optional string` - - `agent: optional object { agent_name }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A file input to the model. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `type: "input_file"` - - `"in_progress"` + The type of the input item. Always `input_file`. - - `"completed"` + - `detail: optional "auto" or "low" or "high"` - - `"incomplete"` + 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`. - - `shell_call: object { action, call_id, type, 5 more }` + - `file_data: optional string` - A tool representing a request to execute one or more shell commands. + The content of the file to be sent to the model. - - `action: object { commands, max_output_length, timeout_ms }` + - `file_id: optional string` - The shell commands and limits that describe how to run the tool call. + The ID of the file to be sent to the model. - - `commands: array of string` + - `file_url: optional string` - Ordered shell commands for the execution environment to run. + The URL of the file to be sent to the model. - - `max_output_length: optional number` + - `filename: optional string` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + The name of the file to be sent to the model. - - `timeout_ms: optional number` + - `prompt_cache_breakpoint: optional object { mode }` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + 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. - - `call_id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the shell tool call generated by the model. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "shell_call"` + - `"in_progress"` - The type of the item. Always `shell_call`. + - `"completed"` - - `id: optional string` + - `"incomplete"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` @@ -74108,181 +85618,131 @@ openai beta:responses compact \ The caller type. Always `program`. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `beta_local_environment: object { type, skills }` - - - `beta_container_reference: object { container_id, type }` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `shell_call_output: object { call_id, output, type, 5 more }` - - The streamed output items emitted by a shell tool call. - - - `call_id: string` - - The unique ID of the shell tool call generated by the model. - - - `output: array of BetaResponseFunctionShellCallOutputContent` - - Captured chunks of stdout and stderr output, along with their associated outcomes. - - - `outcome: object { type } or object { exit_code, type }` - - The exit or timeout outcome associated with this shell call. - - - `timeout: object { type }` - - Indicates that the shell call exceeded its configured time limit. - - - `exit: object { exit_code, type }` - - Indicates that the shell commands finished and returned an exit code. - - - `exit_code: number` - - The exit code returned by the shell process. - - - `type: "exit"` - - The outcome type. Always `exit`. - - - `stderr: string` + - `created_by: optional string` - Captured stderr output for the shell call. + The identifier of the actor that created the item. - - `stdout: string` + - `agent_message: object { id, author, content, 3 more }` - Captured stdout output for the shell call. + - `id: string` - - `type: "shell_call_output"` + The unique ID of the agent message. - The type of the item. Always `shell_call_output`. + - `author: string` - - `id: optional string` + The sending agent identity. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `agent: optional object { agent_name }` + Encrypted content sent between agents. - The agent that produced this item. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `agent_name: string` + A text input to the model. - The canonical name of the agent that produced this item. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `caller: optional object { type } or object { caller_id, type }` + A text output from the model. - The execution context that produced this tool call. + - `text: object { text, type }` - - `direct: object { type }` + A text content. - - `program: object { caller_id, type }` + - `text: string` - - `caller_id: string` + - `type: "text"` - The call ID of the program item that produced this tool call. + - `summary_text: object { text, type }` - - `type: "program"` + A summary text from the model. - The caller type. Always `program`. + - `text: string` - - `max_output_length: optional number` + A summary of the reasoning output from the model so far. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `type: "summary_text"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the object. Always `summary_text`. - The status of the shell call output. + - `reasoning_text: object { text, type }` - - `"in_progress"` + Reasoning text from the model. - - `"completed"` + - `text: string` - - `"incomplete"` + The reasoning text from the model. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `type: "reasoning_text"` - A tool call representing a request to create, delete, or update files using diff patches. + The type of the reasoning text. Always `reasoning_text`. - - `call_id: string` + - `beta_response_output_refusal: object { refusal, type }` - The unique ID of the apply patch tool call generated by the model. + A refusal from the model. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The specific create, delete, or update instruction for the apply_patch tool call. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `create_file: object { diff, path, type }` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - Instruction for creating a new file via the apply_patch tool. + A screenshot of a computer. - - `diff: string` + - `detail: "low" or "high" or "auto" or "original"` - Unified diff content to apply when creating the file. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `path: string` + - `"low"` - Path of the file to create relative to the workspace root. + - `"high"` - - `type: "create_file"` + - `"auto"` - The operation type. Always `create_file`. + - `"original"` - - `delete_file: object { path, type }` + - `file_id: string` - Instruction for deleting an existing file via the apply_patch tool. + The identifier of an uploaded file that contains the screenshot. - - `path: string` + - `image_url: string` - Path of the file to delete relative to the workspace root. + The URL of the screenshot image. - - `type: "delete_file"` + - `type: "computer_screenshot"` - The operation type. Always `delete_file`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `update_file: object { diff, path, type }` + - `prompt_cache_breakpoint: optional object { mode }` - Instruction for updating an existing file via the apply_patch tool. + 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. - - `diff: string` + - `mode: "explicit"` - Unified diff content to apply to the existing file. + The breakpoint mode. Always `explicit`. - - `path: string` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - Path of the file to update relative to the workspace root. + A file input to the model. - - `type: "update_file"` + - `encrypted_content: object { encrypted_content, type }` - The operation type. Always `update_file`. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `status: "in_progress" or "completed"` + - `encrypted_content: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Opaque encrypted content. - - `"in_progress"` + - `type: "encrypted_content"` - - `"completed"` + The type of the input item. Always `encrypted_content`. - - `type: "apply_patch_call"` + - `recipient: string` - The type of the item. Always `apply_patch_call`. + The destination agent identity. - - `id: optional string` + - `type: "agent_message"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of the item. Always `agent_message`. - `agent: optional object { agent_name }` @@ -74292,45 +85752,39 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `caller_id: string` + - `id: string` - The call ID of the program item that produced this tool call. + The unique ID of the multi-agent call item. - - `type: "program"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The caller type. Always `program`. + The multi-agent action to execute. - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `"spawn_agent"` - The streamed output emitted by an apply patch tool call. + - `"interrupt_agent"` - - `call_id: string` + - `"list_agents"` - The unique ID of the apply patch tool call generated by the model. + - `"send_message"` - - `status: "completed" or "failed"` + - `"followup_task"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"wait_agent"` - - `"completed"` + - `arguments: string` - - `"failed"` + The JSON string of arguments generated for the action. - - `type: "apply_patch_call_output"` + - `call_id: string` - The type of the item. Always `apply_patch_call_output`. + The unique ID linking this call to its output. - - `id: optional string` + - `type: "multi_agent_call"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` @@ -74340,61 +85794,53 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - The call ID of the program item that produced this tool call. + - `id: string` - - `type: "program"` + The unique ID of the multi-agent call output item. - The caller type. Always `program`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `output: optional string` + The multi-agent action that produced this result. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `"spawn_agent"` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `"interrupt_agent"` - A list of tools available on an MCP server. + - `"list_agents"` - - `id: string` + - `"send_message"` - The unique ID of the list. + - `"followup_task"` - - `server_label: string` + - `"wait_agent"` - The label of the MCP server. + - `call_id: string` - - `tools: array of object { input_schema, name, annotations, description }` + The unique ID of the multi-agent call. - The tools available on the server. + - `output: array of BetaResponseOutputText` - - `input_schema: unknown` + Text output returned by the multi-agent action. - The JSON schema describing the tool's input. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `name: string` + The annotations of the text output. - The name of the tool. + - `text: string` - - `annotations: optional unknown` + The text output from the model. - Additional annotations about the tool. + - `type: "output_text"` - - `description: optional string` + The type of the output text. Always `output_text`. - The description of the tool. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "mcp_list_tools"` + - `type: "multi_agent_call_output"` - The type of the item. Always `mcp_list_tools`. + The type of the multi-agent result. Always `multi_agent_call_output`. - `agent: optional object { agent_name }` @@ -74404,33 +85850,41 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `error: optional string` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - Error message if the server could not list tools. + - `id: string` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The unique ID of the tool search call item. - A request for human approval of a tool invocation. + - `arguments: unknown` - - `id: string` + Arguments used for the tool search call. - The unique ID of the approval request. + - `call_id: string` - - `arguments: string` + The unique ID of the tool search call generated by the model. - A JSON string of arguments for the tool. + - `execution: "server" or "client"` - - `name: string` + Whether tool search was executed by the server or by the client. - The name of the tool to run. + - `"server"` - - `server_label: string` + - `"client"` - The label of the MCP server making the request. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "mcp_approval_request"` + The status of the tool search call item that was recorded. - The type of the item. Always `mcp_approval_request`. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -74440,1133 +85894,1193 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + - `created_by: optional string` - A response to an MCP approval request. + The identifier of the actor that created the item. - - `approval_request_id: string` + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - The ID of the approval request being answered. + - `id: string` - - `approve: boolean` + The unique ID of the tool search output item. - Whether the request was approved. + - `call_id: string` - - `type: "mcp_approval_response"` + The unique ID of the tool search call generated by the model. - The type of the item. Always `mcp_approval_response`. + - `execution: "server" or "client"` - - `id: optional string` + Whether tool search was executed by the server or by the client. - The unique ID of the approval response + - `"server"` - - `agent: optional object { agent_name }` + - `"client"` - The agent that produced this item. + - `status: "in_progress" or "completed" or "incomplete"` - - `agent_name: string` + The status of the tool search output item that was recorded. - The canonical name of the agent that produced this item. + - `"in_progress"` - - `reason: optional string` + - `"completed"` - Optional reason for the decision. + - `"incomplete"` - - `mcp_call: object { id, arguments, name, 7 more }` + - `tools: array of BetaTool` - An invocation of a tool on an MCP server. + The loaded tool definitions returned by tool search. - - `id: string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The unique ID of the tool call. + 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). - - `arguments: string` + - `name: string` - A JSON string of the arguments passed to the tool. + The name of the function to call. - - `name: string` + - `parameters: map[unknown]` - The name of the tool that was run. + A JSON schema object describing the parameters of the function. - - `server_label: string` + - `strict: boolean` - The label of the MCP server running the tool. + Whether strict parameter validation is enforced for this function tool. - - `type: "mcp_call"` + - `type: "function"` - The type of the item. Always `mcp_call`. + The type of the function tool. Always `function`. - - `agent: optional object { agent_name }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The agent that produced this item. + The tool invocation context(s). - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `"programmatic"` - - `approval_request_id: optional string` + - `defer_loading: optional boolean` - 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. + Whether this function is deferred and loaded via tool search. - - `error: optional string` + - `description: optional string` - The error from the tool call, if any. + A description of the function. Used by the model to determine whether or not to call the function. - - `output: optional string` + - `output_schema: optional map[unknown]` - The output from the tool call. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + 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). - - `"in_progress"` + - `type: "file_search"` - - `"completed"` + The type of the file search tool. Always `file_search`. - - `"incomplete"` + - `vector_store_ids: array of string` - - `"calling"` + The IDs of the vector stores to search. - - `"failed"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + A filter to apply. - The output of a custom tool call from your code, being sent back to the model. + - `Comparison Filter: object { key, type, value }` - - `call_id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The call ID, used to map this custom tool call output to a custom tool call. + - `key: string` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The key to compare against the value. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `type: "eq" or "ne" or "gt" or 5 more` - - `string output: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A string of the output of the custom tool call. + - `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 - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"eq"` - Text, image, or file output of the custom tool call. + - `"ne"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"gt"` - A text input to the model. + - `"gte"` - - `text: string` + - `"lt"` - The text input to the model. + - `"lte"` - - `type: "input_text"` + - `"in"` - The type of the input item. Always `input_text`. + - `"nin"` - - `prompt_cache_breakpoint: optional object { mode }` + - `value: string or number or boolean or array of string or number` - 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. + The value to compare against the attribute key; supports string, number, or boolean types. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `union_member_0: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `union_member_1: number` - - `detail: "low" or "high" or "auto" or "original"` + - `union_member_2: boolean` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `union_member_3: array of string or number` - - `type: "input_image"` + - `union_member_0: string` - The type of the input item. Always `input_image`. + - `union_member_1: number` - - `file_id: optional string` + - `Compound Filter: object { filters, type }` - The ID of the file to be sent to the model. + Combine multiple filters using `and` or `or`. - - `image_url: optional string` + - `filters: array of object { key, type, value } or unknown` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `prompt_cache_breakpoint: optional object { mode }` + - `Comparison Filter: object { key, type, value }` - 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. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `key: string` - A file input to the model. + The key to compare against the value. - - `type: "input_file"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of the input item. Always `input_file`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `detail: optional "auto" or "low" or "high"` + - `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 - 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`. + - `"eq"` - - `file_data: optional string` + - `"ne"` - The content of the file to be sent to the model. + - `"gt"` - - `file_id: optional string` + - `"gte"` - The ID of the file to be sent to the model. + - `"lt"` - - `file_url: optional string` + - `"lte"` - The URL of the file to be sent to the model. + - `"in"` - - `filename: optional string` + - `"nin"` - The name of the file to be sent to the model. + - `value: string or number or boolean or array of string or number` - - `prompt_cache_breakpoint: optional object { mode }` + The value to compare against the attribute key; supports string, number, or boolean types. - 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. + - `union_member_0: string` - - `type: "custom_tool_call_output"` + - `union_member_1: number` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `union_member_2: boolean` - - `id: optional string` + - `union_member_3: array of string or number` - The unique ID of the custom tool call output in the OpenAI platform. + - `union_member_0: string` - - `agent: optional object { agent_name }` + - `union_member_1: number` - The agent that produced this item. + - `union_member_1: unknown` - - `agent_name: string` + - `type: "and" or "or"` - The canonical name of the agent that produced this item. + Type of operation: `and` or `or`. - - `caller: optional object { type } or object { caller_id, type }` + - `"and"` - The execution context that produced this tool call. + - `"or"` - - `direct: object { type }` + - `max_num_results: optional number` - - `program: object { caller_id, type }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `caller_id: string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The call ID of the program item that produced this tool call. + Ranking options for search. - - `type: "program"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The caller type. Always `program`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `embedding_weight: number` - A call to a custom tool created by the model. + The weight of the embedding in the reciprocal ranking fusion. - - `call_id: string` + - `text_weight: number` - An identifier used to map this custom tool call to a tool call output. + The weight of the text in the reciprocal ranking fusion. - - `input: string` + - `ranker: optional "auto" or "default-2024-11-15"` - The input for the custom tool call generated by the model. + The ranker to use for the file search. - - `name: string` + - `"auto"` - The name of the custom tool being called. + - `"default-2024-11-15"` - - `type: "custom_tool_call"` + - `score_threshold: optional number` - The type of the custom tool call. Always `custom_tool_call`. + 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. - - `id: optional string` + - `beta_computer_tool: object { type }` - The unique ID of the custom tool call in the OpenAI platform. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent: optional object { agent_name }` + - `type: "computer"` - The agent that produced this item. + The type of the computer tool. Always `computer`. - - `agent_name: string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `caller: optional object { type } or object { caller_id, type }` + - `display_height: number` - The execution context that produced this tool call. + The height of the computer display. - - `direct: object { type }` + - `display_width: number` - - `program: object { caller_id, type }` + The width of the computer display. - - `caller_id: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The call ID of the program item that produced this tool call. + The type of computer environment to control. - - `type: "program"` + - `"windows"` - - `namespace: optional string` + - `"mac"` - The namespace of the custom tool being called. + - `"linux"` - - `compaction_trigger: object { type, agent }` + - `"ubuntu"` - Compacts the current context. Must be the final input item. + - `"browser"` - - `type: "compaction_trigger"` + - `type: "computer_use_preview"` - The type of the item. Always `compaction_trigger`. + The type of the computer use tool. Always `computer_use_preview`. - - `agent: optional object { agent_name }` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The agent that produced this item. + 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). - - `agent_name: string` + - `type: "web_search" or "web_search_2025_08_26"` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `item_reference: object { id, agent, type }` + - `"web_search"` - An internal identifier for an item to reference. + - `"web_search_2025_08_26"` - - `id: string` + - `filters: optional object { allowed_domains }` - The ID of the item to reference. + Filters for the search. - - `agent: optional object { agent_name }` + - `allowed_domains: optional array of string` - The agent that produced this item. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `agent_name: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The canonical name of the agent that produced this item. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: optional "item_reference"` + 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. - The type of item to reference. Always `item_reference`. + - `"low"` - - `"item_reference"` + - `"medium"` - - `program: object { id, call_id, code, 3 more }` + - `"high"` - - `id: string` + - `user_location: optional object { city, country, region, 2 more }` - The unique ID of this program item. + The approximate location of the user. - - `call_id: string` + - `city: optional string` - The stable call ID of the program item. + Free text input for the city of the user, e.g. `San Francisco`. - - `code: string` + - `country: optional string` - The JavaScript source executed by programmatic tool calling. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `fingerprint: string` + - `region: optional string` - Opaque program replay fingerprint that must be round-tripped. + Free text input for the region of the user, e.g. `California`. - - `type: "program"` + - `timezone: optional string` - The item type. Always `program`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `agent: optional object { agent_name }` + - `type: optional "approximate"` - The agent that produced this item. + The type of location approximation. Always `approximate`. - - `agent_name: string` + - `"approximate"` - The canonical name of the agent that produced this item. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `program_output: object { id, call_id, result, 3 more }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `id: string` + - `server_label: string` - The unique ID of this program output item. + A label for this MCP server, used to identify it in tool calls. - - `call_id: string` + - `type: "mcp"` - The call ID of the program item. + The type of the MCP tool. Always `mcp`. - - `result: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The result produced by the program item. + The tool invocation context(s). - - `status: "completed" or "incomplete"` + - `"direct"` - The terminal status of the program output. + - `"programmatic"` - - `"completed"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"incomplete"` + List of allowed tool names or a filter object. - - `type: "program_output"` + - `MCP allowed tools: array of string` - The item type. Always `program_output`. + A string array of allowed tool names - - `agent: optional object { agent_name }` + - `MCP tool filter: object { read_only, tool_names }` - The agent that produced this item. + A filter object to specify which tools are allowed. - - `agent_name: string` + - `read_only: optional boolean` - The canonical name of the agent that produced this item. + 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. - - `metadata: map[string]` + - `tool_names: optional array of string` - 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. + List of allowed tool names. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `authorization: optional string` - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - Model ID used to generate the response, like `gpt-4o` 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. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"gpt-5.6-sol"` + 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). - - `"gpt-5.6-terra"` + Currently supported `connector_id` values are: - - `"gpt-5.6-luna"` + - 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` - - `"gpt-5.4"` + - `"connector_dropbox"` - - `"gpt-5.4-mini"` + - `"connector_gmail"` - - `"gpt-5.4-nano"` + - `"connector_googlecalendar"` - - `"gpt-5.4-mini-2026-03-17"` + - `"connector_googledrive"` - - `"gpt-5.4-nano-2026-03-17"` + - `"connector_microsoftteams"` - - `"gpt-5.3-chat-latest"` + - `"connector_outlookcalendar"` - - `"gpt-5.2"` + - `"connector_outlookemail"` - - `"gpt-5.2-2025-12-11"` + - `"connector_sharepoint"` - - `"gpt-5.2-chat-latest"` + - `defer_loading: optional boolean` - - `"gpt-5.2-pro"` + Whether this MCP tool is deferred and discovered via tool search. - - `"gpt-5.2-pro-2025-12-11"` + - `headers: optional map[string]` - - `"gpt-5.1"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"gpt-5.1-2025-11-13"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"gpt-5.1-codex"` + Specify which of the MCP server's tools require approval. - - `"gpt-5.1-mini"` + - `MCP tool approval filter: object { always, never }` - - `"gpt-5.1-chat-latest"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"gpt-5"` + - `always: optional object { read_only, tool_names }` - - `"gpt-5-mini"` + A filter object to specify which tools are allowed. - - `"gpt-5-nano"` + - `read_only: optional boolean` - - `"gpt-5-2025-08-07"` + 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. - - `"gpt-5-mini-2025-08-07"` + - `tool_names: optional array of string` - - `"gpt-5-nano-2025-08-07"` + List of allowed tool names. - - `"gpt-5-chat-latest"` + - `never: optional object { read_only, tool_names }` - - `"gpt-4.1"` + A filter object to specify which tools are allowed. - - `"gpt-4.1-mini"` + - `read_only: optional boolean` - - `"gpt-4.1-nano"` + 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. - - `"gpt-4.1-2025-04-14"` + - `tool_names: optional array of string` - - `"gpt-4.1-mini-2025-04-14"` + List of allowed tool names. - - `"gpt-4.1-nano-2025-04-14"` + - `MCP tool approval setting: "always" or "never"` - - `"o4-mini"` + 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. - - `"o4-mini-2025-04-16"` + - `"always"` - - `"o3"` + - `"never"` - - `"o3-2025-04-16"` + - `server_description: optional string` - - `"o3-mini"` + Optional description of the MCP server, used to provide more context. - - `"o3-mini-2025-01-31"` + - `server_url: optional string` - - `"o1"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"o1-2024-12-17"` + - `tunnel_id: optional string` - - `"o1-preview"` + 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. - - `"o1-preview-2024-09-12"` + - `code_interpreter: object { container, type, allowed_callers }` - - `"o1-mini"` + A tool that runs Python code to help generate a response to a prompt. - - `"o1-mini-2024-09-12"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"gpt-4o"` + 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. - - `"gpt-4o-2024-11-20"` + - `union_member_0: string` - - `"gpt-4o-2024-08-06"` + The container ID. - - `"gpt-4o-2024-05-13"` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `"gpt-4o-audio-preview"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"gpt-4o-audio-preview-2024-10-01"` + - `type: "auto"` - - `"gpt-4o-audio-preview-2024-12-17"` + Always `auto`. - - `"gpt-4o-audio-preview-2025-06-03"` + - `file_ids: optional array of string` - - `"gpt-4o-mini-audio-preview"` + An optional list of uploaded files to make available to your code. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"gpt-4o-search-preview"` + The memory limit for the code interpreter container. - - `"gpt-4o-mini-search-preview"` + - `"1g"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"4g"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"16g"` - - `"chatgpt-4o-latest"` + - `"64g"` - - `"codex-mini-latest"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"gpt-4o-mini"` + Network access policy for the container. - - `"gpt-4o-mini-2024-07-18"` + - `beta_container_network_policy_disabled: object { type }` - - `"gpt-4-turbo"` + - `type: "disabled"` - - `"gpt-4-turbo-2024-04-09"` + Disable outbound network access. Always `disabled`. - - `"gpt-4-0125-preview"` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `"gpt-4-turbo-preview"` + - `allowed_domains: array of string` - - `"gpt-4-1106-preview"` + A list of allowed domains when type is `allowlist`. - - `"gpt-4-vision-preview"` + - `type: "allowlist"` - - `"gpt-4"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"gpt-4-0314"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"gpt-4-0613"` + Optional domain-scoped secrets for allowlisted domains. - - `"gpt-4-32k"` + - `domain: string` - - `"gpt-4-32k-0314"` + The domain associated with the secret. - - `"gpt-4-32k-0613"` + - `name: string` - - `"gpt-3.5-turbo"` + The name of the secret to inject for the domain. - - `"gpt-3.5-turbo-16k"` + - `value: string` - - `"gpt-3.5-turbo-0301"` + The secret value to inject for the domain. - - `"gpt-3.5-turbo-0613"` + - `type: "code_interpreter"` - - `"gpt-3.5-turbo-1106"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"gpt-3.5-turbo-0125"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-3.5-turbo-16k-0613"` + The tool invocation context(s). - - `"o1-pro"` + - `"direct"` - - `"o1-pro-2025-03-19"` + - `"programmatic"` - - `"o3-pro"` + - `programmatic_tool_calling: object { type }` - - `"o3-pro-2025-06-10"` + - `image_generation: object { type, action, background, 9 more }` - - `"o3-deep-research"` + A tool that generates images using the GPT image models. - - `"o3-deep-research-2025-06-26"` + - `type: "image_generation"` - - `"o4-mini-deep-research"` + The type of the image generation tool. Always `image_generation`. - - `"o4-mini-deep-research-2025-06-26"` + - `action: optional "generate" or "edit" or "auto"` - - `"computer-use-preview"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"computer-use-preview-2025-03-11"` + - `"generate"` - - `"gpt-5-codex"` + - `"edit"` - - `"gpt-5-pro"` + - `"auto"` - - `"gpt-5-pro-2025-10-06"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"gpt-5.1-codex-max"` + 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. - - `object: "response"` + `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. - The object type of this resource - always set to `response`. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `output: array of BetaResponseOutputItem` + - `"transparent"` - An array of content items generated by the model. + - `"opaque"` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `"auto"` - - `beta_response_output_message: object { id, content, role, 4 more }` + - `input_fidelity: optional "high" or "low"` - An output message from the model. + 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`. - - `id: string` + - `"high"` - The unique ID of the output message. + - `"low"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `input_image_mask: optional object { file_id, image_url }` - The content of the output message. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `role: "assistant"` + - `file_id: optional string` - The role of the output message. Always `assistant`. + File ID for the mask image. - - `status: "in_progress" or "completed" or "incomplete"` + - `image_url: optional string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Base64-encoded mask image. - - `type: "message"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - The type of the output message. Always `message`. + The image generation model to use. Default: `gpt-image-1`. - - `agent: optional object { agent_name }` + - `"gpt-image-1"` - The agent that produced this item. + - `"gpt-image-1-mini"` - - `phase: optional "commentary"` + - `"gpt-image-2"` - 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. + - `"gpt-image-2-2026-04-21"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `"gpt-image-1.5"` - 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. + - `"chatgpt-image-latest"` - - `id: string` + - `moderation: optional "auto" or "low"` - The unique ID of the file search tool call. + Moderation level for the generated image. Default: `auto`. - - `queries: array of string` + - `"auto"` - The queries used to search for files. + - `"low"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `output_compression: optional number` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Compression level for the output image. Default: 100. - - `type: "file_search_call"` + - `output_format: optional "png" or "webp" or "jpeg"` - The type of the file search tool call. Always `file_search_call`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `agent: optional object { agent_name }` + - `"png"` - The agent that produced this item. + - `"webp"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"jpeg"` - The results of the file search tool call. + - `partial_images: optional number` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `arguments: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A JSON string of the arguments to pass to the function. + - `"low"` - - `call_id: string` + - `"medium"` - The unique ID of the function tool call generated by the model. + - `"high"` - - `name: string` + - `"auto"` - The name of the function to run. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "function_call"` + 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`. - The type of the function tool call. Always `function_call`. + - `"1024x1024"` - - `id: optional string` + - `"1024x1536"` - The unique ID of the function tool call. + - `"1536x1024"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `local_shell: object { type }` - - `caller: optional object { type } or object { caller_id, type }` + A tool that allows the model to execute shell commands in a local environment. - The execution context that produced this tool call. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `namespace: optional string` + A tool that allows the model to execute shell commands. - The namespace of the function to run. + - `type: "shell"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the shell tool. Always `shell`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique ID of the function call tool output. + - `"programmatic"` - - `call_id: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The unique ID of the function tool call generated by the model. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `type: "container_auto"` - The output from the function call generated by your code. - Can be a string or an list of output content. + Automatically creates a container for this request - - `string output: string` + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `beta_container_network_policy_disabled: object { type }` + + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - A string of the output of the function call. + An optional list of skills referenced by id or inline data. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_skill_reference: object { skill_id, type, version }` - Text, image, or file output of the function call. + - `skill_id: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The ID of the referenced skill. - A text input to the model. + - `type: "skill_reference"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + References a skill created with the /v1/skills endpoint. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `version: optional string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A file input to the model. + - `beta_inline_skill: object { description, name, source, type }` - - `status: "in_progress" or "completed" or "incomplete"` + - `description: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The description of the skill. - - `"in_progress"` + - `name: string` - - `"completed"` + The name of the skill. - - `"incomplete"` + - `source: object { data, media_type, type }` - - `type: "function_call_output"` + Inline skill payload - The type of the function tool call output. Always `function_call_output`. + - `data: string` - - `agent: optional object { agent_name }` + Base64-encoded skill zip bundle. - The agent that produced this item. + - `media_type: "application/zip"` - - `agent_name: string` + The media type of the inline skill payload. Must be `application/zip`. - The canonical name of the agent that produced this item. + - `type: "base64"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the inline skill source. Must be `base64`. - The execution context that produced this tool call. + - `type: "inline"` - - `direct: object { type }` + Defines an inline skill for this request. - - `program: object { caller_id, type }` + - `beta_local_environment: object { type, skills }` - - `caller_id: string` + - `type: "local"` - The call ID of the program item that produced this tool call. + Use a local computer environment. - - `type: "program"` + - `skills: optional array of BetaLocalSkill` - The caller type. Always `program`. + An optional list of skills. - - `created_by: optional string` + - `description: string` - The identifier of the actor that created the item. + The description of the skill. - - `agent_message: object { id, author, content, 3 more }` + - `name: string` - - `id: string` + The name of the skill. - The unique ID of the agent message. + - `path: string` - - `author: string` + The path to the directory containing the skill. - The sending agent identity. + - `beta_container_reference: object { container_id, type }` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `container_id: string` - Encrypted content sent between agents. + The ID of the referenced container. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `type: "container_reference"` - A text input to the model. + References a container created with the /v1/containers endpoint - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - A text output from the model. + 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) - - `text: object { text, type }` + - `name: string` - A text content. + The name of the custom tool, used to identify it in tool calls. - - `text: string` + - `type: "custom"` - - `type: "text"` + The type of the custom tool. Always `custom`. - - `summary_text: object { text, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A summary text from the model. + The tool invocation context(s). - - `text: string` + - `"direct"` - A summary of the reasoning output from the model so far. + - `"programmatic"` - - `type: "summary_text"` + - `defer_loading: optional boolean` - The type of the object. Always `summary_text`. + Whether this tool should be deferred and discovered via tool search. - - `reasoning_text: object { text, type }` + - `description: optional string` - Reasoning text from the model. + Optional description of the custom tool, used to provide more context. - - `text: string` + - `format: optional object { type } or object { definition, syntax, type }` - The reasoning text from the model. + The input format for the custom tool. Default is unconstrained text. - - `type: "reasoning_text"` + - `text: object { type }` - The type of the reasoning text. Always `reasoning_text`. + Unconstrained free-form text. - - `beta_response_output_refusal: object { refusal, type }` + - `grammar: object { definition, syntax, type }` - A refusal from the model. + A grammar defined by the user. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `definition: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The grammar definition. - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `syntax: "lark" or "regex"` - A screenshot of a computer. + The syntax of the grammar definition. One of `lark` or `regex`. - - `detail: "low" or "high" or "auto" or "original"` + - `"lark"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"regex"` - - `"low"` + - `type: "grammar"` - - `"high"` + Grammar format. Always `grammar`. - - `"auto"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `"original"` + Groups function/custom tools under a shared namespace. - - `file_id: string` + - `description: string` - The identifier of an uploaded file that contains the screenshot. + A description of the namespace shown to the model. - - `image_url: string` + - `name: string` - The URL of the screenshot image. + The namespace name used in tool calls (for example, `crm`). - - `type: "computer_screenshot"` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The function/custom tools available inside this namespace. - - `prompt_cache_breakpoint: optional object { mode }` + - `function: object { name, type, allowed_callers, 5 more }` - 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. + - `name: string` - - `mode: "explicit"` + - `type: "function"` - The breakpoint mode. Always `explicit`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The tool invocation context(s). - A file input to the model. + - `"direct"` - - `encrypted_content: object { encrypted_content, type }` + - `"programmatic"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `defer_loading: optional boolean` - - `encrypted_content: string` + Whether this function should be deferred and discovered via tool search. - Opaque encrypted content. + - `description: optional string` - - `type: "encrypted_content"` + - `output_schema: optional map[unknown]` - The type of the input item. Always `encrypted_content`. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `recipient: string` + - `parameters: optional unknown` - The destination agent identity. + - `strict: optional boolean` - - `type: "agent_message"` + 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. - The type of the item. Always `agent_message`. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `agent: optional object { agent_name }` + 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) - The agent that produced this item. + - `name: string` - - `agent_name: string` + The name of the custom tool, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `type: "custom"` - - `multi_agent_call: object { id, action, arguments, 3 more }` + The type of the custom tool. Always `custom`. - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the multi-agent call item. + The tool invocation context(s). - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `defer_loading: optional boolean` - The multi-agent action to execute. + Whether this tool should be deferred and discovered via tool search. - - `"spawn_agent"` + - `description: optional string` - - `"interrupt_agent"` + Optional description of the custom tool, used to provide more context. - - `"list_agents"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"send_message"` + The input format for the custom tool. Default is unconstrained text. - - `"followup_task"` + - `type: "namespace"` - - `"wait_agent"` + The type of the tool. Always `namespace`. - - `arguments: string` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The JSON string of arguments generated for the action. + Hosted or BYOT tool search configuration for deferred tools. - - `call_id: string` + - `type: "tool_search"` - The unique ID linking this call to its output. + The type of the tool. Always `tool_search`. - - `type: "multi_agent_call"` + - `description: optional string` - The type of the multi-agent call. Always `multi_agent_call`. + Description shown to the model for a client-executed tool search tool. - - `agent: optional object { agent_name }` + - `execution: optional "server" or "client"` - The agent that produced this item. + Whether tool search is executed by the server or by the client. - - `agent_name: string` + - `"server"` - The canonical name of the agent that produced this item. + - `"client"` - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `parameters: optional unknown` - - `id: string` + Parameter schema for a client-executed tool search tool. - The unique ID of the multi-agent call output item. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + 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). - The multi-agent action that produced this result. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"spawn_agent"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"interrupt_agent"` + - `"web_search_preview"` - - `"list_agents"` + - `"web_search_preview_2025_03_11"` - - `"send_message"` + - `search_content_types: optional array of "text" or "image"` - - `"followup_task"` + - `"text"` - - `"wait_agent"` + - `"image"` - - `call_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The unique ID of the multi-agent call. + 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. - - `output: array of BetaResponseOutputText` + - `"low"` - Text output returned by the multi-agent action. + - `"medium"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"high"` - The annotations of the text output. + - `user_location: optional object { type, city, country, 2 more }` - - `text: string` + The user's location. - The text output from the model. + - `type: "approximate"` - - `type: "output_text"` + The type of location approximation. Always `approximate`. - The type of the output text. Always `output_text`. + - `city: optional string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "multi_agent_call_output"` + - `country: optional string` - The type of the multi-agent result. Always `multi_agent_call_output`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `agent: optional object { agent_name }` + - `region: optional string` - The agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `agent_name: string` + - `timezone: optional string` - The canonical name of the agent that produced this item. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - 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. + Allows the assistant to create, delete, or update files using unified diffs. - - `id: string` + - `type: "apply_patch"` - The unique ID of the web search tool call. + The type of the tool. Always `apply_patch`. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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). + The tool invocation context(s). - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"direct"` - The status of the web search tool call. + - `"programmatic"` - - `type: "web_search_call"` + - `type: "tool_search_output"` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `tool_search_output`. - `agent: optional object { agent_name }` The agent that produced this item. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `additional_tools: object { id, role, tools, 2 more }` - `id: string` - The unique ID of the computer call. + The unique ID of the additional tools item. - - `call_id: string` + - `role: "unknown" or "user" or "assistant" or 5 more` - An identifier used when responding to the tool call with output. + The role that provided the additional tools. - - `pending_safety_checks: array of object { id, code, message }` + - `"unknown"` - The pending safety checks for the computer call. + - `"user"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"assistant"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"system"` - - `type: "computer_call"` + - `"critic"` - The type of the computer call. Always `computer_call`. + - `"discriminator"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `"developer"` - A click action. + - `"tool"` - - `actions: optional array of BetaComputerAction` + - `tools: array of BetaTool` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The additional tool definitions made available at this item. - - `agent: optional object { agent_name }` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The agent that produced this item. + 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). - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `id: string` + 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). - The unique ID of the computer call tool output. + - `beta_computer_tool: object { type }` - - `call_id: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The ID of the computer tool call that produced the output. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `output: object { type, file_id, image_url }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A computer screenshot image used with the computer use tool. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `type: "computer_screenshot"` + 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). - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `file_id: optional string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The identifier of an uploaded file that contains the screenshot. + - `code_interpreter: object { container, type, allowed_callers }` - - `image_url: optional string` + A tool that runs Python code to help generate a response to a prompt. - The URL of the screenshot image. + - `programmatic_tool_calling: object { type }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `image_generation: object { type, action, background, 9 more }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + A tool that generates images using the GPT image models. - - `"completed"` + - `local_shell: object { type }` - - `"incomplete"` + A tool that allows the model to execute shell commands in a local environment. - - `"failed"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"in_progress"` + A tool that allows the model to execute shell commands. - - `type: "computer_call_output"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The type of the computer tool call output. Always `computer_call_output`. + 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) - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `beta_namespace_tool: object { description, name, tools, type }` - The safety checks reported by the API that have been acknowledged by the - developer. + Groups function/custom tools under a shared namespace. - - `id: string` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The ID of the pending safety check. + Hosted or BYOT tool search configuration for deferred tools. - - `code: optional string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The type of the pending safety check. + 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). - - `message: optional string` + - `beta_apply_patch_tool: object { type, allowed_callers }` - Details about the pending safety check. + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. - `agent: optional object { agent_name }` @@ -75576,10 +87090,6 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` A description of the chain of thought used by a reasoning model while generating @@ -75595,6 +87105,14 @@ openai beta:responses compact \ Reasoning summary content. + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -75603,10 +87121,22 @@ openai beta:responses compact \ The agent that produced this item. + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `content: optional array of object { text, type }` Reasoning text content. + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + - `encrypted_content: optional string` The encrypted content of the reasoning item - populated when a response is @@ -75617,6 +87147,12 @@ openai beta:responses compact \ The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + - `program: object { id, call_id, code, 3 more }` - `id: string` @@ -75681,41 +87217,61 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: string` - The unique ID of the tool search call item. + The unique ID of the compaction item. - - `arguments: unknown` + - `encrypted_content: string` - Arguments used for the tool search call. + The encrypted content that was produced by compaction. - - `call_id: string` + - `type: "compaction"` - The unique ID of the tool search call generated by the model. + The type of the item. Always `compaction`. - - `execution: "server" or "client"` + - `agent: optional object { agent_name }` - Whether tool search was executed by the server or by the client. + The agent that produced this item. - - `"server"` + - `agent_name: string` - - `"client"` + The canonical name of the agent that produced this item. - - `status: "in_progress" or "completed" or "incomplete"` + - `created_by: optional string` - The status of the tool search call item that was recorded. + The identifier of the actor that created the item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. - `"in_progress"` - `"completed"` - - `"incomplete"` + - `"generating"` - - `type: "tool_search_call"` + - `"failed"` - The type of the item. Always `tool_search_call`. + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. - `agent: optional object { agent_name }` @@ -75725,31 +87281,54 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + A tool call to run code. - `id: string` - The unique ID of the tool search output item. + The unique ID of the code interpreter tool call. - - `call_id: string` + - `code: string` - The unique ID of the tool search call generated by the model. + The code to run, or null if not available. - - `execution: "server" or "client"` + - `container_id: string` - Whether tool search was executed by the server or by the client. + The ID of the container used to run the code. - - `"server"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"client"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `status: "in_progress" or "completed" or "incomplete"` + - `logs: object { logs, type }` - The status of the tool search output item that was recorded. + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` @@ -75757,77 +87336,75 @@ openai beta:responses compact \ - `"incomplete"` - - `tools: array of BetaTool` + - `"interpreting"` - The loaded tool definitions returned by tool search. + - `"failed"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `type: "code_interpreter_call"` - 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). + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `agent: optional object { agent_name }` - 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). + The agent that produced this item. - - `beta_computer_tool: object { type }` + - `agent_name: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The canonical name of the agent that produced this item. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `local_shell_call: object { id, action, call_id, 3 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A tool call to run a command on the local shell. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `id: string` - 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). + The unique ID of the local shell call. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `action: object { command, env, type, 3 more }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Execute a shell command on the server. - - `code_interpreter: object { container, type, allowed_callers }` + - `command: array of string` - A tool that runs Python code to help generate a response to a prompt. + The command to run. - - `programmatic_tool_calling: object { type }` + - `env: map[string]` - - `image_generation: object { type, action, background, 9 more }` + Environment variables to set for the command. - A tool that generates images using the GPT image models. + - `type: "exec"` - - `local_shell: object { type }` + The type of the local shell action. Always `exec`. - A tool that allows the model to execute shell commands in a local environment. + - `timeout_ms: optional number` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + Optional timeout in milliseconds for the command. - A tool that allows the model to execute shell commands. + - `user: optional string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Optional user to run the command as. - 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) + - `working_directory: optional string` - - `beta_namespace_tool: object { description, name, tools, type }` + Optional working directory to run the command in. - Groups function/custom tools under a shared namespace. + - `call_id: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The unique ID of the local shell tool call generated by the model. - Hosted or BYOT tool search configuration for deferred tools. + - `status: "in_progress" or "completed" or "incomplete"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The status of the local shell call. - 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). + - `"in_progress"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"completed"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"incomplete"` - - `type: "tool_search_output"` + - `type: "local_shell_call"` - The type of the item. Always `tool_search_output`. + The type of the local shell call. Always `local_shell_call`. - `agent: optional object { agent_name }` @@ -75837,107 +87414,101 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `additional_tools: object { id, role, tools, 2 more }` + The output of a local shell tool call. - `id: string` - The unique ID of the additional tools item. - - - `role: "unknown" or "user" or "assistant" or 5 more` + The unique ID of the local shell tool call generated by the model. - The role that provided the additional tools. + - `output: string` - - `"unknown"` + A JSON string of the output of the local shell tool call. - - `"user"` + - `type: "local_shell_call_output"` - - `"assistant"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"system"` + - `agent: optional object { agent_name }` - - `"critic"` + The agent that produced this item. - - `"discriminator"` + - `agent_name: string` - - `"developer"` + The canonical name of the agent that produced this item. - - `"tool"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `tools: array of BetaTool` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The additional tool definitions made available at this item. + - `"in_progress"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `"completed"` - 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). + - `"incomplete"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - 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). + A tool call that executes one or more shell commands in a managed environment. - - `beta_computer_tool: object { type }` + - `id: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The unique ID of the shell tool call. Populated when this item is returned via API. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `action: object { commands, max_output_length, timeout_ms }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The shell commands and limits that describe how to run the tool call. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `commands: array of string` - 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). + - `max_output_length: number` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + Optional maximum number of characters to return from each command. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `timeout_ms: number` - - `code_interpreter: object { container, type, allowed_callers }` + Optional timeout in milliseconds for the commands. - A tool that runs Python code to help generate a response to a prompt. + - `call_id: string` - - `programmatic_tool_calling: object { type }` + The unique ID of the shell tool call generated by the model. - - `image_generation: object { type, action, background, 9 more }` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - A tool that generates images using the GPT image models. + Represents the use of a local environment to perform shell actions. - - `local_shell: object { type }` + - `beta_response_local_environment: object { type }` - A tool that allows the model to execute shell commands in a local environment. + Represents the use of a local environment to perform shell actions. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `type: "local"` - A tool that allows the model to execute shell commands. + The environment type. Always `local`. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `beta_response_container_reference: object { container_id, type }` - 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) + Represents a container created with /v1/containers. - - `beta_namespace_tool: object { description, name, tools, type }` + - `container_id: string` - Groups function/custom tools under a shared namespace. + - `type: "container_reference"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The environment type. Always `container_reference`. - Hosted or BYOT tool search configuration for deferred tools. + - `status: "in_progress" or "completed" or "incomplete"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - 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). + - `"in_progress"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"completed"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"incomplete"` - - `type: "additional_tools"` + - `type: "shell_call"` - The type of the item. Always `additional_tools`. + The type of the item. Always `shell_call`. - `agent: optional object { agent_name }` @@ -75947,21 +87518,89 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + + The output of a shell tool call that was emitted. - `id: string` - The unique ID of the compaction item. + The unique ID of the shell call output. Populated when this item is returned via API. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The unique ID of the shell tool call generated by the model. - - `type: "compaction"` + - `max_output_length: number` - The type of the item. Always `compaction`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents + + - `outcome: object { type } or object { exit_code, type }` + + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + The standard error output that was captured. + + - `stdout: string` + + The standard output that was captured. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. - `agent: optional object { agent_name }` @@ -75971,37 +87610,95 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `image_generation_call: object { id, result, status, 2 more }` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - An image generation request made by the model. + A tool call that applies file diffs by creating, deleting, or updating files. - `id: string` - The unique ID of the image generation call. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `result: string` + - `call_id: string` - The generated image encoded in base64. + The unique ID of the apply patch tool call generated by the model. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The status of the image generation call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"in_progress"` + - `create_file: object { diff, path, type }` - - `"completed"` + Instruction describing how to create a file via the apply_patch tool. - - `"generating"` + - `diff: string` - - `"failed"` + Diff to apply. - - `type: "image_generation_call"` + - `path: string` - The type of the image generation call. Always `image_generation_call`. + Path of the file to create. + + - `type: "create_file"` + + Create a new file with the provided diff. + + - `delete_file: object { path, type }` + + Instruction describing how to delete a file via the apply_patch tool. + + - `path: string` + + Path of the file to delete. + + - `type: "delete_file"` + + Delete the specified file. + + - `update_file: object { diff, path, type }` + + Instruction describing how to update a file via the apply_patch tool. + + - `diff: string` + + Diff to apply. + + - `path: string` + + Path of the file to update. + + - `type: "update_file"` + + Update an existing file with the provided diff. + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. - `agent: optional object { agent_name }` @@ -76011,92 +87708,149 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - A tool call to run code. + The execution context that produced this tool call. - - `id: string` + - `direct: object { type }` - The unique ID of the code interpreter tool call. + - `program: object { caller_id, type }` - - `code: string` + - `caller_id: string` - The code to run, or null if not available. + The call ID of the program item that produced this tool call. - - `container_id: string` + - `type: "program"` - The ID of the container used to run the code. + - `created_by: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + The ID of the entity that created this tool call. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The output emitted by an apply patch tool call. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `id: string` - - `type: "code_interpreter_call"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. - `agent: optional object { agent_name }` The agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `agent_name: string` - A tool call to run a command on the local shell. + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call output. + + - `output: optional string` + + Optional textual output returned by the apply patch tool. + + - `mcp_list_tools: object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. - `id: string` - The unique ID of the local shell call. + The unique ID of the list. - - `action: object { command, env, type, 3 more }` + - `server_label: string` - Execute a shell command on the server. + The label of the MCP server. - - `command: array of string` + - `tools: array of object { input_schema, name, annotations, description }` - The command to run. + The tools available on the server. - - `env: map[string]` + - `input_schema: unknown` - Environment variables to set for the command. + The JSON schema describing the tool's input. - - `type: "exec"` + - `name: string` - The type of the local shell action. Always `exec`. + The name of the tool. - - `timeout_ms: optional number` + - `annotations: optional unknown` - Optional timeout in milliseconds for the command. + Additional annotations about the tool. - - `user: optional string` + - `description: optional string` - Optional user to run the command as. + The description of the tool. - - `working_directory: optional string` + - `type: "mcp_list_tools"` - Optional working directory to run the command in. + The type of the item. Always `mcp_list_tools`. - - `call_id: string` + - `agent: optional object { agent_name }` - The unique ID of the local shell tool call generated by the model. + The agent that produced this item. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent_name: string` - The status of the local shell call. + The canonical name of the agent that produced this item. - - `"in_progress"` + - `error: optional string` - - `"completed"` + Error message if the server could not list tools. - - `"incomplete"` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `type: "local_shell_call"` + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` - The type of the local shell call. Always `local_shell_call`. + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` @@ -76106,21 +87860,25 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - The output of a local shell tool call. + A response to an MCP approval request. - `id: string` - The unique ID of the local shell tool call generated by the model. + The unique ID of the approval response - - `output: string` + - `approval_request_id: string` - A JSON string of the output of the local shell tool call. + The ID of the approval request being answered. - - `type: "local_shell_call_output"` + - `approve: boolean` - The type of the local shell tool call output. Always `local_shell_call_output`. + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. - `agent: optional object { agent_name }` @@ -76130,67 +87888,81 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `reason: optional string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Optional reason for the decision. - - `"in_progress"` + - `mcp_call: object { id, arguments, name, 7 more }` - - `"completed"` + An invocation of a tool on an MCP server. - - `"incomplete"` + - `id: string` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + The unique ID of the tool call. - A tool call that executes one or more shell commands in a managed environment. + - `arguments: string` - - `id: string` + A JSON string of the arguments passed to the tool. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `name: string` - - `action: object { commands, max_output_length, timeout_ms }` + The name of the tool that was run. - The shell commands and limits that describe how to run the tool call. + - `server_label: string` - - `commands: array of string` + The label of the MCP server running the tool. - - `max_output_length: number` + - `type: "mcp_call"` - Optional maximum number of characters to return from each command. + The type of the item. Always `mcp_call`. - - `timeout_ms: number` + - `agent: optional object { agent_name }` - Optional timeout in milliseconds for the commands. + The agent that produced this item. - - `call_id: string` + - `agent_name: string` - The unique ID of the shell tool call generated by the model. + The canonical name of the agent that produced this item. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `approval_request_id: optional string` - Represents the use of a local environment to perform shell actions. + 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. - - `beta_response_local_environment: object { type }` + - `error: optional string` - Represents the use of a local environment to perform shell actions. + The error from the tool call, if any. - - `type: "local"` + - `output: optional string` - The environment type. Always `local`. + The output from the tool call. - - `beta_response_container_reference: object { container_id, type }` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - Represents a container created with /v1/containers. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `container_id: string` + - `"in_progress"` - - `type: "container_reference"` + - `"completed"` - The environment type. Always `container_reference`. + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` + + A call to a custom tool created by the model. + + - `id: string` + + The unique ID of the custom tool call item. - `status: "in_progress" or "completed" or "incomplete"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -76198,1570 +87970,1481 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "shell_call"` + - `created_by: optional string` - The type of the item. Always `shell_call`. + The identifier of the actor that created the item. - - `agent: optional object { agent_name }` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - The agent that produced this item. + The output of a custom tool call from your code, being sent back to the model. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the custom tool call output item. - - `caller: optional object { type } or object { caller_id, type }` + - `status: "in_progress" or "completed" or "incomplete"` - The execution context that produced this tool call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `direct: object { type }` + - `"in_progress"` - - `program: object { caller_id, type }` + - `"completed"` - - `caller_id: string` + - `"incomplete"` - The call ID of the program item that produced this tool call. + - `created_by: optional string` - - `type: "program"` + The identifier of the actor that created the item. - - `created_by: optional string` +### Beta Response Local Environment - The ID of the entity that created this tool call. +- `beta_response_local_environment: object { type }` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + Represents the use of a local environment to perform shell actions. - The output of a shell tool call that was emitted. + - `type: "local"` - - `id: string` + The environment type. Always `local`. - The unique ID of the shell call output. Populated when this item is returned via API. +### Beta Response Mcp Call Arguments Delta Event - - `call_id: string` +- `beta_response_mcp_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` - The unique ID of the shell tool call generated by the model. + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `max_output_length: number` + - `delta: string` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + A JSON string containing the partial update to the arguments for the MCP tool call. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `item_id: string` - An array of shell call output contents + The unique identifier of the MCP tool call item being processed. - - `outcome: object { type } or object { exit_code, type }` + - `output_index: number` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The index of the output item in the response's output array. - - `timeout: object { type }` + - `sequence_number: number` - Indicates that the shell call exceeded its configured time limit. + The sequence number of this event. - - `exit: object { exit_code, type }` + - `type: "response.mcp_call_arguments.delta"` - Indicates that the shell commands finished and returned an exit code. + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `exit_code: number` + - `agent: optional object { agent_name }` - Exit code from the shell process. + The agent that owns this multi-agent streaming event. - - `type: "exit"` + - `agent_name: string` - The outcome type. Always `exit`. + The canonical name of the agent that produced this item. - - `stderr: string` +### Beta Response Mcp Call Arguments Done Event - The standard error output that was captured. +- `beta_response_mcp_call_arguments_done_event: object { arguments, item_id, output_index, 3 more }` - - `stdout: string` + Emitted when the arguments for an MCP tool call are finalized. - The standard output that was captured. + - `arguments: string` - - `created_by: optional string` + A JSON string containing the finalized arguments for the MCP tool call. - The identifier of the actor that created the item. + - `item_id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The unique identifier of the MCP tool call item being processed. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `output_index: number` - - `"in_progress"` + The index of the output item in the response's output array. - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number of this event. - - `type: "shell_call_output"` + - `type: "response.mcp_call_arguments.done"` - The type of the shell call output. Always `shell_call_output`. + The type of the event. Always 'response.mcp_call_arguments.done'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` +### Beta Response Mcp Call Completed Event - The execution context that produced this tool call. +- `beta_response_mcp_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `direct: object { type }` + Emitted when an MCP tool call has completed successfully. - - `program: object { caller_id, type }` + - `item_id: string` - - `caller_id: string` + The ID of the MCP tool call item that completed. - The call ID of the program item that produced this tool call. + - `output_index: number` - - `type: "program"` + The index of the output item that completed. - - `created_by: optional string` + - `sequence_number: number` - The identifier of the actor that created the item. + The sequence number of this event. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `type: "response.mcp_call.completed"` - A tool call that applies file diffs by creating, deleting, or updating files. + The type of the event. Always 'response.mcp_call.completed'. - - `id: string` + - `agent: optional object { agent_name }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The agent that owns this multi-agent streaming event. - - `call_id: string` + - `agent_name: string` - The unique ID of the apply patch tool call generated by the model. + The canonical name of the agent that produced this item. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` +### Beta Response Mcp Call Failed Event - One of the create_file, delete_file, or update_file operations applied via apply_patch. +- `beta_response_mcp_call_failed_event: object { item_id, output_index, sequence_number, 2 more }` - - `create_file: object { diff, path, type }` + Emitted when an MCP tool call has failed. - Instruction describing how to create a file via the apply_patch tool. + - `item_id: string` - - `diff: string` + The ID of the MCP tool call item that failed. - Diff to apply. + - `output_index: number` - - `path: string` + The index of the output item that failed. - Path of the file to create. + - `sequence_number: number` - - `type: "create_file"` + The sequence number of this event. - Create a new file with the provided diff. + - `type: "response.mcp_call.failed"` - - `delete_file: object { path, type }` + The type of the event. Always 'response.mcp_call.failed'. - Instruction describing how to delete a file via the apply_patch tool. + - `agent: optional object { agent_name }` - - `path: string` + The agent that owns this multi-agent streaming event. - Path of the file to delete. + - `agent_name: string` - - `type: "delete_file"` + The canonical name of the agent that produced this item. - Delete the specified file. +### Beta Response Mcp Call In Progress Event - - `update_file: object { diff, path, type }` +- `beta_response_mcp_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - Instruction describing how to update a file via the apply_patch tool. + Emitted when an MCP tool call is in progress. - - `diff: string` + - `item_id: string` - Diff to apply. + The unique identifier of the MCP tool call item being processed. - - `path: string` + - `output_index: number` - Path of the file to update. + The index of the output item in the response's output array. - - `type: "update_file"` + - `sequence_number: number` - Update an existing file with the provided diff. + The sequence number of this event. - - `status: "in_progress" or "completed"` + - `type: "response.mcp_call.in_progress"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The type of the event. Always 'response.mcp_call.in_progress'. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that owns this multi-agent streaming event. - - `type: "apply_patch_call"` + - `agent_name: string` - The type of the item. Always `apply_patch_call`. + The canonical name of the agent that produced this item. - - `agent: optional object { agent_name }` +### Beta Response Mcp List Tools Completed Event - The agent that produced this item. +- `beta_response_mcp_list_tools_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `agent_name: string` + Emitted when the list of available MCP tools has been successfully retrieved. - The canonical name of the agent that produced this item. + - `item_id: string` - - `caller: optional object { type } or object { caller_id, type }` + The ID of the MCP tool call item that produced this output. - The execution context that produced this tool call. + - `output_index: number` - - `direct: object { type }` + The index of the output item that was processed. - - `program: object { caller_id, type }` + - `sequence_number: number` - - `caller_id: string` + The sequence number of this event. - The call ID of the program item that produced this tool call. + - `type: "response.mcp_list_tools.completed"` - - `type: "program"` + The type of the event. Always 'response.mcp_list_tools.completed'. - - `created_by: optional string` + - `agent: optional object { agent_name }` - The ID of the entity that created this tool call. + The agent that owns this multi-agent streaming event. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `agent_name: string` - The output emitted by an apply patch tool call. + The canonical name of the agent that produced this item. - - `id: string` +### Beta Response Mcp List Tools Failed Event - The unique ID of the apply patch tool call output. Populated when this item is returned via API. +- `beta_response_mcp_list_tools_failed_event: object { item_id, output_index, sequence_number, 2 more }` - - `call_id: string` + Emitted when the attempt to list available MCP tools has failed. - The unique ID of the apply patch tool call generated by the model. + - `item_id: string` - - `status: "completed" or "failed"` + The ID of the MCP tool call item that failed. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `output_index: number` - - `"completed"` + The index of the output item that failed. - - `"failed"` + - `sequence_number: number` - - `type: "apply_patch_call_output"` + The sequence number of this event. - The type of the item. Always `apply_patch_call_output`. + - `type: "response.mcp_list_tools.failed"` + + The type of the event. Always 'response.mcp_list_tools.failed'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` +### Beta Response Mcp List Tools In Progress Event - The execution context that produced this tool call. +- `beta_response_mcp_list_tools_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `direct: object { type }` + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `program: object { caller_id, type }` + - `item_id: string` - - `caller_id: string` + The ID of the MCP tool call item that is being processed. - The call ID of the program item that produced this tool call. + - `output_index: number` - - `type: "program"` + The index of the output item that is being processed. - - `created_by: optional string` + - `sequence_number: number` - The ID of the entity that created this tool call output. + The sequence number of this event. - - `output: optional string` + - `type: "response.mcp_list_tools.in_progress"` - Optional textual output returned by the apply patch tool. + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `mcp_call: object { id, arguments, name, 7 more }` + - `agent: optional object { agent_name }` - An invocation of a tool on an MCP server. + The agent that owns this multi-agent streaming event. - - `id: string` + - `agent_name: string` - The unique ID of the tool call. + The canonical name of the agent that produced this item. - - `arguments: string` +### Beta Response Output Audio - A JSON string of the arguments passed to the tool. +- `beta_response_output_audio: object { data, transcript, type }` - - `name: string` + An audio output from the model. - The name of the tool that was run. + - `data: string` - - `server_label: string` + Base64-encoded audio data from the model. - The label of the MCP server running the tool. + - `transcript: string` - - `type: "mcp_call"` + The transcript of the audio data from the model. - The type of the item. Always `mcp_call`. + - `type: "output_audio"` - - `agent: optional object { agent_name }` + The type of the output audio. Always `output_audio`. - The agent that produced this item. +### Beta Response Output Item - - `agent_name: string` +- `beta_response_output_item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` - The canonical name of the agent that produced this item. + An output message from the model. - - `approval_request_id: optional string` + - `beta_response_output_message: object { id, content, role, 4 more }` - 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. + An output message from the model. - - `error: optional string` + - `id: string` - The error from the tool call, if any. + The unique ID of the output message. - - `output: optional string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The output from the tool call. + The content of the output message. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A text output from the model. - - `"in_progress"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `"completed"` + The annotations of the text output. - - `"incomplete"` + - `file_citation: object { file_id, filename, index, type }` - - `"calling"` + A citation to a file. - - `"failed"` + - `file_id: string` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + The ID of the file. - A list of tools available on an MCP server. + - `filename: string` - - `id: string` + The filename of the file cited. - The unique ID of the list. + - `index: number` - - `server_label: string` + The index of the file in the list of files. - The label of the MCP server. + - `type: "file_citation"` - - `tools: array of object { input_schema, name, annotations, description }` + The type of the file citation. Always `file_citation`. - The tools available on the server. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `input_schema: unknown` + A citation for a web resource used to generate a model response. - The JSON schema describing the tool's input. + - `end_index: number` - - `name: string` + The index of the last character of the URL citation in the message. - The name of the tool. + - `start_index: number` - - `annotations: optional unknown` + The index of the first character of the URL citation in the message. - Additional annotations about the tool. + - `title: string` - - `description: optional string` + The title of the web resource. - The description of the tool. + - `type: "url_citation"` - - `type: "mcp_list_tools"` + The type of the URL citation. Always `url_citation`. - The type of the item. Always `mcp_list_tools`. + - `url: string` - - `agent: optional object { agent_name }` + The URL of the web resource. - The agent that produced this item. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `agent_name: string` + A citation for a container file used to generate a model response. - The canonical name of the agent that produced this item. + - `container_id: string` - - `error: optional string` + The ID of the container file. - Error message if the server could not list tools. + - `end_index: number` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The index of the last character of the container file citation in the message. - A request for human approval of a tool invocation. + - `file_id: string` - - `id: string` + The ID of the file. - The unique ID of the approval request. + - `filename: string` - - `arguments: string` + The filename of the container file cited. - A JSON string of arguments for the tool. + - `start_index: number` - - `name: string` + The index of the first character of the container file citation in the message. - The name of the tool to run. + - `type: "container_file_citation"` - - `server_label: string` + The type of the container file citation. Always `container_file_citation`. - The label of the MCP server making the request. + - `file_path: object { file_id, index, type }` - - `type: "mcp_approval_request"` + A path to a file. - The type of the item. Always `mcp_approval_request`. + - `file_id: string` - - `agent: optional object { agent_name }` + The ID of the file. - The agent that produced this item. + - `index: number` - - `agent_name: string` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `type: "file_path"` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + The type of the file path. Always `file_path`. - A response to an MCP approval request. + - `text: string` - - `id: string` + The text output from the model. - The unique ID of the approval response + - `type: "output_text"` - - `approval_request_id: string` + The type of the output text. Always `output_text`. - The ID of the approval request being answered. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `approve: boolean` + - `token: string` - Whether the request was approved. + - `bytes: array of number` - - `type: "mcp_approval_response"` + - `logprob: number` - The type of the item. Always `mcp_approval_response`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `agent: optional object { agent_name }` + - `token: string` - The agent that produced this item. + - `bytes: array of number` - - `agent_name: string` + - `logprob: number` - The canonical name of the agent that produced this item. + - `beta_response_output_refusal: object { refusal, type }` - - `reason: optional string` + A refusal from the model. - Optional reason for the decision. + - `refusal: string` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + The refusal explanation from the model. - A call to a custom tool created by the model. + - `type: "refusal"` - - `call_id: string` + The type of the refusal. Always `refusal`. - An identifier used to map this custom tool call to a tool call output. + - `role: "assistant"` - - `input: string` + The role of the output message. Always `assistant`. - The input for the custom tool call generated by the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The name of the custom tool being called. + - `"in_progress"` - - `type: "custom_tool_call"` + - `"completed"` - The type of the custom tool call. Always `custom_tool_call`. + - `"incomplete"` - - `id: optional string` + - `type: "message"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the output message. Always `message`. - `agent: optional object { agent_name }` The agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `namespace: optional string` - - The namespace of the custom tool being called. + - `agent_name: string` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The canonical name of the agent that produced this item. - The output of a custom tool call from your code, being sent back to the model. + - `phase: optional "commentary" or "final_answer"` - - `id: string` + 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. - The unique ID of the custom tool call output item. + - `"commentary"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"final_answer"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `"in_progress"` + 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. - - `"completed"` + - `id: string` - - `"incomplete"` + The unique ID of the file search tool call. - - `created_by: optional string` + - `queries: array of string` - The identifier of the actor that created the item. + The queries used to search for files. - - `parallel_tool_calls: boolean` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Whether to allow the model to run tool calls in parallel. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `temperature: number` + - `"in_progress"` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `"searching"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"completed"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `"incomplete"` - - `beta_tool_choice_options: "none" or "auto" or "required"` + - `"failed"` - Controls which (if any) tool is called by the model. + - `type: "file_search_call"` - `none` means the model will not call any tool and instead generates a message. + The type of the file search tool call. Always `file_search_call`. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `agent: optional object { agent_name }` - `required` means the model must call one or more tools. + The agent that produced this item. - - `"none"` + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"required"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `beta_tool_choice_allowed: object { mode, tools, type }` + The results of the file search tool call. - Constrains the tools available to the model to a pre-defined set. + - `attributes: optional map[string or number or boolean]` - - `mode: "auto" or "required"` + 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. - Constrains the tools available to the model to a pre-defined set. + - `union_member_0: string` - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `union_member_1: number` - `required` requires the model to call one or more of the allowed tools. + - `union_member_2: boolean` - - `"auto"` + - `file_id: optional string` - - `"required"` + The unique ID of the file. - - `tools: array of map[unknown]` + - `filename: optional string` - A list of tool definitions that the model should be allowed to call. + The name of the file. - For the Responses API, the list of tool definitions might look like: + - `score: optional number` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The relevance score of the file - a value between 0 and 1. - - `type: "allowed_tools"` + - `text: optional string` - Allowed tool configuration type. Always `allowed_tools`. + The text that was retrieved from the file. - - `beta_tool_choice_types: object { type }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `arguments: string` - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + A JSON string of the arguments to pass to the function. - Allowed values are: + - `call_id: string` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The unique ID of the function tool call generated by the model. - - `"file_search"` + - `name: string` - - `"web_search_preview"` + The name of the function to run. - - `"computer"` + - `type: "function_call"` - - `"computer_use_preview"` + The type of the function tool call. Always `function_call`. - - `"computer_use"` + - `id: optional string` - - `"web_search_preview_2025_03_11"` + The unique ID of the function tool call. - - `"image_generation"` + - `agent: optional object { agent_name }` - - `"code_interpreter"` + The agent that produced this item. - - `beta_tool_choice_function: object { name, type }` + - `agent_name: string` - Use this option to force the model to call a specific function. + The canonical name of the agent that produced this item. - - `name: string` + - `caller: optional object { type } or object { caller_id, type }` - The name of the function to call. + The execution context that produced this tool call. - - `type: "function"` + - `direct: object { type }` - For function calling, the type is always `function`. + - `program: object { caller_id, type }` - - `beta_tool_choice_mcp: object { server_label, type, name }` + - `caller_id: string` - Use this option to force the model to call a specific tool on a remote MCP server. + The call ID of the program item that produced this tool call. - - `server_label: string` + - `type: "program"` - The label of the MCP server to use. + - `namespace: optional string` - - `type: "mcp"` + The namespace of the function to run. - For MCP tools, the type is always `mcp`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `name: optional string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The name of the tool to call on the server. + - `"in_progress"` - - `beta_tool_choice_custom: object { name, type }` + - `"completed"` - Use this option to force the model to call a specific custom tool. + - `"incomplete"` - - `name: string` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - The name of the custom tool to call. + - `id: string` - - `type: "custom"` + The unique ID of the function call tool output. - For custom tool calling, the type is always `custom`. + - `call_id: string` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + The unique ID of the function tool call generated by the model. - - `beta_tool_choice_apply_patch: object { type }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Forces the model to call the apply_patch tool when executing a tool call. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `type: "apply_patch"` + - `string output: string` - The tool to call. Always `apply_patch`. + A string of the output of the function call. - - `beta_tool_choice_shell: object { type }` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Forces the model to call the shell tool when a tool call is required. + Text, image, or file output of the function call. - - `type: "shell"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The tool to call. Always `shell`. + A text input to the model. - - `tools: array of BetaTool` + - `text: string` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The text input to the model. - We support the following categories of tools: + - `type: "input_text"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The type of the input item. Always `input_text`. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `prompt_cache_breakpoint: optional object { mode }` - 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). + 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. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `mode: "explicit"` - 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). + The breakpoint mode. Always `explicit`. - - `beta_computer_tool: object { type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `detail: "low" or "high" or "auto" or "original"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `"low"` - 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). + - `"high"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `"auto"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"original"` - - `code_interpreter: object { container, type, allowed_callers }` + - `type: "input_image"` - A tool that runs Python code to help generate a response to a prompt. + The type of the input item. Always `input_image`. - - `programmatic_tool_calling: object { type }` + - `file_id: optional string` - - `image_generation: object { type, action, background, 9 more }` + The ID of the file to be sent to the model. - A tool that generates images using the GPT image models. + - `image_url: optional string` - - `local_shell: object { type }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - A tool that allows the model to execute shell commands in a local environment. + - `prompt_cache_breakpoint: optional object { mode }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + 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. - A tool that allows the model to execute shell commands. + - `mode: "explicit"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The breakpoint mode. Always `explicit`. - 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) + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `beta_namespace_tool: object { description, name, tools, type }` + A file input to the model. - Groups function/custom tools under a shared namespace. + - `type: "input_file"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The type of the input item. Always `input_file`. - Hosted or BYOT tool search configuration for deferred tools. + - `detail: optional "auto" or "low" or "high"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + 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`. - 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). + - `"auto"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"low"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"high"` - - `top_p: number` + - `file_data: optional string` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The content of the file to be sent to the model. - We generally recommend altering this or `temperature` but not both. + - `file_id: optional string` - - `background: optional boolean` + The ID of the file to be sent to the model. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `file_url: optional string` - - `completed_at: optional number` + The URL of the file to be sent to the model. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `filename: optional string` - - `conversation: optional object { id }` + The name of the file to be sent to the model. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `prompt_cache_breakpoint: optional object { mode }` - - `id: string` + 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. - The unique ID of the conversation that this response was associated with. + - `mode: "explicit"` - - `max_output_tokens: optional number` + The breakpoint mode. Always `explicit`. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `status: "in_progress" or "completed" or "incomplete"` - - `max_tool_calls: optional number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"in_progress"` - - `moderation: optional object { input, output }` + - `"completed"` - Moderation results for the response input and output, if moderated completions were requested. + - `"incomplete"` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `type: "function_call_output"` - Moderation for the response input. + The type of the function tool call output. Always `function_call_output`. - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `agent: optional object { agent_name }` - A moderation result produced for the response input or output. + The agent that produced this item. - - `categories: map[boolean]` + - `agent_name: string` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The canonical name of the agent that produced this item. - - `category_applied_input_types: map[array of "text" or "image"]` + - `caller: optional object { type } or object { caller_id, type }` - Which modalities of input are reflected by the score for each category. + The execution context that produced this tool call. - - `"text"` + - `direct: object { type }` - - `"image"` + - `program: object { caller_id, type }` - - `category_scores: map[number]` + - `caller_id: string` - A dictionary of moderation categories to scores. + The call ID of the program item that produced this tool call. - - `flagged: boolean` + - `type: "program"` - A boolean indicating whether the content was flagged by any category. + The caller type. Always `program`. - - `model: string` + - `created_by: optional string` - The moderation model that produced this result. + The identifier of the actor that created the item. - - `type: "moderation_result"` + - `agent_message: object { id, author, content, 3 more }` - The object type, which was always `moderation_result` for successful moderation results. + - `id: string` - - `error: object { code, message, type }` + The unique ID of the agent message. - An error produced while attempting moderation for the response input or output. + - `author: string` - - `code: string` + The sending agent identity. - The error code. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `message: string` + Encrypted content sent between agents. - The error message. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `type: "error"` + A text input to the model. - The object type, which was always `error` for moderation failures. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + A text output from the model. - Moderation for the response output. + - `text: object { text, type }` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + A text content. - A moderation result produced for the response input or output. + - `text: string` - - `categories: map[boolean]` + - `type: "text"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `summary_text: object { text, type }` - - `category_applied_input_types: map[array of "text" or "image"]` + A summary text from the model. - Which modalities of input are reflected by the score for each category. + - `text: string` - - `"text"` + A summary of the reasoning output from the model so far. - - `"image"` + - `type: "summary_text"` - - `category_scores: map[number]` + The type of the object. Always `summary_text`. - A dictionary of moderation categories to scores. + - `reasoning_text: object { text, type }` - - `flagged: boolean` + Reasoning text from the model. - A boolean indicating whether the content was flagged by any category. + - `text: string` - - `model: string` + The reasoning text from the model. - The moderation model that produced this result. + - `type: "reasoning_text"` - - `type: "moderation_result"` + The type of the reasoning text. Always `reasoning_text`. - The object type, which was always `moderation_result` for successful moderation results. + - `beta_response_output_refusal: object { refusal, type }` - - `error: object { code, message, type }` + A refusal from the model. - An error produced while attempting moderation for the response input or output. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `code: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The error code. + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - - `message: string` + A screenshot of a computer. - The error message. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "error"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The object type, which was always `error` for moderation failures. + - `"low"` - - `previous_response_id: optional string` + - `"high"` - 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`. + - `"auto"` - - `prompt: optional object { id, variables, version }` + - `"original"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `file_id: string` - - `id: string` + The identifier of an uploaded file that contains the screenshot. - The unique identifier of the prompt template to use. + - `image_url: string` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + The URL of the screenshot image. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `type: "computer_screenshot"` - - `union_member_0: string` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `prompt_cache_breakpoint: optional object { mode }` - A text input to the model. + 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. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The breakpoint mode. Always `explicit`. - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. - - `version: optional string` + - `encrypted_content: object { encrypted_content, type }` - Optional version of the prompt template. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `prompt_cache_key: optional string` + - `encrypted_content: string` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Opaque encrypted content. - - `prompt_cache_options: optional object { mode, ttl }` + - `type: "encrypted_content"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The type of the input item. Always `encrypted_content`. - - `mode: "implicit" or "explicit"` + - `recipient: string` - Whether implicit prompt-cache breakpoints were enabled. + The destination agent identity. - - `"implicit"` + - `type: "agent_message"` - - `"explicit"` + The type of the item. Always `agent_message`. - - `ttl: "30m"` + - `agent: optional object { agent_name }` - The minimum lifetime applied to each cache breakpoint. + The agent that produced this item. - - `"30m"` + - `agent_name: string` - - `prompt_cache_retention: optional "in_memory" or "24h"` + The canonical name of the agent that produced this item. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `multi_agent_call: object { id, action, arguments, 3 more }` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `id: string` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The unique ID of the multi-agent call item. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"in_memory"` + The multi-agent action to execute. - - `"24h"` + - `"spawn_agent"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `"interrupt_agent"` - **gpt-5 and o-series models only** + - `"list_agents"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"send_message"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `"followup_task"` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"wait_agent"` - - `"auto"` + - `arguments: string` - - `"current_turn"` + The JSON string of arguments generated for the action. - - `"all_turns"` + - `call_id: string` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The unique ID linking this call to its output. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `type: "multi_agent_call"` - - `"none"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"minimal"` + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"medium"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"xhigh"` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - - `"max"` + - `id: string` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The unique ID of the multi-agent call output item. - **Deprecated:** use `summary` instead. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The multi-agent action that produced this result. - - `"auto"` + - `"spawn_agent"` - - `"concise"` + - `"interrupt_agent"` - - `"detailed"` + - `"list_agents"` - - `mode: optional string or "standard" or "pro"` + - `"send_message"` - Controls the reasoning execution mode for the request. + - `"followup_task"` - When returned on a response, this is the effective execution mode. + - `"wait_agent"` - - `"standard"` + - `call_id: string` - - `"pro"` + The unique ID of the multi-agent call. - - `summary: optional "auto" or "concise" or "detailed"` + - `output: array of BetaResponseOutputText` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + Text output returned by the multi-agent action. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `"auto"` + The annotations of the text output. - - `"concise"` + - `text: string` - - `"detailed"` + The text output from the model. - - `safety_identifier: optional string` + - `type: "output_text"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The type of the output text. Always `output_text`. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - Specifies the processing type used for serving the request. + - `type: "multi_agent_call_output"` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The type of the multi-agent result. Always `multi_agent_call_output`. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `"default"` + - `agent_name: string` - - `"flex"` + The canonical name of the agent that produced this item. - - `"scale"` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `"priority"` + 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. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `id: string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The unique ID of the web search tool call. - - `"completed"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"failed"` + 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). - - `"in_progress"` + - `search: object { type, queries, query, sources }` - - `"cancelled"` + Action type "search" - Performs a web search query. - - `"queued"` + - `type: "search"` - - `"incomplete"` + The action type. - - `text: optional object { format, verbosity }` + - `queries: optional array of string` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The search queries. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `query: optional string` - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + The search query. - An object specifying the format that the model must output. + - `sources: optional array of object { type, url }` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + The sources used in the search. - The default format is `{ "type": "text" }` with no additional options. + - `type: "url"` - **Not recommended for gpt-4o and newer models:** + The type of source. Always `url`. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `url: string` - - `text: object { type }` + The URL of the source. - Default response format. Used to generate text responses. + - `open_page: object { type, url }` - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + Action type "open_page" - Opens a specific URL from search results. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "open_page"` - - `name: string` + The action type. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `url: optional string` - - `schema: map[unknown]` + The URL opened by the model. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `find_in_page: object { pattern, type, url }` - - `type: "json_schema"` + Action type "find_in_page": Searches for a pattern within a loaded page. - The type of response format being defined. Always `json_schema`. + - `pattern: string` - - `description: optional string` + The pattern or text to search for within the page. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `type: "find_in_page"` - - `strict: optional boolean` + The action type. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `url: string` - - `json_object: object { type }` + The URL of the page searched for the pattern. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `verbosity: optional "low" or "medium" or "high"` + The status of the web search tool call. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `"in_progress"` - - `"low"` + - `"searching"` - - `"medium"` + - `"completed"` - - `"high"` + - `"failed"` - - `top_logprobs: optional number` + - `type: "web_search_call"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The type of the web search tool call. Always `web_search_call`. - - `truncation: optional "auto" or "disabled"` + - `agent: optional object { agent_name }` - The truncation strategy to use for the model response. + The agent that produced this item. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"disabled"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + 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. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `id: string` - - `input_tokens: number` + The unique ID of the computer call. - The number of input tokens. + - `call_id: string` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + An identifier used when responding to the tool call with output. - A detailed breakdown of the input tokens. + - `pending_safety_checks: array of object { id, code, message }` - - `cache_write_tokens: number` + The pending safety checks for the computer call. - The number of input tokens that were written to the cache. + - `id: string` - - `cached_tokens: number` + The ID of the pending safety check. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `code: optional string` - - `output_tokens: number` + The type of the pending safety check. - The number of output tokens. + - `message: optional string` - - `output_tokens_details: object { reasoning_tokens }` + Details about the pending safety check. - A detailed breakdown of the output tokens. + - `status: "in_progress" or "completed" or "incomplete"` - - `reasoning_tokens: number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The number of reasoning tokens. + - `"in_progress"` - - `total_tokens: number` + - `"completed"` - The total number of tokens used. + - `"incomplete"` - - `user: optional string` + - `type: "computer_call"` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The type of the computer call. Always `computer_call`. - - `sequence_number: number` + - `"computer_call"` - The sequence number of this event. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `type: "response.in_progress"` + A click action. - The type of the event. Always `response.in_progress`. + - `click: object { button, type, x, 2 more }` - - `agent: optional object { agent_name }` + A click action. - The agent that owns this multi-agent streaming event. + - `button: "left" or "right" or "wheel" or 2 more` - - `agent_name: string` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The canonical name of the agent that produced this item. + - `"left"` -### Beta Response Includable + - `"right"` -- `beta_response_includable: "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more` + - `"wheel"` - Specify additional output data to include in the model response. Currently supported values are: + - `"back"` - - `web_search_call.results`: Include the search results of the web search tool call. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `"forward"` - - `"file_search_call.results"` + - `type: "click"` - - `"web_search_call.results"` + Specifies the event type. For a click action, this property is always `click`. - - `"web_search_call.action.sources"` + - `x: number` - - `"message.input_image.image_url"` + The x-coordinate where the click occurred. - - `"computer_call_output.output.image_url"` + - `y: number` - - `"code_interpreter_call.outputs"` + The y-coordinate where the click occurred. - - `"reasoning.encrypted_content"` + - `keys: optional array of string` - - `"message.output_text.logprobs"` + The keys being held while clicking. -### Beta Response Incomplete Event + - `double_click: object { keys, type, x, y }` -- `beta_response_incomplete_event: object { response, sequence_number, type, agent }` + A double click action. - An event that is emitted when a response finishes as incomplete. + - `keys: array of string` - - `response: object { id, created_at, error, 31 more }` + The keys being held while double-clicking. - The response that was incomplete. + - `type: "double_click"` - - `id: string` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Unique identifier for this Response. + - `x: number` - - `created_at: number` + The x-coordinate where the double click occurred. - Unix timestamp (in seconds) of when this Response was created. + - `y: number` - - `error: object { code, message }` + The y-coordinate where the double click occurred. - An error object returned when the model fails to generate a Response. + - `drag: object { path, type, keys }` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + A drag action. - The error code for the response. + - `path: array of object { x, y }` - - `"server_error"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"rate_limit_exceeded"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"invalid_prompt"` + - `x: number` - - `"bio_policy"` + The x-coordinate. - - `"vector_store_timeout"` + - `y: number` - - `"invalid_image"` + The y-coordinate. - - `"invalid_image_format"` + - `type: "drag"` - - `"invalid_base64_image"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"invalid_image_url"` + - `keys: optional array of string` - - `"image_too_large"` + The keys being held while dragging the mouse. - - `"image_too_small"` + - `keypress: object { keys, type }` - - `"image_parse_error"` + A collection of keypresses the model would like to perform. - - `"image_content_policy_violation"` + - `keys: array of string` - - `"invalid_image_mode"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"image_file_too_large"` + - `type: "keypress"` - - `"unsupported_image_media_type"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"empty_image_file"` + - `move: object { type, x, y, keys }` - - `"failed_to_download_image"` + A mouse move action. - - `"image_file_not_found"` + - `type: "move"` - - `message: string` + Specifies the event type. For a move action, this property is always set to `move`. - A human-readable description of the error. + - `x: number` - - `incomplete_details: object { reason }` + The x-coordinate to move to. - Details about why the response is incomplete. + - `y: number` - - `reason: optional "max_output_tokens" or "content_filter"` + The y-coordinate to move to. - The reason why the response is incomplete. + - `keys: optional array of string` - - `"max_output_tokens"` + The keys being held while moving the mouse. - - `"content_filter"` + - `screenshot: object { type }` - - `instructions: string or array of BetaResponseInputItem` + A screenshot action. - A system (or developer) message inserted into the model's context. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - When using 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. + A scroll action. - - `union_member_0: string` + - `scroll_x: number` - A text input to the model, equivalent to a text input with the - `developer` role. + The horizontal scroll distance. - - `Input item list: array of BetaResponseInputItem` + - `scroll_y: number` - A list of one or many input items to the model, containing - different content types. + The vertical scroll distance. - - `beta_easy_input_message: object { content, role, phase, type }` + - `type: "scroll"` - 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. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `content: string or BetaResponseInputMessageContentList` + - `x: number` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The x-coordinate where the scroll occurred. - - `Text input: string` + - `y: number` - A text input to the model. + The y-coordinate where the scroll occurred. - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `keys: optional array of string` - A list of one or many input items to the model, containing different content - types. + The keys being held while scrolling. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `type: object { text, type }` - A text input to the model. + An action to type in text. - `text: string` - The text input to the model. + The text to type. - - `type: "input_text"` + - `type: "type"` - The type of the input item. Always `input_text`. + Specifies the event type. For a type action, this property is always set to `type`. - - `prompt_cache_breakpoint: optional object { mode }` + - `wait: object { type }` - 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. + A wait action. - - `mode: "explicit"` + - `actions: optional array of BetaComputerAction` - The breakpoint mode. Always `explicit`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `click: object { button, type, x, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A click action. - - `detail: "low" or "high" or "auto" or "original"` + - `double_click: object { keys, type, x, y }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A double click action. - - `"low"` + - `drag: object { path, type, keys }` - - `"high"` + A drag action. - - `"auto"` + - `keypress: object { keys, type }` - - `"original"` + A collection of keypresses the model would like to perform. - - `type: "input_image"` + - `move: object { type, x, y, keys }` - The type of the input item. Always `input_image`. + A mouse move action. - - `file_id: optional string` + - `screenshot: object { type }` - The ID of the file to be sent to the model. + A screenshot action. - - `image_url: optional string` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A scroll action. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: object { text, type }` - 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. + An action to type in text. - - `mode: "explicit"` + - `wait: object { type }` - The breakpoint mode. Always `explicit`. + A wait action. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `agent: optional object { agent_name }` - A file input to the model. + The agent that produced this item. - - `type: "input_file"` + - `agent_name: string` - The type of the input item. Always `input_file`. + The canonical name of the agent that produced this item. - - `detail: optional "auto" or "low" or "high"` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - 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`. + - `id: string` - - `"auto"` + The unique ID of the computer call tool output. - - `"low"` + - `call_id: string` - - `"high"` + The ID of the computer tool call that produced the output. - - `file_data: optional string` + - `output: object { type, file_id, image_url }` - The content of the file to be sent to the model. + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - `file_id: optional string` - The ID of the file to be sent to the model. + The identifier of an uploaded file that contains the screenshot. - - `file_url: optional string` + - `image_url: optional string` - The URL of the file to be sent to the model. + The URL of the screenshot image. - - `filename: optional string` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The name of the file to be sent to the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `prompt_cache_breakpoint: optional object { mode }` + - `"completed"` - 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. + - `"incomplete"` - - `mode: "explicit"` + - `"failed"` - The breakpoint mode. Always `explicit`. + - `"in_progress"` - - `role: "user" or "assistant" or "system" or "developer"` + - `type: "computer_call_output"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The type of the computer tool call output. Always `computer_call_output`. - - `"user"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"assistant"` + The safety checks reported by the API that have been acknowledged by the + developer. - - `"system"` + - `id: string` - - `"developer"` + The ID of the pending safety check. - - `phase: optional "commentary"` + - `code: optional string` - 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. + The type of the pending safety check. - - `"commentary"` + - `message: optional string` - - `type: optional "message"` + Details about the pending safety check. - The type of the message input. Always `message`. + - `agent: optional object { agent_name }` - - `"message"` + The agent that produced this item. - - `message: object { content, role, agent, 2 more }` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - - `content: array of BetaResponseInputContent` + - `created_by: optional string` - A list of one or many input items to the model, containing different content - types. + The identifier of the actor that created the item. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - A text input to the model. + 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). - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `id: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The unique identifier of the reasoning content. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `summary: array of object { text, type }` - A file input to the model. + Reasoning summary content. - - `role: "user" or "system" or "developer"` + - `text: string` - The role of the message input. One of `user`, `system`, or `developer`. + A summary of the reasoning output from the model so far. - - `"user"` + - `type: "summary_text"` - - `"system"` + The type of the object. Always `summary_text`. - - `"developer"` + - `type: "reasoning"` + + The type of the object. Always `reasoning`. - `agent: optional object { agent_name }` @@ -77771,9 +89454,26 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of item. One of `in_progress`, `completed`, or + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -77782,242 +89482,246 @@ openai beta:responses compact \ - `"incomplete"` - - `type: optional "message"` + - `program: object { id, call_id, code, 3 more }` - The type of the message input. Always set to `message`. + - `id: string` - - `"message"` + The unique ID of the program item. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `call_id: string` - An output message from the model. + The stable call ID of the program item. - - `id: string` + - `code: string` - The unique ID of the output message. + The JavaScript source executed by programmatic tool calling. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `fingerprint: string` - The content of the output message. + Opaque program replay fingerprint that must be round-tripped. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `type: "program"` - A text output from the model. + The type of the item. Always `program`. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `agent: optional object { agent_name }` - The annotations of the text output. + The agent that produced this item. - - `file_citation: object { file_id, filename, index, type }` + - `agent_name: string` - A citation to a file. + The canonical name of the agent that produced this item. - - `file_id: string` + - `program_output: object { id, call_id, result, 3 more }` - The ID of the file. + - `id: string` - - `filename: string` + The unique ID of the program output item. - The filename of the file cited. + - `call_id: string` - - `index: number` + The call ID of the program item. - The index of the file in the list of files. + - `result: string` - - `type: "file_citation"` + The result produced by the program item. - The type of the file citation. Always `file_citation`. + - `status: "completed" or "incomplete"` - - `url_citation: object { end_index, start_index, title, 2 more }` + The terminal status of the program output item. - A citation for a web resource used to generate a model response. + - `"completed"` - - `end_index: number` + - `"incomplete"` - The index of the last character of the URL citation in the message. + - `type: "program_output"` - - `start_index: number` + The type of the item. Always `program_output`. - The index of the first character of the URL citation in the message. + - `agent: optional object { agent_name }` - - `title: string` + The agent that produced this item. - The title of the web resource. + - `agent_name: string` - - `type: "url_citation"` + The canonical name of the agent that produced this item. - The type of the URL citation. Always `url_citation`. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `url: string` + - `id: string` - The URL of the web resource. + The unique ID of the tool search call item. - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `arguments: unknown` - A citation for a container file used to generate a model response. + Arguments used for the tool search call. - - `container_id: string` + - `call_id: string` - The ID of the container file. + The unique ID of the tool search call generated by the model. - - `end_index: number` + - `execution: "server" or "client"` - The index of the last character of the container file citation in the message. + Whether tool search was executed by the server or by the client. - - `file_id: string` + - `"server"` - The ID of the file. + - `"client"` - - `filename: string` + - `status: "in_progress" or "completed" or "incomplete"` - The filename of the container file cited. + The status of the tool search call item that was recorded. - - `start_index: number` + - `"in_progress"` - The index of the first character of the container file citation in the message. + - `"completed"` - - `type: "container_file_citation"` + - `"incomplete"` - The type of the container file citation. Always `container_file_citation`. + - `type: "tool_search_call"` - - `file_path: object { file_id, index, type }` + The type of the item. Always `tool_search_call`. - A path to a file. + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The ID of the file. + - `agent_name: string` - - `index: number` + The canonical name of the agent that produced this item. - The index of the file in the list of files. + - `created_by: optional string` - - `type: "file_path"` + The identifier of the actor that created the item. - The type of the file path. Always `file_path`. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `text: string` + - `id: string` - The text output from the model. + The unique ID of the tool search output item. - - `type: "output_text"` + - `call_id: string` - The type of the output text. Always `output_text`. + The unique ID of the tool search call generated by the model. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `execution: "server" or "client"` - - `token: string` + Whether tool search was executed by the server or by the client. - - `bytes: array of number` + - `"server"` - - `logprob: number` + - `"client"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `status: "in_progress" or "completed" or "incomplete"` - - `token: string` + The status of the tool search output item that was recorded. - - `bytes: array of number` + - `"in_progress"` - - `logprob: number` + - `"completed"` - - `beta_response_output_refusal: object { refusal, type }` + - `"incomplete"` - A refusal from the model. + - `tools: array of BetaTool` - - `refusal: string` + The loaded tool definitions returned by tool search. - The refusal explanation from the model. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `type: "refusal"` + 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). - The type of the refusal. Always `refusal`. + - `name: string` - - `role: "assistant"` + The name of the function to call. - The role of the output message. Always `assistant`. + - `parameters: map[unknown]` - - `status: "in_progress" or "completed" or "incomplete"` + A JSON schema object describing the parameters of the function. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `strict: boolean` - - `"in_progress"` + Whether strict parameter validation is enforced for this function tool. - - `"completed"` + - `type: "function"` - - `"incomplete"` + The type of the function tool. Always `function`. - - `type: "message"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the output message. Always `message`. + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this function is deferred and loaded via tool search. - - `phase: optional "commentary"` + - `description: optional string` - 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. + A description of the function. Used by the model to determine whether or not to call the function. - - `"commentary"` + - `output_schema: optional map[unknown]` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - 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. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `id: string` + 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). - The unique ID of the file search tool call. + - `type: "file_search"` - - `queries: array of string` + The type of the file search tool. Always `file_search`. - The queries used to search for files. + - `vector_store_ids: array of string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The IDs of the vector stores to search. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `filters: optional object { key, type, value } or object { filters, type }` - - `"in_progress"` + A filter to apply. - - `"searching"` + - `Comparison Filter: object { key, type, value }` - - `"completed"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"incomplete"` + - `key: string` - - `"failed"` + The key to compare against the value. - - `type: "file_search_call"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of the file search tool call. Always `file_search_call`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent: optional object { agent_name }` + - `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 - The agent that produced this item. + - `"eq"` - - `agent_name: string` + - `"ne"` - The canonical name of the agent that produced this item. + - `"gt"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"gte"` - The results of the file search tool call. + - `"lt"` - - `attributes: optional map[string or number or boolean]` + - `"lte"` - 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. + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. - `union_member_0: string` @@ -78025,906 +89729,944 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `file_id: optional string` + - `union_member_3: array of string or number` - The unique ID of the file. + - `union_member_0: string` - - `filename: optional string` + - `union_member_1: number` - The name of the file. + - `Compound Filter: object { filters, type }` - - `score: optional number` + Combine multiple filters using `and` or `or`. - The relevance score of the file - a value between 0 and 1. + - `filters: array of object { key, type, value } or unknown` - - `text: optional string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The text that was retrieved from the file. + - `Comparison Filter: object { key, type, value }` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - 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. + - `key: string` - - `id: string` + The key to compare against the value. - The unique ID of the computer call. + - `type: "eq" or "ne" or "gt" or 5 more` - - `call_id: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - An identifier used when responding to the tool call with output. + - `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 - - `pending_safety_checks: array of object { id, code, message }` + - `"eq"` - The pending safety checks for the computer call. + - `"ne"` - - `id: string` + - `"gt"` - The ID of the pending safety check. + - `"gte"` - - `code: optional string` + - `"lt"` - The type of the pending safety check. + - `"lte"` - - `message: optional string` + - `"in"` - Details about the pending safety check. + - `"nin"` - - `status: "in_progress" or "completed" or "incomplete"` + - `value: string or number or boolean or array of string or number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"in_progress"` + - `union_member_0: string` - - `"completed"` + - `union_member_1: number` - - `"incomplete"` + - `union_member_2: boolean` - - `type: "computer_call"` + - `union_member_3: array of string or number` - The type of the computer call. Always `computer_call`. + - `union_member_0: string` - - `"computer_call"` + - `union_member_1: number` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `union_member_1: unknown` - A click action. + - `type: "and" or "or"` - - `click: object { button, type, x, 2 more }` + Type of operation: `and` or `or`. - A click action. + - `"and"` - - `button: "left" or "right" or "wheel" or 2 more` + - `"or"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `max_num_results: optional number` - - `"left"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"right"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"wheel"` + Ranking options for search. - - `"back"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"forward"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: "click"` + - `embedding_weight: number` - Specifies the event type. For a click action, this property is always `click`. + The weight of the embedding in the reciprocal ranking fusion. - - `x: number` + - `text_weight: number` - The x-coordinate where the click occurred. + The weight of the text in the reciprocal ranking fusion. - - `y: number` + - `ranker: optional "auto" or "default-2024-11-15"` - The y-coordinate where the click occurred. + The ranker to use for the file search. - - `keys: optional array of string` + - `"auto"` - The keys being held while clicking. + - `"default-2024-11-15"` - - `double_click: object { keys, type, x, y }` + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `beta_computer_tool: object { type }` - A double click action. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `keys: array of string` + - `type: "computer"` - The keys being held while double-clicking. + The type of the computer tool. Always `computer`. - - `type: "double_click"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `x: number` + - `display_height: number` - The x-coordinate where the double click occurred. + The height of the computer display. - - `y: number` + - `display_width: number` - The y-coordinate where the double click occurred. + The width of the computer display. - - `drag: object { path, type, keys }` + - `environment: "windows" or "mac" or "linux" or 2 more` - A drag action. + The type of computer environment to control. - - `path: array of object { x, y }` + - `"windows"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"mac"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"linux"` - - `x: number` + - `"ubuntu"` - The x-coordinate. + - `"browser"` - - `y: number` + - `type: "computer_use_preview"` - The y-coordinate. + The type of the computer use tool. Always `computer_use_preview`. - - `type: "drag"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - Specifies the event type. For a drag action, this property is always set to `drag`. + 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). - - `keys: optional array of string` + - `type: "web_search" or "web_search_2025_08_26"` - The keys being held while dragging the mouse. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `keypress: object { keys, type }` + - `"web_search"` - A collection of keypresses the model would like to perform. + - `"web_search_2025_08_26"` - - `keys: array of string` + - `filters: optional object { allowed_domains }` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Filters for the search. - - `type: "keypress"` + - `allowed_domains: optional array of string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `move: object { type, x, y, keys }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - A mouse move action. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "move"` + 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. - Specifies the event type. For a move action, this property is always set to `move`. + - `"low"` - - `x: number` + - `"medium"` - The x-coordinate to move to. + - `"high"` - - `y: number` + - `user_location: optional object { city, country, region, 2 more }` - The y-coordinate to move to. + The approximate location of the user. - - `keys: optional array of string` + - `city: optional string` - The keys being held while moving the mouse. + Free text input for the city of the user, e.g. `San Francisco`. - - `screenshot: object { type }` + - `country: optional string` - A screenshot action. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `region: optional string` - A scroll action. + Free text input for the region of the user, e.g. `California`. - - `scroll_x: number` + - `timezone: optional string` - The horizontal scroll distance. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `scroll_y: number` + - `type: optional "approximate"` - The vertical scroll distance. + The type of location approximation. Always `approximate`. - - `type: "scroll"` + - `"approximate"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `x: number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The x-coordinate where the scroll occurred. + - `server_label: string` - - `y: number` + A label for this MCP server, used to identify it in tool calls. - The y-coordinate where the scroll occurred. + - `type: "mcp"` - - `keys: optional array of string` + The type of the MCP tool. Always `mcp`. - The keys being held while scrolling. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: object { text, type }` + The tool invocation context(s). - An action to type in text. + - `"direct"` - - `text: string` + - `"programmatic"` - The text to type. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "type"` + List of allowed tool names or a filter object. - Specifies the event type. For a type action, this property is always set to `type`. + - `MCP allowed tools: array of string` - - `wait: object { type }` + A string array of allowed tool names - A wait action. + - `MCP tool filter: object { read_only, tool_names }` - - `actions: optional array of BetaComputerAction` + A filter object to specify which tools are allowed. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `read_only: optional boolean` - - `click: object { button, type, x, 2 more }` + 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. - A click action. + - `tool_names: optional array of string` - - `double_click: object { keys, type, x, y }` + List of allowed tool names. - A double click action. + - `authorization: optional string` - - `drag: object { path, type, keys }` + 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. - A drag action. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `keypress: object { keys, type }` + 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). - A collection of keypresses the model would like to perform. + Currently supported `connector_id` values are: - - `move: object { type, x, y, keys }` + - 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` - A mouse move action. + - `"connector_dropbox"` - - `screenshot: object { type }` + - `"connector_gmail"` - A screenshot action. + - `"connector_googlecalendar"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"connector_googledrive"` - A scroll action. + - `"connector_microsoftteams"` - - `type: object { text, type }` + - `"connector_outlookcalendar"` - An action to type in text. + - `"connector_outlookemail"` - - `wait: object { type }` + - `"connector_sharepoint"` - A wait action. + - `defer_loading: optional boolean` - - `agent: optional object { agent_name }` + Whether this MCP tool is deferred and discovered via tool search. - The agent that produced this item. + - `headers: optional map[string]` - - `agent_name: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The canonical name of the agent that produced this item. + - `require_approval: optional object { always, never } or "always" or "never"` - - `computer_call_output: object { call_id, output, type, 4 more }` + Specify which of the MCP server's tools require approval. - The output of a computer tool call. + - `MCP tool approval filter: object { always, never }` - - `call_id: string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The ID of the computer tool call that produced the output. + - `always: optional object { read_only, tool_names }` - - `output: object { type, file_id, image_url }` + A filter object to specify which tools are allowed. - A computer screenshot image used with the computer use tool. + - `read_only: optional boolean` - - `type: "computer_screenshot"` + 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. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `tool_names: optional array of string` - - `file_id: optional string` + List of allowed tool names. - The identifier of an uploaded file that contains the screenshot. + - `never: optional object { read_only, tool_names }` - - `image_url: optional string` + A filter object to specify which tools are allowed. - The URL of the screenshot image. + - `read_only: optional boolean` - - `type: "computer_call_output"` + 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. - The type of the computer tool call output. Always `computer_call_output`. + - `tool_names: optional array of string` - - `id: optional string` + List of allowed tool names. - The ID of the computer tool call output. + - `MCP tool approval setting: "always" or "never"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + 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. - The safety checks reported by the API that have been acknowledged by the developer. + - `"always"` - - `id: string` + - `"never"` - The ID of the pending safety check. + - `server_description: optional string` - - `code: optional string` + Optional description of the MCP server, used to provide more context. - The type of the pending safety check. + - `server_url: optional string` - - `message: optional string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Details about the pending safety check. + - `tunnel_id: optional string` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + - `code_interpreter: object { container, type, allowed_callers }` - - `agent_name: string` + A tool that runs Python code to help generate a response to a prompt. - The canonical name of the agent that produced this item. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `status: optional "in_progress" or "completed" or "incomplete"` + 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. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `union_member_0: string` - - `"in_progress"` + The container ID. - - `"completed"` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `"incomplete"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `type: "auto"` - 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. + Always `auto`. - - `id: string` + - `file_ids: optional array of string` - The unique ID of the web search tool call. + An optional list of uploaded files to make available to your code. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - 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). + The memory limit for the code interpreter container. - - `search: object { type, queries, query, sources }` + - `"1g"` - Action type "search" - Performs a web search query. + - `"4g"` - - `type: "search"` + - `"16g"` - The action type. + - `"64g"` - - `queries: optional array of string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The search queries. + Network access policy for the container. - - `query: optional string` + - `beta_container_network_policy_disabled: object { type }` - The search query. + - `type: "disabled"` - - `sources: optional array of object { type, url }` + Disable outbound network access. Always `disabled`. - The sources used in the search. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `type: "url"` + - `allowed_domains: array of string` - The type of source. Always `url`. + A list of allowed domains when type is `allowlist`. - - `url: string` + - `type: "allowlist"` - The URL of the source. + Allow outbound network access only to specified domains. Always `allowlist`. - - `open_page: object { type, url }` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - Action type "open_page" - Opens a specific URL from search results. + Optional domain-scoped secrets for allowlisted domains. - - `type: "open_page"` + - `domain: string` - The action type. + The domain associated with the secret. - - `url: optional string` + - `name: string` - The URL opened by the model. + The name of the secret to inject for the domain. - - `find_in_page: object { pattern, type, url }` + - `value: string` - Action type "find_in_page": Searches for a pattern within a loaded page. + The secret value to inject for the domain. - - `pattern: string` + - `type: "code_interpreter"` - The pattern or text to search for within the page. + The type of the code interpreter tool. Always `code_interpreter`. - - `type: "find_in_page"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The action type. + The tool invocation context(s). - - `url: string` + - `"direct"` - The URL of the page searched for the pattern. + - `"programmatic"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `programmatic_tool_calling: object { type }` - The status of the web search tool call. + - `image_generation: object { type, action, background, 9 more }` - - `"in_progress"` + A tool that generates images using the GPT image models. - - `"searching"` + - `type: "image_generation"` - - `"completed"` + The type of the image generation tool. Always `image_generation`. - - `"failed"` + - `action: optional "generate" or "edit" or "auto"` - - `type: "web_search_call"` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the web search tool call. Always `web_search_call`. + - `"generate"` - - `agent: optional object { agent_name }` + - `"edit"` - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `background: optional "transparent" or "opaque" or "auto"` - The canonical name of the agent that produced this item. + 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. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + `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. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `arguments: string` + - `"transparent"` - A JSON string of the arguments to pass to the function. + - `"opaque"` - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `input_fidelity: optional "high" or "low"` - - `name: string` + 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`. - The name of the function to run. + - `"high"` - - `type: "function_call"` + - `"low"` - The type of the function tool call. Always `function_call`. + - `input_image_mask: optional object { file_id, image_url }` - - `id: optional string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The unique ID of the function tool call. + - `file_id: optional string` - - `agent: optional object { agent_name }` + File ID for the mask image. - The agent that produced this item. + - `image_url: optional string` - - `agent_name: string` + Base64-encoded mask image. - The canonical name of the agent that produced this item. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `caller: optional object { type } or object { caller_id, type }` + The image generation model to use. Default: `gpt-image-1`. - The execution context that produced this tool call. + - `"gpt-image-1"` - - `direct: object { type }` + - `"gpt-image-1-mini"` - - `program: object { caller_id, type }` + - `"gpt-image-2"` - - `caller_id: string` + - `"gpt-image-2-2026-04-21"` - The call ID of the program item that produced this tool call. + - `"gpt-image-1.5"` - - `type: "program"` + - `"chatgpt-image-latest"` - - `namespace: optional string` + - `moderation: optional "auto" or "low"` - The namespace of the function to run. + Moderation level for the generated image. Default: `auto`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"low"` - - `"in_progress"` + - `output_compression: optional number` - - `"completed"` + Compression level for the output image. Default: 100. - - `"incomplete"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `function_call_output: object { call_id, output, type, 4 more }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The output of a function tool call. + - `"png"` - - `call_id: string` + - `"webp"` - The unique ID of the function tool call generated by the model. + - `"jpeg"` - - `output: string or BetaResponseFunctionCallOutputItemList` + - `partial_images: optional number` - Text, image, or file output of the function tool call. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `union_member_0: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - A JSON string of the output of the function tool call. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + - `"low"` - An array of content outputs (text, image, file) for the function tool call. + - `"medium"` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `"high"` - A text input to the model. + - `"auto"` - - `text: string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The text input to the model. + 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`. - - `type: "input_text"` + - `"1024x1024"` - The type of the input item. Always `input_text`. + - `"1024x1536"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"1536x1024"` - 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. + - `"auto"` - - `mode: "explicit"` + - `local_shell: object { type }` - The breakpoint mode. Always `explicit`. + A tool that allows the model to execute shell commands in a local environment. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + A tool that allows the model to execute shell commands. - - `type: "input_image"` + - `type: "shell"` - The type of the input item. Always `input_image`. + The type of the shell tool. Always `shell`. - - `detail: optional "low" or "high" or "auto" or "original"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The tool invocation context(s). - - `"low"` + - `"direct"` - - `"high"` + - `"programmatic"` - - `"auto"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"original"` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `file_id: optional string` + - `type: "container_auto"` - The ID of the file to be sent to the model. + Automatically creates a container for this request - - `image_url: optional string` + - `file_ids: optional array of string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + An optional list of uploaded files to make available to your code. - - `prompt_cache_breakpoint: optional object { mode }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - 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. + The memory limit for the container. - - `mode: "explicit"` + - `"1g"` - The breakpoint mode. Always `explicit`. + - `"4g"` - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `"16g"` - A file input to the model. + - `"64g"` - - `type: "input_file"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The type of the input item. Always `input_file`. + Network access policy for the container. - - `detail: optional "auto" or "low" or "high"` + - `beta_container_network_policy_disabled: object { type }` - 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`. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `"auto"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"low"` + An optional list of skills referenced by id or inline data. - - `"high"` + - `beta_skill_reference: object { skill_id, type, version }` - - `file_data: optional string` + - `skill_id: string` - The base64-encoded data of the file to be sent to the model. + The ID of the referenced skill. - - `file_id: optional string` + - `type: "skill_reference"` - The ID of the file to be sent to the model. + References a skill created with the /v1/skills endpoint. - - `file_url: optional string` + - `version: optional string` - The URL of the file to be sent to the model. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `filename: optional string` + - `beta_inline_skill: object { description, name, source, type }` - The name of the file to be sent to the model. + - `description: string` - - `prompt_cache_breakpoint: optional object { mode }` + The description of the skill. - 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. + - `name: string` - - `mode: "explicit"` + The name of the skill. - The breakpoint mode. Always `explicit`. + - `source: object { data, media_type, type }` - - `type: "function_call_output"` + Inline skill payload - The type of the function tool call output. Always `function_call_output`. + - `data: string` - - `id: optional string` + Base64-encoded skill zip bundle. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `media_type: "application/zip"` - - `agent: optional object { agent_name }` + The media type of the inline skill payload. Must be `application/zip`. - The agent that produced this item. + - `type: "base64"` - - `agent_name: string` + The type of the inline skill source. Must be `base64`. - The canonical name of the agent that produced this item. + - `type: "inline"` - - `caller: optional object { type } or object { caller_id, type }` + Defines an inline skill for this request. - The execution context that produced this tool call. + - `beta_local_environment: object { type, skills }` - - `direct: object { type }` + - `type: "local"` - - `program: object { caller_id, type }` + Use a local computer environment. - - `caller_id: string` + - `skills: optional array of BetaLocalSkill` - The call ID of the program item that produced this tool call. + An optional list of skills. - - `type: "program"` + - `description: string` - The caller type. Always `program`. + The description of the skill. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The name of the skill. - - `"in_progress"` + - `path: string` - - `"completed"` + The path to the directory containing the skill. - - `"incomplete"` + - `beta_container_reference: object { container_id, type }` - - `agent_message: object { author, content, recipient, 3 more }` + - `container_id: string` - A message routed between agents. + The ID of the referenced container. - - `author: string` + - `type: "container_reference"` - The sending agent identity. + References a container created with the /v1/containers endpoint - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Plaintext, image, or encrypted content sent between agents. + 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) - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `name: string` - A text input to the model. + The name of the custom tool, used to identify it in tool calls. - - `text: string` + - `type: "custom"` - The text input to the model. + The type of the custom tool. Always `custom`. - - `type: "input_text"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the input item. Always `input_text`. + The tool invocation context(s). - - `prompt_cache_breakpoint: optional object { mode }` + - `"direct"` - 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. + - `"programmatic"` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `defer_loading: optional boolean` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + Whether this tool should be deferred and discovered via tool search. - - `type: "input_image"` + - `description: optional string` - The type of the input item. Always `input_image`. + Optional description of the custom tool, used to provide more context. - - `detail: optional "low" or "high" or "auto" or "original"` + - `format: optional object { type } or object { definition, syntax, type }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The input format for the custom tool. Default is unconstrained text. - - `file_id: optional string` + - `text: object { type }` - The ID of the file to be sent to the model. + Unconstrained free-form text. - - `image_url: optional string` + - `grammar: object { definition, syntax, type }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A grammar defined by the user. - - `prompt_cache_breakpoint: optional object { mode }` + - `definition: string` - 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. + The grammar definition. - - `encrypted_content: object { encrypted_content, type }` + - `syntax: "lark" or "regex"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The syntax of the grammar definition. One of `lark` or `regex`. - - `encrypted_content: string` + - `"lark"` - Opaque encrypted content. + - `"regex"` - - `type: "encrypted_content"` + - `type: "grammar"` - The type of the input item. Always `encrypted_content`. + Grammar format. Always `grammar`. - - `recipient: string` + - `beta_namespace_tool: object { description, name, tools, type }` - The destination agent identity. + Groups function/custom tools under a shared namespace. - - `type: "agent_message"` + - `description: string` - The item type. Always `agent_message`. + A description of the namespace shown to the model. - - `id: optional string` + - `name: string` - The unique ID of this agent message item. + The namespace name used in tool calls (for example, `crm`). - - `agent: optional object { agent_name }` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - The agent that produced this item. + The function/custom tools available inside this namespace. - - `agent_name: string` + - `function: object { name, type, allowed_callers, 5 more }` - The canonical name of the agent that produced this item. + - `name: string` - - `multi_agent_call: object { action, arguments, call_id, 3 more }` + - `type: "function"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `allowed_callers: optional array of "direct" or "programmatic"` - The multi-agent action that was executed. + The tool invocation context(s). - - `"spawn_agent"` + - `"direct"` - - `"interrupt_agent"` + - `"programmatic"` - - `"list_agents"` + - `defer_loading: optional boolean` - - `"send_message"` + Whether this function should be deferred and discovered via tool search. - - `"followup_task"` + - `description: optional string` - - `"wait_agent"` + - `output_schema: optional map[unknown]` - - `arguments: string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The action arguments as a JSON string. + - `parameters: optional unknown` - - `call_id: string` + - `strict: optional boolean` - The unique ID linking this call to its output. + 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. - - `type: "multi_agent_call"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The item type. Always `multi_agent_call`. + 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) - - `id: optional string` + - `name: string` - The unique ID of this multi-agent call. + The name of the custom tool, used to identify it in tool calls. - - `agent: optional object { agent_name }` + - `type: "custom"` - The agent that produced this item. + The type of the custom tool. Always `custom`. - - `agent_name: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The canonical name of the agent that produced this item. + The tool invocation context(s). - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + - `defer_loading: optional boolean` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Whether this tool should be deferred and discovered via tool search. - The multi-agent action that produced this result. + - `description: optional string` - - `"spawn_agent"` + Optional description of the custom tool, used to provide more context. - - `"interrupt_agent"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"list_agents"` + The input format for the custom tool. Default is unconstrained text. - - `"send_message"` + - `type: "namespace"` - - `"followup_task"` + The type of the tool. Always `namespace`. - - `"wait_agent"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `call_id: string` + Hosted or BYOT tool search configuration for deferred tools. - The unique ID of the multi-agent call. + - `type: "tool_search"` - - `output: array of object { text, type, annotations }` + The type of the tool. Always `tool_search`. - Text output returned by the multi-agent action. + - `description: optional string` - - `text: string` + Description shown to the model for a client-executed tool search tool. - The text content. + - `execution: optional "server" or "client"` - - `type: "output_text"` + Whether tool search is executed by the server or by the client. - The content type. Always `output_text`. + - `"server"` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `"client"` - Citations associated with the text content. + - `parameters: optional unknown` - - `union_member_0: array of object { file_id, filename, index, type }` + Parameter schema for a client-executed tool search tool. - - `file_id: string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The ID of the file. + 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). - - `filename: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The filename of the file cited. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `index: number` + - `"web_search_preview"` - The index of the file in the list of files. + - `"web_search_preview_2025_03_11"` - - `type: "file_citation"` + - `search_content_types: optional array of "text" or "image"` - The citation type. Always `file_citation`. + - `"text"` - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + - `"image"` - - `end_index: number` + - `search_context_size: optional "low" or "medium" or "high"` - The index of the last character of the citation in the message. + 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. - - `start_index: number` + - `"low"` - The index of the first character of the citation in the message. + - `"medium"` - - `title: string` + - `"high"` - The title of the cited resource. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "url_citation"` + The user's location. - The citation type. Always `url_citation`. + - `type: "approximate"` - - `url: string` + The type of location approximation. Always `approximate`. - The URL of the cited resource. + - `city: optional string` - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + Free text input for the city of the user, e.g. `San Francisco`. - - `container_id: string` + - `country: optional string` - The ID of the container. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `end_index: number` + - `region: optional string` - The index of the last character of the citation in the message. + Free text input for the region of the user, e.g. `California`. - - `file_id: string` + - `timezone: optional string` - The ID of the container file. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `filename: string` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The filename of the container file cited. + Allows the assistant to create, delete, or update files using unified diffs. - - `start_index: number` + - `type: "apply_patch"` - The index of the first character of the citation in the message. + The type of the tool. Always `apply_patch`. - - `type: "container_file_citation"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The citation type. Always `container_file_citation`. + The tool invocation context(s). - - `type: "multi_agent_call_output"` + - `"direct"` - The item type. Always `multi_agent_call_output`. + - `"programmatic"` - - `id: optional string` + - `type: "tool_search_output"` - The unique ID of this multi-agent call output. + The type of the item. Always `tool_search_output`. - `agent: optional object { agent_name }` @@ -78934,1117 +90676,1085 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `tool_search_call: object { arguments, type, id, 4 more }` + - `created_by: optional string` - - `arguments: unknown` + The identifier of the actor that created the item. - The arguments supplied to the tool search call. + - `additional_tools: object { id, role, tools, 2 more }` - - `type: "tool_search_call"` + - `id: string` - The item type. Always `tool_search_call`. + The unique ID of the additional tools item. - - `id: optional string` + - `role: "unknown" or "user" or "assistant" or 5 more` - The unique ID of this tool search call. + The role that provided the additional tools. - - `agent: optional object { agent_name }` + - `"unknown"` - The agent that produced this item. + - `"user"` - - `agent_name: string` + - `"assistant"` - The canonical name of the agent that produced this item. + - `"system"` - - `call_id: optional string` + - `"critic"` - The unique ID of the tool search call generated by the model. + - `"discriminator"` - - `execution: optional "server" or "client"` + - `"developer"` - Whether tool search was executed by the server or by the client. + - `"tool"` - - `"server"` + - `tools: array of BetaTool` - - `"client"` + The additional tool definitions made available at this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The status of the tool search call. + 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). - - `"in_progress"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"completed"` + 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). - - `"incomplete"` + - `beta_computer_tool: object { type }` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `tools: array of BetaTool` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The loaded tool definitions returned by the tool search output. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - 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). + 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). - - `name: string` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The name of the function to call. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `parameters: map[unknown]` + - `code_interpreter: object { container, type, allowed_callers }` - A JSON schema object describing the parameters of the function. + A tool that runs Python code to help generate a response to a prompt. - - `strict: boolean` + - `programmatic_tool_calling: object { type }` - Whether strict parameter validation is enforced for this function tool. + - `image_generation: object { type, action, background, 9 more }` - - `type: "function"` + A tool that generates images using the GPT image models. - The type of the function tool. Always `function`. + - `local_shell: object { type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A tool that allows the model to execute shell commands in a local environment. - The tool invocation context(s). + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"direct"` + A tool that allows the model to execute shell commands. - - `"programmatic"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `defer_loading: optional boolean` + 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) - Whether this function is deferred and loaded via tool search. + - `beta_namespace_tool: object { description, name, tools, type }` - - `description: optional string` + Groups function/custom tools under a shared namespace. - A description of the function. Used by the model to determine whether or not to call the function. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `output_schema: optional map[unknown]` + Hosted or BYOT tool search configuration for deferred tools. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + 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). - 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). + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `type: "file_search"` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the file search tool. Always `file_search`. + - `type: "additional_tools"` - - `vector_store_ids: array of string` + The type of the item. Always `additional_tools`. - The IDs of the vector stores to search. + - `agent: optional object { agent_name }` - - `filters: optional object { key, type, value } or object { filters, type }` + The agent that produced this item. - A filter to apply. + - `agent_name: string` - - `Comparison Filter: object { key, type, value }` + The canonical name of the agent that produced this item. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - `key: string` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The key to compare against the value. + - `id: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The unique ID of the compaction item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `encrypted_content: string` - - `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 + The encrypted content that was produced by compaction. - - `"eq"` + - `type: "compaction"` - - `"ne"` + The type of the item. Always `compaction`. - - `"gt"` + - `agent: optional object { agent_name }` - - `"gte"` + The agent that produced this item. - - `"lt"` + - `agent_name: string` - - `"lte"` + The canonical name of the agent that produced this item. - - `"in"` + - `created_by: optional string` - - `"nin"` + The identifier of the actor that created the item. - - `value: string or number or boolean or array of unknown` + - `image_generation_call: object { id, result, status, 2 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + An image generation request made by the model. - - `union_member_0: string` + - `id: string` - - `union_member_1: number` + The unique ID of the image generation call. - - `union_member_2: boolean` + - `result: string` - - `union_member_3: array of unknown` + The generated image encoded in base64. - - `Compound Filter: object { filters, type }` + - `status: "in_progress" or "completed" or "generating" or "failed"` - Combine multiple filters using `and` or `or`. + The status of the image generation call. - - `filters: array of object { key, type, value } or unknown` + - `"in_progress"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"completed"` - - `Comparison Filter: object { key, type, value }` + - `"generating"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"failed"` - - `key: string` + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` - The key to compare against the value. + The unique ID of the code interpreter tool call. - - `type: "eq" or "ne" or "gt" or 5 more` + - `code: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The code to run, or null if not available. - - `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 + - `container_id: string` - - `"eq"` + The ID of the container used to run the code. - - `"ne"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"gt"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"gte"` + - `logs: object { logs, type }` - - `"lt"` + The logs output from the code interpreter. - - `"lte"` + - `logs: string` - - `"in"` + The logs output from the code interpreter. - - `"nin"` + - `type: "logs"` - - `value: string or number or boolean or array of unknown` + The type of the output. Always `logs`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `image: object { type, url }` - - `union_member_0: string` + The image output from the code interpreter. - - `union_member_1: number` + - `type: "image"` - - `union_member_2: boolean` + The type of the output. Always `image`. - - `union_member_3: array of unknown` + - `url: string` - - `union_member_1: unknown` + The URL of the image output from the code interpreter. - - `type: "and" or "or"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Type of operation: `and` or `or`. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"and"` + - `"in_progress"` - - `"or"` + - `"completed"` - - `max_num_results: optional number` + - `"incomplete"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"interpreting"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"failed"` - Ranking options for search. + - `type: "code_interpreter_call"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `agent: optional object { agent_name }` - - `embedding_weight: number` + The agent that produced this item. - The weight of the embedding in the reciprocal ranking fusion. + - `agent_name: string` - - `text_weight: number` + The canonical name of the agent that produced this item. - The weight of the text in the reciprocal ranking fusion. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `ranker: optional "auto" or "default-2024-11-15"` + A tool call to run a command on the local shell. - The ranker to use for the file search. + - `id: string` - - `"auto"` + The unique ID of the local shell call. - - `"default-2024-11-15"` + - `action: object { command, env, type, 3 more }` - - `score_threshold: optional number` + Execute a shell command on the server. - 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. + - `command: array of string` - - `beta_computer_tool: object { type }` + The command to run. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `env: map[string]` - - `type: "computer"` + Environment variables to set for the command. - The type of the computer tool. Always `computer`. + - `type: "exec"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The type of the local shell action. Always `exec`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `timeout_ms: optional number` - - `display_height: number` + Optional timeout in milliseconds for the command. - The height of the computer display. + - `user: optional string` - - `display_width: number` + Optional user to run the command as. - The width of the computer display. + - `working_directory: optional string` - - `environment: "windows" or "mac" or "linux" or 2 more` + Optional working directory to run the command in. - The type of computer environment to control. + - `call_id: string` - - `"windows"` + The unique ID of the local shell tool call generated by the model. - - `"mac"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"linux"` + The status of the local shell call. - - `"ubuntu"` + - `"in_progress"` - - `"browser"` + - `"completed"` - - `type: "computer_use_preview"` + - `"incomplete"` - The type of the computer use tool. Always `computer_use_preview`. + - `type: "local_shell_call"` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The type of the local shell call. Always `local_shell_call`. - 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). + - `agent: optional object { agent_name }` - - `type: "web_search" or "web_search_2025_08_26"` + The agent that produced this item. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `agent_name: string` - - `"web_search"` + The canonical name of the agent that produced this item. - - `"web_search_2025_08_26"` + - `local_shell_call_output: object { id, output, type, 2 more }` - - `filters: optional object { allowed_domains }` + The output of a local shell tool call. - Filters for the search. + - `id: string` - - `allowed_domains: optional array of string` + The unique ID of the local shell tool call generated by the model. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `output: string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + A JSON string of the output of the local shell tool call. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "local_shell_call_output"` - 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. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"low"` + - `agent: optional object { agent_name }` - - `"medium"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `user_location: optional object { city, country, region, 2 more }` + The canonical name of the agent that produced this item. - The approximate location of the user. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `city: optional string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"in_progress"` - - `country: optional string` + - `"completed"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"incomplete"` - - `region: optional string` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - Free text input for the region of the user, e.g. `California`. + A tool call that executes one or more shell commands in a managed environment. - - `timezone: optional string` + - `id: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: optional "approximate"` + - `action: object { commands, max_output_length, timeout_ms }` - The type of location approximation. Always `approximate`. + The shell commands and limits that describe how to run the tool call. - - `"approximate"` + - `commands: array of string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `max_output_length: number` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Optional maximum number of characters to return from each command. - - `server_label: string` + - `timeout_ms: number` - A label for this MCP server, used to identify it in tool calls. + Optional timeout in milliseconds for the commands. - - `type: "mcp"` + - `call_id: string` - The type of the MCP tool. Always `mcp`. + The unique ID of the shell tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The tool invocation context(s). + Represents the use of a local environment to perform shell actions. - - `"direct"` + - `beta_response_local_environment: object { type }` - - `"programmatic"` + Represents the use of a local environment to perform shell actions. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `type: "local"` - List of allowed tool names or a filter object. + The environment type. Always `local`. - - `MCP allowed tools: array of string` + - `beta_response_container_reference: object { container_id, type }` - A string array of allowed tool names + Represents a container created with /v1/containers. - - `MCP tool filter: object { read_only, tool_names }` + - `container_id: string` - A filter object to specify which tools are allowed. + - `type: "container_reference"` - - `read_only: optional boolean` + The environment type. Always `container_reference`. - 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. + - `status: "in_progress" or "completed" or "incomplete"` - - `tool_names: optional array of string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - List of allowed tool names. + - `"in_progress"` - - `authorization: optional string` + - `"completed"` - 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. + - `"incomplete"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `type: "shell_call"` - 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). + The type of the item. Always `shell_call`. - Currently supported `connector_id` values are: + - `agent: optional object { agent_name }` - - 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` + The agent that produced this item. - - `"connector_dropbox"` + - `agent_name: string` - - `"connector_gmail"` + The canonical name of the agent that produced this item. - - `"connector_googlecalendar"` + - `caller: optional object { type } or object { caller_id, type }` - - `"connector_googledrive"` + The execution context that produced this tool call. - - `"connector_microsoftteams"` + - `direct: object { type }` - - `"connector_outlookcalendar"` + - `program: object { caller_id, type }` - - `"connector_outlookemail"` + - `caller_id: string` - - `"connector_sharepoint"` + The call ID of the program item that produced this tool call. - - `defer_loading: optional boolean` + - `type: "program"` - Whether this MCP tool is deferred and discovered via tool search. + - `created_by: optional string` - - `headers: optional map[string]` + The ID of the entity that created this tool call. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `require_approval: optional object { always, never } or "always" or "never"` + The output of a shell tool call that was emitted. - Specify which of the MCP server's tools require approval. + - `id: string` - - `MCP tool approval filter: object { always, never }` + The unique ID of the shell call output. Populated when this item is returned via API. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `call_id: string` - - `always: optional object { read_only, tool_names }` + The unique ID of the shell tool call generated by the model. - A filter object to specify which tools are allowed. + - `max_output_length: number` - - `read_only: optional boolean` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - 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. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `tool_names: optional array of string` + An array of shell call output contents - List of allowed tool names. + - `outcome: object { type } or object { exit_code, type }` - - `never: optional object { read_only, tool_names }` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - A filter object to specify which tools are allowed. + - `timeout: object { type }` - - `read_only: optional boolean` + Indicates that the shell call exceeded its configured time limit. - 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. + - `exit: object { exit_code, type }` - - `tool_names: optional array of string` + Indicates that the shell commands finished and returned an exit code. - List of allowed tool names. + - `exit_code: number` - - `MCP tool approval setting: "always" or "never"` + Exit code from the shell process. - 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. + - `type: "exit"` - - `"always"` + The outcome type. Always `exit`. - - `"never"` + - `stderr: string` - - `server_description: optional string` + The standard error output that was captured. - Optional description of the MCP server, used to provide more context. + - `stdout: string` - - `server_url: optional string` + The standard output that was captured. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `created_by: optional string` - - `tunnel_id: optional string` + The identifier of the actor that created the item. - 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. + - `status: "in_progress" or "completed" or "incomplete"` - - `code_interpreter: object { container, type, allowed_callers }` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - A tool that runs Python code to help generate a response to a prompt. + - `"in_progress"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"completed"` - 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. + - `"incomplete"` - - `union_member_0: string` + - `type: "shell_call_output"` - The container ID. + The type of the shell call output. Always `shell_call_output`. - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + - `agent: optional object { agent_name }` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The agent that produced this item. - - `type: "auto"` + - `agent_name: string` - Always `auto`. + The canonical name of the agent that produced this item. - - `file_ids: optional array of string` + - `caller: optional object { type } or object { caller_id, type }` - An optional list of uploaded files to make available to your code. + The execution context that produced this tool call. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `direct: object { type }` - The memory limit for the code interpreter container. + - `program: object { caller_id, type }` - - `"1g"` + - `caller_id: string` - - `"4g"` + The call ID of the program item that produced this tool call. - - `"16g"` + - `type: "program"` - - `"64g"` + - `created_by: optional string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The identifier of the actor that created the item. - Network access policy for the container. + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `beta_container_network_policy_disabled: object { type }` + A tool call that applies file diffs by creating, deleting, or updating files. - - `type: "disabled"` + - `id: string` - Disable outbound network access. Always `disabled`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `call_id: string` - - `allowed_domains: array of string` + The unique ID of the apply patch tool call generated by the model. - A list of allowed domains when type is `allowlist`. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `type: "allowlist"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - Allow outbound network access only to specified domains. Always `allowlist`. + - `create_file: object { diff, path, type }` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + Instruction describing how to create a file via the apply_patch tool. - Optional domain-scoped secrets for allowlisted domains. + - `diff: string` - - `domain: string` + Diff to apply. - The domain associated with the secret. + - `path: string` - - `name: string` + Path of the file to create. - The name of the secret to inject for the domain. + - `type: "create_file"` - - `value: string` + Create a new file with the provided diff. - The secret value to inject for the domain. + - `delete_file: object { path, type }` - - `type: "code_interpreter"` + Instruction describing how to delete a file via the apply_patch tool. - The type of the code interpreter tool. Always `code_interpreter`. + - `path: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Path of the file to delete. - The tool invocation context(s). + - `type: "delete_file"` - - `"direct"` + Delete the specified file. - - `"programmatic"` + - `update_file: object { diff, path, type }` - - `programmatic_tool_calling: object { type }` + Instruction describing how to update a file via the apply_patch tool. - - `image_generation: object { type, action, background, 9 more }` + - `diff: string` - A tool that generates images using the GPT image models. + Diff to apply. - - `type: "image_generation"` + - `path: string` - The type of the image generation tool. Always `image_generation`. + Path of the file to update. - - `action: optional "generate" or "edit" or "auto"` + - `type: "update_file"` - Whether to generate a new image or edit an existing image. Default: `auto`. + Update an existing file with the provided diff. - - `"generate"` + - `status: "in_progress" or "completed"` - - `"edit"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"auto"` + - `"in_progress"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"completed"` - 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. + - `type: "apply_patch_call"` - `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. + The type of the item. Always `apply_patch_call`. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `agent: optional object { agent_name }` - - `"transparent"` + The agent that produced this item. - - `"opaque"` + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `input_fidelity: optional "high" or "low"` + - `caller: optional object { type } or object { caller_id, type }` - 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`. + The execution context that produced this tool call. - - `"high"` + - `direct: object { type }` - - `"low"` + - `program: object { caller_id, type }` - - `input_image_mask: optional object { file_id, image_url }` + - `caller_id: string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The call ID of the program item that produced this tool call. - - `file_id: optional string` + - `type: "program"` - File ID for the mask image. + - `created_by: optional string` - - `image_url: optional string` + The ID of the entity that created this tool call. - Base64-encoded mask image. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The output emitted by an apply patch tool call. - The image generation model to use. Default: `gpt-image-1`. + - `id: string` - - `"gpt-image-1"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"gpt-image-1-mini"` + - `call_id: string` - - `"gpt-image-2"` + The unique ID of the apply patch tool call generated by the model. - - `"gpt-image-2-2026-04-21"` + - `status: "completed" or "failed"` - - `"gpt-image-1.5"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"chatgpt-image-latest"` + - `"completed"` - - `moderation: optional "auto" or "low"` + - `"failed"` - Moderation level for the generated image. Default: `auto`. + - `type: "apply_patch_call_output"` - - `"auto"` + The type of the item. Always `apply_patch_call_output`. - - `"low"` + - `agent: optional object { agent_name }` - - `output_compression: optional number` + The agent that produced this item. - Compression level for the output image. Default: 100. + - `agent_name: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The canonical name of the agent that produced this item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `caller: optional object { type } or object { caller_id, type }` - - `"png"` + The execution context that produced this tool call. - - `"webp"` + - `direct: object { type }` - - `"jpeg"` + - `program: object { caller_id, type }` - - `partial_images: optional number` + - `caller_id: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The call ID of the program item that produced this tool call. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `type: "program"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `created_by: optional string` - - `"low"` + The ID of the entity that created this tool call output. - - `"medium"` + - `output: optional string` - - `"high"` + Optional textual output returned by the apply patch tool. - - `"auto"` + - `mcp_call: object { id, arguments, name, 7 more }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + An invocation of a tool on an MCP server. - 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`. + - `id: string` - - `"1024x1024"` + The unique ID of the tool call. - - `"1024x1536"` + - `arguments: string` - - `"1536x1024"` + A JSON string of the arguments passed to the tool. - - `"auto"` + - `name: string` - - `local_shell: object { type }` + The name of the tool that was run. - A tool that allows the model to execute shell commands in a local environment. + - `server_label: string` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The label of the MCP server running the tool. - A tool that allows the model to execute shell commands. + - `type: "mcp_call"` - - `type: "shell"` + The type of the item. Always `mcp_call`. - The type of the shell tool. Always `shell`. + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `approval_request_id: optional string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + 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. - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `error: optional string` - - `type: "container_auto"` + The error from the tool call, if any. - Automatically creates a container for this request + - `output: optional string` - - `file_ids: optional array of string` + The output from the tool call. - An optional list of uploaded files to make available to your code. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The memory limit for the container. + - `"in_progress"` - - `"1g"` + - `"completed"` - - `"4g"` + - `"incomplete"` - - `"16g"` + - `"calling"` - - `"64g"` + - `"failed"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - Network access policy for the container. + A list of tools available on an MCP server. - - `beta_container_network_policy_disabled: object { type }` + - `id: string` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The unique ID of the list. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `server_label: string` - An optional list of skills referenced by id or inline data. + The label of the MCP server. - - `beta_skill_reference: object { skill_id, type, version }` + - `tools: array of object { input_schema, name, annotations, description }` - - `skill_id: string` + The tools available on the server. - The ID of the referenced skill. + - `input_schema: unknown` - - `type: "skill_reference"` + The JSON schema describing the tool's input. - References a skill created with the /v1/skills endpoint. + - `name: string` - - `version: optional string` + The name of the tool. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `annotations: optional unknown` - - `beta_inline_skill: object { description, name, source, type }` + Additional annotations about the tool. - - `description: string` + - `description: optional string` - The description of the skill. + The description of the tool. - - `name: string` + - `type: "mcp_list_tools"` - The name of the skill. + The type of the item. Always `mcp_list_tools`. - - `source: object { data, media_type, type }` + - `agent: optional object { agent_name }` - Inline skill payload + The agent that produced this item. - - `data: string` + - `agent_name: string` - Base64-encoded skill zip bundle. + The canonical name of the agent that produced this item. - - `media_type: "application/zip"` + - `error: optional string` - The media type of the inline skill payload. Must be `application/zip`. + Error message if the server could not list tools. - - `type: "base64"` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - The type of the inline skill source. Must be `base64`. + A request for human approval of a tool invocation. - - `type: "inline"` + - `id: string` - Defines an inline skill for this request. + The unique ID of the approval request. - - `beta_local_environment: object { type, skills }` + - `arguments: string` - - `type: "local"` + A JSON string of arguments for the tool. - Use a local computer environment. + - `name: string` - - `skills: optional array of BetaLocalSkill` + The name of the tool to run. - An optional list of skills. + - `server_label: string` - - `description: string` + The label of the MCP server making the request. - The description of the skill. + - `type: "mcp_approval_request"` - - `name: string` + The type of the item. Always `mcp_approval_request`. - The name of the skill. + - `agent: optional object { agent_name }` - - `path: string` + The agent that produced this item. - The path to the directory containing the skill. + - `agent_name: string` - - `beta_container_reference: object { container_id, type }` + The canonical name of the agent that produced this item. - - `container_id: string` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - The ID of the referenced container. + A response to an MCP approval request. - - `type: "container_reference"` + - `id: string` - References a container created with the /v1/containers endpoint + The unique ID of the approval response - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `approval_request_id: string` - 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) + The ID of the approval request being answered. - - `name: string` + - `approve: boolean` - The name of the custom tool, used to identify it in tool calls. + Whether the request was approved. - - `type: "custom"` + - `type: "mcp_approval_response"` - The type of the custom tool. Always `custom`. + The type of the item. Always `mcp_approval_response`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that produced this item. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `defer_loading: optional boolean` + - `reason: optional string` - Whether this tool should be deferred and discovered via tool search. + Optional reason for the decision. - - `description: optional string` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - Optional description of the custom tool, used to provide more context. + A call to a custom tool created by the model. - - `format: optional object { type } or object { definition, syntax, type }` + - `call_id: string` - The input format for the custom tool. Default is unconstrained text. + An identifier used to map this custom tool call to a tool call output. - - `text: object { type }` + - `input: string` - Unconstrained free-form text. + The input for the custom tool call generated by the model. - - `grammar: object { definition, syntax, type }` + - `name: string` - A grammar defined by the user. + The name of the custom tool being called. - - `definition: string` + - `type: "custom_tool_call"` - The grammar definition. + The type of the custom tool call. Always `custom_tool_call`. - - `syntax: "lark" or "regex"` + - `id: optional string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the custom tool call in the OpenAI platform. - - `"lark"` + - `agent: optional object { agent_name }` - - `"regex"` + The agent that produced this item. - - `type: "grammar"` + - `agent_name: string` - Grammar format. Always `grammar`. + The canonical name of the agent that produced this item. - - `beta_namespace_tool: object { description, name, tools, type }` + - `caller: optional object { type } or object { caller_id, type }` - Groups function/custom tools under a shared namespace. + The execution context that produced this tool call. - - `description: string` + - `direct: object { type }` - A description of the namespace shown to the model. + - `program: object { caller_id, type }` - - `name: string` + - `caller_id: string` - The namespace name used in tool calls (for example, `crm`). + The call ID of the program item that produced this tool call. - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `type: "program"` - The function/custom tools available inside this namespace. + - `namespace: optional string` - - `function: object { name, type, allowed_callers, 5 more }` + The namespace of the custom tool being called. - - `name: string` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `type: "function"` + The output of a custom tool call from your code, being sent back to the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the custom tool call output item. - - `"direct"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"programmatic"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `defer_loading: optional boolean` + - `"in_progress"` - Whether this function should be deferred and discovered via tool search. + - `"completed"` - - `description: optional string` + - `"incomplete"` - - `output_schema: optional map[unknown]` + - `created_by: optional string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The identifier of the actor that created the item. - - `parameters: optional unknown` +### Beta Response Output Item Added Event - - `strict: optional boolean` +- `beta_response_output_item_added_event: object { item, output_index, sequence_number, 2 more }` - 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. + Emitted when a new output item is added. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` - 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) + The output item that was added. - - `name: string` + - `beta_response_output_message: object { id, content, role, 4 more }` - The name of the custom tool, used to identify it in tool calls. + An output message from the model. - - `type: "custom"` + - `id: string` - The type of the custom tool. Always `custom`. + The unique ID of the output message. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The tool invocation context(s). + The content of the output message. - - `defer_loading: optional boolean` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - Whether this tool should be deferred and discovered via tool search. + A text output from the model. - - `description: optional string` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - Optional description of the custom tool, used to provide more context. + The annotations of the text output. - - `format: optional object { type } or object { definition, syntax, type }` + - `file_citation: object { file_id, filename, index, type }` - The input format for the custom tool. Default is unconstrained text. + A citation to a file. - - `type: "namespace"` + - `file_id: string` - The type of the tool. Always `namespace`. + The ID of the file. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `filename: string` - Hosted or BYOT tool search configuration for deferred tools. + The filename of the file cited. - - `type: "tool_search"` + - `index: number` - The type of the tool. Always `tool_search`. + The index of the file in the list of files. - - `description: optional string` + - `type: "file_citation"` - Description shown to the model for a client-executed tool search tool. + The type of the file citation. Always `file_citation`. - - `execution: optional "server" or "client"` + - `url_citation: object { end_index, start_index, title, 2 more }` - Whether tool search is executed by the server or by the client. + A citation for a web resource used to generate a model response. - - `"server"` + - `end_index: number` - - `"client"` + The index of the last character of the URL citation in the message. - - `parameters: optional unknown` + - `start_index: number` - Parameter schema for a client-executed tool search tool. + The index of the first character of the URL citation in the message. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `title: string` - 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). + The title of the web resource. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `type: "url_citation"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The type of the URL citation. Always `url_citation`. - - `"web_search_preview"` + - `url: string` - - `"web_search_preview_2025_03_11"` + The URL of the web resource. - - `search_content_types: optional array of "text" or "image"` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `"text"` + A citation for a container file used to generate a model response. - - `"image"` + - `container_id: string` - - `search_context_size: optional "low" or "medium" or "high"` + The ID of the container file. - 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. + - `end_index: number` - - `"low"` + The index of the last character of the container file citation in the message. - - `"medium"` + - `file_id: string` - - `"high"` + The ID of the file. - - `user_location: optional object { type, city, country, 2 more }` + - `filename: string` - The user's location. + The filename of the container file cited. - - `type: "approximate"` + - `start_index: number` - The type of location approximation. Always `approximate`. + The index of the first character of the container file citation in the message. - - `city: optional string` + - `type: "container_file_citation"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the container file citation. Always `container_file_citation`. - - `country: optional string` + - `file_path: object { file_id, index, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A path to a file. - - `region: optional string` + - `file_id: string` - Free text input for the region of the user, e.g. `California`. + The ID of the file. - - `timezone: optional string` + - `index: number` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The index of the file in the list of files. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `type: "file_path"` - Allows the assistant to create, delete, or update files using unified diffs. + The type of the file path. Always `file_path`. - - `type: "apply_patch"` + - `text: string` - The type of the tool. Always `apply_patch`. + The text output from the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "output_text"` - The tool invocation context(s). + The type of the output text. Always `output_text`. - - `"direct"` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `"programmatic"` + - `token: string` - - `type: "tool_search_output"` + - `bytes: array of number` - The item type. Always `tool_search_output`. + - `logprob: number` - - `id: optional string` + - `top_logprobs: array of object { token, bytes, logprob }` - The unique ID of this tool search output. + - `token: string` - - `agent: optional object { agent_name }` + - `bytes: array of number` - The agent that produced this item. + - `logprob: number` - - `agent_name: string` + - `beta_response_output_refusal: object { refusal, type }` - The canonical name of the agent that produced this item. + A refusal from the model. - - `call_id: optional string` + - `refusal: string` - The unique ID of the tool search call generated by the model. + The refusal explanation from the model. - - `execution: optional "server" or "client"` + - `type: "refusal"` - Whether tool search was executed by the server or by the client. + The type of the refusal. Always `refusal`. - - `"server"` + - `role: "assistant"` - - `"client"` + The role of the output message. Always `assistant`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -80052,122 +91762,126 @@ openai beta:responses compact \ - `"incomplete"` - - `additional_tools: object { role, tools, type, 2 more }` + - `type: "message"` - - `role: "developer"` + The type of the output message. Always `message`. - The role that provided the additional tools. Only `developer` is supported. + - `agent: optional object { agent_name }` - - `tools: array of BetaTool` + The agent that produced this item. - A list of additional tools made available at this item. + - `agent_name: string` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The canonical name of the agent that produced this item. - 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). + - `phase: optional "commentary" or "final_answer"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + 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. - 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). + - `"commentary"` - - `beta_computer_tool: object { type }` + - `"final_answer"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + 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. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `id: string` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The unique ID of the file search tool call. - 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). + - `queries: array of string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The queries used to search for files. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `code_interpreter: object { container, type, allowed_callers }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - A tool that runs Python code to help generate a response to a prompt. + - `"in_progress"` - - `programmatic_tool_calling: object { type }` + - `"searching"` - - `image_generation: object { type, action, background, 9 more }` + - `"completed"` - A tool that generates images using the GPT image models. + - `"incomplete"` - - `local_shell: object { type }` + - `"failed"` - A tool that allows the model to execute shell commands in a local environment. + - `type: "file_search_call"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The type of the file search tool call. Always `file_search_call`. - A tool that allows the model to execute shell commands. + - `agent: optional object { agent_name }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The agent that produced this item. - 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) + - `agent_name: string` - - `beta_namespace_tool: object { description, name, tools, type }` + The canonical name of the agent that produced this item. - Groups function/custom tools under a shared namespace. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The results of the file search tool call. - Hosted or BYOT tool search configuration for deferred tools. + - `attributes: optional map[string or number or boolean]` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + 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. - 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). + - `union_member_0: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `union_member_1: number` - Allows the assistant to create, delete, or update files using unified diffs. + - `union_member_2: boolean` - - `type: "additional_tools"` + - `file_id: optional string` - The item type. Always `additional_tools`. + The unique ID of the file. - - `id: optional string` + - `filename: optional string` - The unique ID of this additional tools item. + The name of the file. - - `agent: optional object { agent_name }` + - `score: optional number` - The agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `agent_name: string` + - `text: optional string` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique identifier of the reasoning content. + A JSON string of the arguments to pass to the function. - - `summary: array of object { text, type }` + - `call_id: string` - Reasoning summary content. + The unique ID of the function tool call generated by the model. - - `text: string` + - `name: string` - A summary of the reasoning output from the model so far. + The name of the function to run. - - `type: "summary_text"` + - `type: "function_call"` - The type of the object. Always `summary_text`. + The type of the function tool call. Always `function_call`. - - `type: "reasoning"` + - `id: optional string` - The type of the object. Always `reasoning`. + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -80177,22 +91891,23 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` + - `caller: optional object { type } or object { caller_id, type }` - Reasoning text content. + The execution context that produced this tool call. - - `text: string` + - `direct: object { type }` - The reasoning text from the model. + - `program: object { caller_id, type }` - - `type: "reasoning_text"` + - `caller_id: string` - The type of the reasoning text. Always `reasoning_text`. + The call ID of the program item that produced this tool call. - - `encrypted_content: optional string` + - `type: "program"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `namespace: optional string` + + The namespace of the function to run. - `status: optional "in_progress" or "completed" or "incomplete"` @@ -80205,114 +91920,131 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `id: string` - - `encrypted_content: string` + The unique ID of the function call tool output. - The encrypted content of the compaction summary. + - `call_id: string` - - `type: "compaction"` + The unique ID of the function tool call generated by the model. - The type of the item. Always `compaction`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `id: optional string` + The output from the function call generated by your code. + Can be a string or an list of output content. - The ID of the compaction item. + - `string output: string` - - `agent: optional object { agent_name }` + A string of the output of the function call. - The agent that produced this item. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `agent_name: string` + Text, image, or file output of the function call. - The canonical name of the agent that produced this item. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `image_generation_call: object { id, result, status, 2 more }` + A text input to the model. - An image generation request made by the model. + - `text: string` - - `id: string` + The text input to the model. - The unique ID of the image generation call. + - `type: "input_text"` - - `result: string` + The type of the input item. Always `input_text`. - The generated image encoded in base64. + - `prompt_cache_breakpoint: optional object { mode }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + 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. - The status of the image generation call. + - `mode: "explicit"` - - `"in_progress"` + The breakpoint mode. Always `explicit`. - - `"completed"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"generating"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"failed"` + - `detail: "low" or "high" or "auto" or "original"` - - `type: "image_generation_call"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of the image generation call. Always `image_generation_call`. + - `"low"` - - `agent: optional object { agent_name }` + - `"high"` - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"original"` - The canonical name of the agent that produced this item. + - `type: "input_image"` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + The type of the input item. Always `input_image`. - A tool call to run code. + - `file_id: optional string` - - `id: string` + The ID of the file to be sent to the model. - The unique ID of the code interpreter tool call. + - `image_url: optional string` - - `code: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The code to run, or null if not available. + - `prompt_cache_breakpoint: optional object { mode }` - - `container_id: string` + 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. - The ID of the container used to run the code. + - `mode: "explicit"` - - `outputs: array of object { logs, type } or object { type, url }` + The breakpoint mode. Always `explicit`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `logs: object { logs, type }` + A file input to the model. - The logs output from the code interpreter. + - `type: "input_file"` - - `logs: string` + The type of the input item. Always `input_file`. - The logs output from the code interpreter. + - `detail: optional "auto" or "low" or "high"` - - `type: "logs"` + 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`. - The type of the output. Always `logs`. + - `"auto"` - - `image: object { type, url }` + - `"low"` - The image output from the code interpreter. + - `"high"` - - `type: "image"` + - `file_data: optional string` - The type of the output. Always `image`. + The content of the file to be sent to the model. - - `url: string` + - `file_id: optional string` - The URL of the image output from the code interpreter. + The ID of the file to be sent to the model. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `file_url: optional string` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -80320,13 +92052,9 @@ openai beta:responses compact \ - `"incomplete"` - - `"interpreting"` - - - `"failed"` - - - `type: "code_interpreter_call"` + - `type: "function_call_output"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` @@ -80336,333 +92064,339 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - A tool call to run a command on the local shell. + The execution context that produced this tool call. - - `id: string` + - `direct: object { type }` - The unique ID of the local shell call. + - `program: object { caller_id, type }` - - `action: object { command, env, type, 3 more }` + - `caller_id: string` - Execute a shell command on the server. + The call ID of the program item that produced this tool call. - - `command: array of string` + - `type: "program"` - The command to run. + The caller type. Always `program`. - - `env: map[string]` + - `created_by: optional string` - Environment variables to set for the command. + The identifier of the actor that created the item. - - `type: "exec"` + - `agent_message: object { id, author, content, 3 more }` - The type of the local shell action. Always `exec`. + - `id: string` - - `timeout_ms: optional number` + The unique ID of the agent message. - Optional timeout in milliseconds for the command. + - `author: string` - - `user: optional string` + The sending agent identity. - Optional user to run the command as. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `working_directory: optional string` + Encrypted content sent between agents. - Optional working directory to run the command in. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `call_id: string` + A text input to the model. - The unique ID of the local shell tool call generated by the model. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `status: "in_progress" or "completed" or "incomplete"` + A text output from the model. - The status of the local shell call. + - `text: object { text, type }` - - `"in_progress"` + A text content. - - `"completed"` + - `text: string` - - `"incomplete"` + - `type: "text"` - - `type: "local_shell_call"` + - `summary_text: object { text, type }` - The type of the local shell call. Always `local_shell_call`. + A summary text from the model. - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + A summary of the reasoning output from the model so far. - - `agent_name: string` + - `type: "summary_text"` - The canonical name of the agent that produced this item. + The type of the object. Always `summary_text`. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `reasoning_text: object { text, type }` - The output of a local shell tool call. + Reasoning text from the model. - - `id: string` + - `text: string` - The unique ID of the local shell tool call generated by the model. + The reasoning text from the model. - - `output: string` + - `type: "reasoning_text"` - A JSON string of the output of the local shell tool call. + The type of the reasoning text. Always `reasoning_text`. - - `type: "local_shell_call_output"` + - `beta_response_output_refusal: object { refusal, type }` - The type of the local shell tool call output. Always `local_shell_call_output`. + A refusal from the model. - - `agent: optional object { agent_name }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The agent that produced this item. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `agent_name: string` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - The canonical name of the agent that produced this item. + A screenshot of a computer. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `detail: "low" or "high" or "auto" or "original"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"in_progress"` + - `"low"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `"auto"` - - `shell_call: object { action, call_id, type, 5 more }` + - `"original"` - A tool representing a request to execute one or more shell commands. + - `file_id: string` - - `action: object { commands, max_output_length, timeout_ms }` + The identifier of an uploaded file that contains the screenshot. - The shell commands and limits that describe how to run the tool call. + - `image_url: string` - - `commands: array of string` + The URL of the screenshot image. - Ordered shell commands for the execution environment to run. + - `type: "computer_screenshot"` - - `max_output_length: optional number` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `prompt_cache_breakpoint: optional object { mode }` - - `timeout_ms: optional number` + 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. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `mode: "explicit"` - - `call_id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the shell tool call generated by the model. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `type: "shell_call"` + A file input to the model. - The type of the item. Always `shell_call`. + - `encrypted_content: object { encrypted_content, type }` - - `id: optional string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `encrypted_content: string` - - `agent: optional object { agent_name }` + Opaque encrypted content. - The agent that produced this item. + - `type: "encrypted_content"` - - `agent_name: string` + The type of the input item. Always `encrypted_content`. - The canonical name of the agent that produced this item. + - `recipient: string` - - `caller: optional object { type } or object { caller_id, type }` + The destination agent identity. - The execution context that produced this tool call. + - `type: "agent_message"` - - `direct: object { type }` + The type of the item. Always `agent_message`. - - `program: object { caller_id, type }` + - `agent: optional object { agent_name }` - - `caller_id: string` + The agent that produced this item. - The call ID of the program item that produced this tool call. + - `agent_name: string` - - `type: "program"` + The canonical name of the agent that produced this item. - The caller type. Always `program`. + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `id: string` - The environment to execute the shell commands in. + The unique ID of the multi-agent call item. - - `beta_local_environment: object { type, skills }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `beta_container_reference: object { container_id, type }` + The multi-agent action to execute. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"spawn_agent"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"interrupt_agent"` - - `"in_progress"` + - `"list_agents"` - - `"completed"` + - `"send_message"` - - `"incomplete"` + - `"followup_task"` - - `shell_call_output: object { call_id, output, type, 5 more }` + - `"wait_agent"` - The streamed output items emitted by a shell tool call. + - `arguments: string` + + The JSON string of arguments generated for the action. - `call_id: string` - The unique ID of the shell tool call generated by the model. + The unique ID linking this call to its output. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `type: "multi_agent_call"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The type of the multi-agent call. Always `multi_agent_call`. - - `outcome: object { type } or object { exit_code, type }` + - `agent: optional object { agent_name }` - The exit or timeout outcome associated with this shell call. + The agent that produced this item. - - `timeout: object { type }` + - `agent_name: string` - Indicates that the shell call exceeded its configured time limit. + The canonical name of the agent that produced this item. - - `exit: object { exit_code, type }` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - Indicates that the shell commands finished and returned an exit code. + - `id: string` - - `exit_code: number` + The unique ID of the multi-agent call output item. - The exit code returned by the shell process. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "exit"` + The multi-agent action that produced this result. - The outcome type. Always `exit`. + - `"spawn_agent"` - - `stderr: string` + - `"interrupt_agent"` - Captured stderr output for the shell call. + - `"list_agents"` - - `stdout: string` + - `"send_message"` - Captured stdout output for the shell call. + - `"followup_task"` - - `type: "shell_call_output"` + - `"wait_agent"` - The type of the item. Always `shell_call_output`. + - `call_id: string` - - `id: optional string` + The unique ID of the multi-agent call. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `output: array of BetaResponseOutputText` - - `agent: optional object { agent_name }` + Text output returned by the multi-agent action. - The agent that produced this item. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `agent_name: string` + The annotations of the text output. - The canonical name of the agent that produced this item. + - `text: string` - - `caller: optional object { type } or object { caller_id, type }` + The text output from the model. - The execution context that produced this tool call. + - `type: "output_text"` - - `direct: object { type }` + The type of the output text. Always `output_text`. - - `program: object { caller_id, type }` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `caller_id: string` + - `type: "multi_agent_call_output"` - The call ID of the program item that produced this tool call. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `type: "program"` + - `agent: optional object { agent_name }` - The caller type. Always `program`. + The agent that produced this item. - - `max_output_length: optional number` + - `agent_name: string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - The status of the shell call output. + 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. - - `"in_progress"` + - `id: string` - - `"completed"` + The unique ID of the web search tool call. - - `"incomplete"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `apply_patch_call: object { call_id, operation, status, 4 more }` + 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). - A tool call representing a request to create, delete, or update files using diff patches. + - `search: object { type, queries, query, sources }` - - `call_id: string` + Action type "search" - Performs a web search query. - The unique ID of the apply patch tool call generated by the model. + - `type: "search"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The action type. - The specific create, delete, or update instruction for the apply_patch tool call. + - `queries: optional array of string` - - `create_file: object { diff, path, type }` + The search queries. - Instruction for creating a new file via the apply_patch tool. + - `query: optional string` - - `diff: string` + The search query. - Unified diff content to apply when creating the file. + - `sources: optional array of object { type, url }` - - `path: string` + The sources used in the search. - Path of the file to create relative to the workspace root. + - `type: "url"` - - `type: "create_file"` + The type of source. Always `url`. - The operation type. Always `create_file`. + - `url: string` - - `delete_file: object { path, type }` + The URL of the source. - Instruction for deleting an existing file via the apply_patch tool. + - `open_page: object { type, url }` - - `path: string` + Action type "open_page" - Opens a specific URL from search results. - Path of the file to delete relative to the workspace root. + - `type: "open_page"` - - `type: "delete_file"` + The action type. - The operation type. Always `delete_file`. + - `url: optional string` - - `update_file: object { diff, path, type }` + The URL opened by the model. - Instruction for updating an existing file via the apply_patch tool. + - `find_in_page: object { pattern, type, url }` - - `diff: string` + Action type "find_in_page": Searches for a pattern within a loaded page. - Unified diff content to apply to the existing file. + - `pattern: string` - - `path: string` + The pattern or text to search for within the page. - Path of the file to update relative to the workspace root. + - `type: "find_in_page"` - - `type: "update_file"` + The action type. - The operation type. Always `update_file`. + - `url: string` - - `status: "in_progress" or "completed"` + The URL of the page searched for the pattern. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. - `"in_progress"` - - `"completed"` + - `"searching"` - - `type: "apply_patch_call"` + - `"completed"` - The type of the item. Always `apply_patch_call`. + - `"failed"` - - `id: optional string` + - `type: "web_search_call"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of the web search tool call. Always `web_search_call`. - `agent: optional object { agent_name }` @@ -80672,345 +92406,369 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - The execution context that produced this tool call. + 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. - - `direct: object { type }` + - `id: string` - - `program: object { caller_id, type }` + The unique ID of the computer call. - - `caller_id: string` + - `call_id: string` - The call ID of the program item that produced this tool call. + An identifier used when responding to the tool call with output. - - `type: "program"` + - `pending_safety_checks: array of object { id, code, message }` - The caller type. Always `program`. + The pending safety checks for the computer call. - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `id: string` - The streamed output emitted by an apply patch tool call. + The ID of the pending safety check. - - `call_id: string` + - `code: optional string` - The unique ID of the apply patch tool call generated by the model. + The type of the pending safety check. - - `status: "completed" or "failed"` + - `message: optional string` - The status of the apply patch tool call output. One of `completed` or `failed`. + Details about the pending safety check. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: "apply_patch_call_output"` + - `type: "computer_call"` - The type of the item. Always `apply_patch_call_output`. + The type of the computer call. Always `computer_call`. - - `id: optional string` + - `"computer_call"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `agent: optional object { agent_name }` + A click action. - The agent that produced this item. + - `click: object { button, type, x, 2 more }` - - `agent_name: string` + A click action. - The canonical name of the agent that produced this item. + - `button: "left" or "right" or "wheel" or 2 more` - - `caller: optional object { type } or object { caller_id, type }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The execution context that produced this tool call. + - `"left"` - - `direct: object { type }` + - `"right"` - - `program: object { caller_id, type }` + - `"wheel"` - - `caller_id: string` + - `"back"` - The call ID of the program item that produced this tool call. + - `"forward"` - - `type: "program"` + - `type: "click"` - The caller type. Always `program`. + Specifies the event type. For a click action, this property is always `click`. - - `output: optional string` + - `x: number` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The x-coordinate where the click occurred. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `y: number` - A list of tools available on an MCP server. + The y-coordinate where the click occurred. - - `id: string` + - `keys: optional array of string` - The unique ID of the list. + The keys being held while clicking. - - `server_label: string` + - `double_click: object { keys, type, x, y }` - The label of the MCP server. + A double click action. - - `tools: array of object { input_schema, name, annotations, description }` + - `keys: array of string` - The tools available on the server. + The keys being held while double-clicking. - - `input_schema: unknown` + - `type: "double_click"` - The JSON schema describing the tool's input. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `name: string` + - `x: number` - The name of the tool. + The x-coordinate where the double click occurred. - - `annotations: optional unknown` + - `y: number` - Additional annotations about the tool. + The y-coordinate where the double click occurred. - - `description: optional string` + - `drag: object { path, type, keys }` - The description of the tool. + A drag action. - - `type: "mcp_list_tools"` + - `path: array of object { x, y }` - The type of the item. Always `mcp_list_tools`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `agent: optional object { agent_name }` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The agent that produced this item. + - `x: number` - - `agent_name: string` + The x-coordinate. - The canonical name of the agent that produced this item. + - `y: number` - - `error: optional string` + The y-coordinate. - Error message if the server could not list tools. + - `type: "drag"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + Specifies the event type. For a drag action, this property is always set to `drag`. - A request for human approval of a tool invocation. + - `keys: optional array of string` - - `id: string` + The keys being held while dragging the mouse. - The unique ID of the approval request. + - `keypress: object { keys, type }` - - `arguments: string` + A collection of keypresses the model would like to perform. - A JSON string of arguments for the tool. + - `keys: array of string` - - `name: string` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The name of the tool to run. + - `type: "keypress"` - - `server_label: string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The label of the MCP server making the request. + - `move: object { type, x, y, keys }` - - `type: "mcp_approval_request"` + A mouse move action. - The type of the item. Always `mcp_approval_request`. + - `type: "move"` - - `agent: optional object { agent_name }` + Specifies the event type. For a move action, this property is always set to `move`. - The agent that produced this item. + - `x: number` - - `agent_name: string` + The x-coordinate to move to. - The canonical name of the agent that produced this item. + - `y: number` - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + The y-coordinate to move to. - A response to an MCP approval request. + - `keys: optional array of string` - - `approval_request_id: string` + The keys being held while moving the mouse. - The ID of the approval request being answered. + - `screenshot: object { type }` - - `approve: boolean` + A screenshot action. - Whether the request was approved. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `type: "mcp_approval_response"` + A scroll action. - The type of the item. Always `mcp_approval_response`. + - `scroll_x: number` - - `id: optional string` + The horizontal scroll distance. - The unique ID of the approval response + - `scroll_y: number` - - `agent: optional object { agent_name }` + The vertical scroll distance. - The agent that produced this item. + - `type: "scroll"` - - `agent_name: string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The canonical name of the agent that produced this item. + - `x: number` - - `reason: optional string` + The x-coordinate where the scroll occurred. - Optional reason for the decision. + - `y: number` - - `mcp_call: object { id, arguments, name, 7 more }` + The y-coordinate where the scroll occurred. - An invocation of a tool on an MCP server. + - `keys: optional array of string` - - `id: string` + The keys being held while scrolling. - The unique ID of the tool call. + - `type: object { text, type }` - - `arguments: string` + An action to type in text. - A JSON string of the arguments passed to the tool. + - `text: string` - - `name: string` + The text to type. - The name of the tool that was run. + - `type: "type"` - - `server_label: string` + Specifies the event type. For a type action, this property is always set to `type`. - The label of the MCP server running the tool. + - `wait: object { type }` - - `type: "mcp_call"` + A wait action. - The type of the item. Always `mcp_call`. + - `actions: optional array of BetaComputerAction` - - `agent: optional object { agent_name }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The agent that produced this item. + - `click: object { button, type, x, 2 more }` - - `agent_name: string` + A click action. - The canonical name of the agent that produced this item. + - `double_click: object { keys, type, x, y }` - - `approval_request_id: optional string` + A double click action. - 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. + - `drag: object { path, type, keys }` - - `error: optional string` + A drag action. - The error from the tool call, if any. + - `keypress: object { keys, type }` - - `output: optional string` + A collection of keypresses the model would like to perform. - The output from the tool call. + - `move: object { type, x, y, keys }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + A mouse move action. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `screenshot: object { type }` - - `"in_progress"` + A screenshot action. - - `"completed"` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `"incomplete"` + A scroll action. - - `"calling"` + - `type: object { text, type }` - - `"failed"` + An action to type in text. - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `wait: object { type }` - The output of a custom tool call from your code, being sent back to the model. + A wait action. - - `call_id: string` + - `agent: optional object { agent_name }` - The call ID, used to map this custom tool call output to a custom tool call. + The agent that produced this item. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `agent_name: string` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The canonical name of the agent that produced this item. - - `string output: string` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - A string of the output of the custom tool call. + - `id: string` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The unique ID of the computer call tool output. - Text, image, or file output of the custom tool call. + - `call_id: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The ID of the computer tool call that produced the output. - A text input to the model. + - `output: object { type, file_id, image_url }` - - `text: string` + A computer screenshot image used with the computer use tool. - The text input to the model. + - `type: "computer_screenshot"` - - `type: "input_text"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The type of the input item. Always `input_text`. + - `file_id: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The identifier of an uploaded file that contains the screenshot. - 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. + - `image_url: optional string` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The URL of the screenshot image. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `detail: "low" or "high" or "auto" or "original"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"completed"` - - `type: "input_image"` + - `"incomplete"` - The type of the input item. Always `input_image`. + - `"failed"` - - `file_id: optional string` + - `"in_progress"` - The ID of the file to be sent to the model. + - `type: "computer_call_output"` - - `image_url: optional string` + The type of the computer tool call output. Always `computer_call_output`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `prompt_cache_breakpoint: optional object { mode }` + The safety checks reported by the API that have been acknowledged by the + developer. - 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. + - `id: string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The ID of the pending safety check. - A file input to the model. + - `code: optional string` - - `type: "input_file"` + The type of the pending safety check. - The type of the input item. Always `input_file`. + - `message: optional string` - - `detail: optional "auto" or "low" or "high"` + Details about the pending safety check. - 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`. + - `agent: optional object { agent_name }` - - `file_data: optional string` + The agent that produced this item. - The content of the file to be sent to the model. + - `agent_name: string` - - `file_id: optional string` + The canonical name of the agent that produced this item. - The ID of the file to be sent to the model. + - `created_by: optional string` - - `file_url: optional string` + The identifier of the actor that created the item. - The URL of the file to be sent to the model. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `filename: optional string` + 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). - The name of the file to be sent to the model. + - `id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique identifier of the reasoning content. - 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. + - `summary: array of object { text, type }` - - `type: "custom_tool_call_output"` + Reasoning summary content. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `text: string` - - `id: optional string` + A summary of the reasoning output from the model so far. - The unique ID of the custom tool call output in the OpenAI platform. + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. - `agent: optional object { agent_name }` @@ -81020,45 +92778,55 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `content: optional array of object { text, type }` - The execution context that produced this tool call. + Reasoning text content. - - `direct: object { type }` + - `text: string` - - `program: object { caller_id, type }` + The reasoning text from the model. - - `caller_id: string` + - `type: "reasoning_text"` - The call ID of the program item that produced this tool call. + The type of the reasoning text. Always `reasoning_text`. - - `type: "program"` + - `encrypted_content: optional string` - The caller type. Always `program`. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A call to a custom tool created by the model. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `call_id: string` + - `"in_progress"` - An identifier used to map this custom tool call to a tool call output. + - `"completed"` - - `input: string` + - `"incomplete"` - The input for the custom tool call generated by the model. + - `program: object { id, call_id, code, 3 more }` - - `name: string` + - `id: string` - The name of the custom tool being called. + The unique ID of the program item. - - `type: "custom_tool_call"` + - `call_id: string` - The type of the custom tool call. Always `custom_tool_call`. + The stable call ID of the program item. - - `id: optional string` + - `code: string` - The unique ID of the custom tool call in the OpenAI platform. + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. - `agent: optional object { agent_name }` @@ -81068,31 +92836,31 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `program_output: object { id, call_id, result, 3 more }` - The execution context that produced this tool call. + - `id: string` - - `direct: object { type }` + The unique ID of the program output item. - - `program: object { caller_id, type }` + - `call_id: string` - - `caller_id: string` + The call ID of the program item. - The call ID of the program item that produced this tool call. + - `result: string` - - `type: "program"` + The result produced by the program item. - - `namespace: optional string` + - `status: "completed" or "incomplete"` - The namespace of the custom tool being called. + The terminal status of the program output item. - - `compaction_trigger: object { type, agent }` + - `"completed"` - Compacts the current context. Must be the final input item. + - `"incomplete"` - - `type: "compaction_trigger"` + - `type: "program_output"` - The type of the item. Always `compaction_trigger`. + The type of the item. Always `program_output`. - `agent: optional object { agent_name }` @@ -81102,49 +92870,41 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `item_reference: object { id, agent, type }` - - An internal identifier for an item to reference. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - `id: string` - The ID of the item to reference. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` + The unique ID of the tool search call item. - The canonical name of the agent that produced this item. + - `arguments: unknown` - - `type: optional "item_reference"` + Arguments used for the tool search call. - The type of item to reference. Always `item_reference`. + - `call_id: string` - - `"item_reference"` + The unique ID of the tool search call generated by the model. - - `program: object { id, call_id, code, 3 more }` + - `execution: "server" or "client"` - - `id: string` + Whether tool search was executed by the server or by the client. - The unique ID of this program item. + - `"server"` - - `call_id: string` + - `"client"` - The stable call ID of the program item. + - `status: "in_progress" or "completed" or "incomplete"` - - `code: string` + The status of the tool search call item that was recorded. - The JavaScript source executed by programmatic tool calling. + - `"in_progress"` - - `fingerprint: string` + - `"completed"` - Opaque program replay fingerprint that must be round-tripped. + - `"incomplete"` - - `type: "program"` + - `type: "tool_search_call"` - The item type. Always `program`. + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -81154,1056 +92914,1079 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `program_output: object { id, call_id, result, 3 more }` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - `id: string` - The unique ID of this program output item. + The unique ID of the tool search output item. + + - `call_id: string` + + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` - - `call_id: string` + Whether tool search was executed by the server or by the client. - The call ID of the program item. + - `"server"` - - `result: string` + - `"client"` - The result produced by the program item. + - `status: "in_progress" or "completed" or "incomplete"` - - `status: "completed" or "incomplete"` + The status of the tool search output item that was recorded. - The terminal status of the program output. + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` - - The item type. Always `program_output`. + - `tools: array of BetaTool` - - `agent: optional object { agent_name }` + The loaded tool definitions returned by tool search. - The agent that produced this item. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `name: string` - - `metadata: map[string]` + The name of the function to call. - 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. + - `parameters: map[unknown]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A JSON schema object describing the parameters of the function. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `strict: boolean` - Model ID used to generate the response, like `gpt-4o` 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. + Whether strict parameter validation is enforced for this function tool. - - `"gpt-5.6-sol"` + - `type: "function"` - - `"gpt-5.6-terra"` + The type of the function tool. Always `function`. - - `"gpt-5.6-luna"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5.4"` + The tool invocation context(s). - - `"gpt-5.4-mini"` + - `"direct"` - - `"gpt-5.4-nano"` + - `"programmatic"` - - `"gpt-5.4-mini-2026-03-17"` + - `defer_loading: optional boolean` - - `"gpt-5.4-nano-2026-03-17"` + Whether this function is deferred and loaded via tool search. - - `"gpt-5.3-chat-latest"` + - `description: optional string` - - `"gpt-5.2"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"gpt-5.2-2025-12-11"` + - `output_schema: optional map[unknown]` - - `"gpt-5.2-chat-latest"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"gpt-5.2-pro"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `"gpt-5.2-pro-2025-12-11"` + 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). - - `"gpt-5.1"` + - `type: "file_search"` - - `"gpt-5.1-2025-11-13"` + The type of the file search tool. Always `file_search`. - - `"gpt-5.1-codex"` + - `vector_store_ids: array of string` - - `"gpt-5.1-mini"` + The IDs of the vector stores to search. - - `"gpt-5.1-chat-latest"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"gpt-5"` + A filter to apply. - - `"gpt-5-mini"` + - `Comparison Filter: object { key, type, value }` - - `"gpt-5-nano"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-5-2025-08-07"` + - `key: string` - - `"gpt-5-mini-2025-08-07"` + The key to compare against the value. - - `"gpt-5-nano-2025-08-07"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-5-chat-latest"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4.1"` + - `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 - - `"gpt-4.1-mini"` + - `"eq"` - - `"gpt-4.1-nano"` + - `"ne"` - - `"gpt-4.1-2025-04-14"` + - `"gt"` - - `"gpt-4.1-mini-2025-04-14"` + - `"gte"` - - `"gpt-4.1-nano-2025-04-14"` + - `"lt"` - - `"o4-mini"` + - `"lte"` - - `"o4-mini-2025-04-16"` + - `"in"` - - `"o3"` + - `"nin"` - - `"o3-2025-04-16"` + - `value: string or number or boolean or array of string or number` - - `"o3-mini"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"o3-mini-2025-01-31"` + - `union_member_0: string` - - `"o1"` + - `union_member_1: number` - - `"o1-2024-12-17"` + - `union_member_2: boolean` - - `"o1-preview"` + - `union_member_3: array of string or number` - - `"o1-preview-2024-09-12"` + - `union_member_0: string` - - `"o1-mini"` + - `union_member_1: number` - - `"o1-mini-2024-09-12"` + - `Compound Filter: object { filters, type }` - - `"gpt-4o"` + Combine multiple filters using `and` or `or`. - - `"gpt-4o-2024-11-20"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-4o-2024-08-06"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-4o-2024-05-13"` + - `Comparison Filter: object { key, type, value }` - - `"gpt-4o-audio-preview"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4o-audio-preview-2024-10-01"` + - `key: string` - - `"gpt-4o-audio-preview-2024-12-17"` + The key to compare against the value. - - `"gpt-4o-audio-preview-2025-06-03"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4o-mini-audio-preview"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `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 - - `"gpt-4o-search-preview"` + - `"eq"` - - `"gpt-4o-mini-search-preview"` + - `"ne"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"gt"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"gte"` - - `"chatgpt-4o-latest"` + - `"lt"` - - `"codex-mini-latest"` + - `"lte"` - - `"gpt-4o-mini"` + - `"in"` - - `"gpt-4o-mini-2024-07-18"` + - `"nin"` - - `"gpt-4-turbo"` + - `value: string or number or boolean or array of string or number` - - `"gpt-4-turbo-2024-04-09"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-4-0125-preview"` + - `union_member_0: string` - - `"gpt-4-turbo-preview"` + - `union_member_1: number` - - `"gpt-4-1106-preview"` + - `union_member_2: boolean` - - `"gpt-4-vision-preview"` + - `union_member_3: array of string or number` - - `"gpt-4"` + - `union_member_0: string` - - `"gpt-4-0314"` + - `union_member_1: number` - - `"gpt-4-0613"` + - `union_member_1: unknown` - - `"gpt-4-32k"` + - `type: "and" or "or"` - - `"gpt-4-32k-0314"` + Type of operation: `and` or `or`. - - `"gpt-4-32k-0613"` + - `"and"` - - `"gpt-3.5-turbo"` + - `"or"` - - `"gpt-3.5-turbo-16k"` + - `max_num_results: optional number` - - `"gpt-3.5-turbo-0301"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-3.5-turbo-0613"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"gpt-3.5-turbo-1106"` + Ranking options for search. - - `"gpt-3.5-turbo-0125"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"gpt-3.5-turbo-16k-0613"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"o1-pro"` + - `embedding_weight: number` - - `"o1-pro-2025-03-19"` + The weight of the embedding in the reciprocal ranking fusion. - - `"o3-pro"` + - `text_weight: number` - - `"o3-pro-2025-06-10"` + The weight of the text in the reciprocal ranking fusion. - - `"o3-deep-research"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"o3-deep-research-2025-06-26"` + The ranker to use for the file search. - - `"o4-mini-deep-research"` + - `"auto"` - - `"o4-mini-deep-research-2025-06-26"` + - `"default-2024-11-15"` - - `"computer-use-preview"` + - `score_threshold: optional number` - - `"computer-use-preview-2025-03-11"` + 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. - - `"gpt-5-codex"` + - `beta_computer_tool: object { type }` - - `"gpt-5-pro"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"gpt-5-pro-2025-10-06"` + - `type: "computer"` - - `"gpt-5.1-codex-max"` + The type of the computer tool. Always `computer`. - - `object: "response"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The object type of this resource - always set to `response`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `output: array of BetaResponseOutputItem` + - `display_height: number` - An array of content items generated by the model. + The height of the computer display. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `display_width: number` - - `beta_response_output_message: object { id, content, role, 4 more }` + The width of the computer display. - An output message from the model. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `id: string` + The type of computer environment to control. - The unique ID of the output message. + - `"windows"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"mac"` - The content of the output message. + - `"linux"` - - `role: "assistant"` + - `"ubuntu"` - The role of the output message. Always `assistant`. + - `"browser"` - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "computer_use_preview"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The type of the computer use tool. Always `computer_use_preview`. - - `type: "message"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the output message. Always `message`. + 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). - - `agent: optional object { agent_name }` + - `type: "web_search" or "web_search_2025_08_26"` - The agent that produced this item. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `phase: optional "commentary"` + - `"web_search"` - 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. + - `"web_search_2025_08_26"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `filters: optional object { allowed_domains }` - 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. + Filters for the search. - - `id: string` + - `allowed_domains: optional array of string` - The unique ID of the file search tool call. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `queries: array of string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The queries used to search for files. + - `search_context_size: optional "low" or "medium" or "high"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + 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. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"low"` - - `type: "file_search_call"` + - `"medium"` - The type of the file search tool call. Always `file_search_call`. + - `"high"` - - `agent: optional object { agent_name }` + - `user_location: optional object { city, country, region, 2 more }` - The agent that produced this item. + The approximate location of the user. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `city: optional string` - The results of the file search tool call. + Free text input for the city of the user, e.g. `San Francisco`. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `country: optional string` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `arguments: string` + - `region: optional string` - A JSON string of the arguments to pass to the function. + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The unique ID of the function tool call generated by the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `name: string` + - `type: optional "approximate"` - The name of the function to run. + The type of location approximation. Always `approximate`. - - `type: "function_call"` + - `"approximate"` - The type of the function tool call. Always `function_call`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `id: optional string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The unique ID of the function tool call. + - `server_label: string` - - `agent: optional object { agent_name }` + A label for this MCP server, used to identify it in tool calls. - The agent that produced this item. + - `type: "mcp"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the MCP tool. Always `mcp`. - The execution context that produced this tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `namespace: optional string` + The tool invocation context(s). - The namespace of the function to run. + - `"direct"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"programmatic"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + List of allowed tool names or a filter object. - - `id: string` + - `MCP allowed tools: array of string` - The unique ID of the function call tool output. + A string array of allowed tool names - - `call_id: string` + - `MCP tool filter: object { read_only, tool_names }` - The unique ID of the function tool call generated by the model. + A filter object to specify which tools are allowed. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `read_only: optional boolean` - The output from the function call generated by your code. - Can be a string or an list of output content. + 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. - - `string output: string` + - `tool_names: optional array of string` - A string of the output of the function call. + List of allowed tool names. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `authorization: optional string` - Text, image, or file output of the function call. + 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. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - A text input to the model. + 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). - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + Currently supported `connector_id` values are: - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - 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` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"connector_dropbox"` - A file input to the model. + - `"connector_gmail"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"connector_googlecalendar"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"connector_googledrive"` - - `"in_progress"` + - `"connector_microsoftteams"` - - `"completed"` + - `"connector_outlookcalendar"` - - `"incomplete"` + - `"connector_outlookemail"` - - `type: "function_call_output"` + - `"connector_sharepoint"` - The type of the function tool call output. Always `function_call_output`. + - `defer_loading: optional boolean` - - `agent: optional object { agent_name }` + Whether this MCP tool is deferred and discovered via tool search. - The agent that produced this item. + - `headers: optional map[string]` - - `agent_name: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The canonical name of the agent that produced this item. + - `require_approval: optional object { always, never } or "always" or "never"` - - `caller: optional object { type } or object { caller_id, type }` + Specify which of the MCP server's tools require approval. - The execution context that produced this tool call. + - `MCP tool approval filter: object { always, never }` - - `direct: object { type }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `program: object { caller_id, type }` + - `always: optional object { read_only, tool_names }` - - `caller_id: string` + A filter object to specify which tools are allowed. - The call ID of the program item that produced this tool call. + - `read_only: optional boolean` - - `type: "program"` + 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. - The caller type. Always `program`. + - `tool_names: optional array of string` - - `created_by: optional string` + List of allowed tool names. - The identifier of the actor that created the item. + - `never: optional object { read_only, tool_names }` - - `agent_message: object { id, author, content, 3 more }` + A filter object to specify which tools are allowed. - - `id: string` + - `read_only: optional boolean` - The unique ID of the agent message. + 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. - - `author: string` + - `tool_names: optional array of string` - The sending agent identity. + List of allowed tool names. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `MCP tool approval setting: "always" or "never"` - Encrypted content sent between agents. + 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. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `"always"` - A text input to the model. + - `"never"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `server_description: optional string` - A text output from the model. + Optional description of the MCP server, used to provide more context. - - `text: object { text, type }` + - `server_url: optional string` - A text content. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `text: string` + - `tunnel_id: optional string` - - `type: "text"` + 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. - - `summary_text: object { text, type }` + - `code_interpreter: object { container, type, allowed_callers }` - A summary text from the model. + A tool that runs Python code to help generate a response to a prompt. - - `text: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - A summary of the reasoning output from the model so far. + 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. - - `type: "summary_text"` + - `union_member_0: string` - The type of the object. Always `summary_text`. + The container ID. - - `reasoning_text: object { text, type }` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - Reasoning text from the model. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `text: string` + - `type: "auto"` - The reasoning text from the model. + Always `auto`. - - `type: "reasoning_text"` + - `file_ids: optional array of string` - The type of the reasoning text. Always `reasoning_text`. + An optional list of uploaded files to make available to your code. - - `beta_response_output_refusal: object { refusal, type }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - A refusal from the model. + The memory limit for the code interpreter container. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"1g"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"4g"` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `"16g"` - A screenshot of a computer. + - `"64g"` - - `detail: "low" or "high" or "auto" or "original"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Network access policy for the container. - - `"low"` + - `beta_container_network_policy_disabled: object { type }` - - `"high"` + - `type: "disabled"` - - `"auto"` + Disable outbound network access. Always `disabled`. - - `"original"` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `file_id: string` + - `allowed_domains: array of string` - The identifier of an uploaded file that contains the screenshot. + A list of allowed domains when type is `allowlist`. - - `image_url: string` + - `type: "allowlist"` - The URL of the screenshot image. + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "computer_screenshot"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Optional domain-scoped secrets for allowlisted domains. - - `prompt_cache_breakpoint: optional object { mode }` + - `domain: string` - 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. + The domain associated with the secret. - - `mode: "explicit"` + - `name: string` - The breakpoint mode. Always `explicit`. + The name of the secret to inject for the domain. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `value: string` - A file input to the model. + The secret value to inject for the domain. - - `encrypted_content: object { encrypted_content, type }` + - `type: "code_interpreter"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The type of the code interpreter tool. Always `code_interpreter`. - - `encrypted_content: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Opaque encrypted content. + The tool invocation context(s). - - `type: "encrypted_content"` + - `"direct"` - The type of the input item. Always `encrypted_content`. + - `"programmatic"` - - `recipient: string` + - `programmatic_tool_calling: object { type }` - The destination agent identity. + - `image_generation: object { type, action, background, 9 more }` - - `type: "agent_message"` + A tool that generates images using the GPT image models. - The type of the item. Always `agent_message`. + - `type: "image_generation"` - - `agent: optional object { agent_name }` + The type of the image generation tool. Always `image_generation`. - The agent that produced this item. + - `action: optional "generate" or "edit" or "auto"` - - `agent_name: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The canonical name of the agent that produced this item. + - `"generate"` - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `"edit"` - - `id: string` + - `"auto"` - The unique ID of the multi-agent call item. + - `background: optional "transparent" or "opaque" or "auto"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + 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. - The multi-agent action to execute. + `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. - - `"spawn_agent"` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `"interrupt_agent"` + - `"transparent"` - - `"list_agents"` + - `"opaque"` - - `"send_message"` + - `"auto"` - - `"followup_task"` + - `input_fidelity: optional "high" or "low"` - - `"wait_agent"` + 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`. - - `arguments: string` + - `"high"` - The JSON string of arguments generated for the action. + - `"low"` - - `call_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The unique ID linking this call to its output. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "multi_agent_call"` + - `file_id: optional string` - The type of the multi-agent call. Always `multi_agent_call`. + File ID for the mask image. - - `agent: optional object { agent_name }` + - `image_url: optional string` - The agent that produced this item. + Base64-encoded mask image. - - `agent_name: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - The canonical name of the agent that produced this item. + The image generation model to use. Default: `gpt-image-1`. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `"gpt-image-1"` - - `id: string` + - `"gpt-image-1-mini"` - The unique ID of the multi-agent call output item. + - `"gpt-image-2"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"gpt-image-2-2026-04-21"` - The multi-agent action that produced this result. + - `"gpt-image-1.5"` - - `"spawn_agent"` + - `"chatgpt-image-latest"` - - `"interrupt_agent"` + - `moderation: optional "auto" or "low"` - - `"list_agents"` + Moderation level for the generated image. Default: `auto`. - - `"send_message"` + - `"auto"` - - `"followup_task"` + - `"low"` - - `"wait_agent"` + - `output_compression: optional number` - - `call_id: string` + Compression level for the output image. Default: 100. - The unique ID of the multi-agent call. + - `output_format: optional "png" or "webp" or "jpeg"` - - `output: array of BetaResponseOutputText` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Text output returned by the multi-agent action. + - `"png"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"webp"` - The annotations of the text output. + - `"jpeg"` - - `text: string` + - `partial_images: optional number` - The text output from the model. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "output_text"` + - `quality: optional "low" or "medium" or "high" or "auto"` - The type of the output text. Always `output_text`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `"low"` - - `type: "multi_agent_call_output"` + - `"medium"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"high"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `agent_name: string` + 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`. - The canonical name of the agent that produced this item. + - `"1024x1024"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `"1024x1536"` - 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. + - `"1536x1024"` - - `id: string` + - `"auto"` - The unique ID of the web search tool call. + - `local_shell: object { type }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + A tool that allows the model to execute shell commands in a local environment. - 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). + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + A tool that allows the model to execute shell commands. - The status of the web search tool call. + - `type: "shell"` - - `type: "web_search_call"` + The type of the shell tool. Always `shell`. - The type of the web search tool call. Always `web_search_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `"programmatic"` - 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. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: string` + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - The unique ID of the computer call. + - `type: "container_auto"` - - `call_id: string` + Automatically creates a container for this request - An identifier used when responding to the tool call with output. + - `file_ids: optional array of string` - - `pending_safety_checks: array of object { id, code, message }` + An optional list of uploaded files to make available to your code. - The pending safety checks for the computer call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `status: "in_progress" or "completed" or "incomplete"` + The memory limit for the container. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"1g"` - - `type: "computer_call"` + - `"4g"` - The type of the computer call. Always `computer_call`. + - `"16g"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `"64g"` - A click action. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `actions: optional array of BetaComputerAction` + Network access policy for the container. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `beta_container_network_policy_disabled: object { type }` - - `agent: optional object { agent_name }` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The agent that produced this item. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + An optional list of skills referenced by id or inline data. - - `id: string` + - `beta_skill_reference: object { skill_id, type, version }` - The unique ID of the computer call tool output. + - `skill_id: string` - - `call_id: string` + The ID of the referenced skill. - The ID of the computer tool call that produced the output. + - `type: "skill_reference"` - - `output: object { type, file_id, image_url }` + References a skill created with the /v1/skills endpoint. - A computer screenshot image used with the computer use tool. + - `version: optional string` - - `type: "computer_screenshot"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `beta_inline_skill: object { description, name, source, type }` - - `file_id: optional string` + - `description: string` - The identifier of an uploaded file that contains the screenshot. + The description of the skill. - - `image_url: optional string` + - `name: string` - The URL of the screenshot image. + The name of the skill. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `source: object { data, media_type, type }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Inline skill payload - - `"completed"` + - `data: string` - - `"incomplete"` + Base64-encoded skill zip bundle. - - `"failed"` + - `media_type: "application/zip"` - - `"in_progress"` + The media type of the inline skill payload. Must be `application/zip`. - - `type: "computer_call_output"` + - `type: "base64"` - The type of the computer tool call output. Always `computer_call_output`. + The type of the inline skill source. Must be `base64`. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "inline"` - The safety checks reported by the API that have been acknowledged by the - developer. + Defines an inline skill for this request. - - `id: string` + - `beta_local_environment: object { type, skills }` - The ID of the pending safety check. + - `type: "local"` - - `code: optional string` + Use a local computer environment. - The type of the pending safety check. + - `skills: optional array of BetaLocalSkill` - - `message: optional string` + An optional list of skills. - Details about the pending safety check. + - `description: string` - - `agent: optional object { agent_name }` + The description of the skill. - The agent that produced this item. + - `name: string` - - `agent_name: string` + The name of the skill. - The canonical name of the agent that produced this item. + - `path: string` - - `created_by: optional string` + The path to the directory containing the skill. - The identifier of the actor that created the item. + - `beta_container_reference: object { container_id, type }` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `container_id: string` - 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). + The ID of the referenced container. - - `id: string` + - `type: "container_reference"` - The unique identifier of the reasoning content. + References a container created with the /v1/containers endpoint - - `summary: array of object { text, type }` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Reasoning summary content. + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `type: "reasoning"` + - `name: string` - The type of the object. Always `reasoning`. + The name of the custom tool, used to identify it in tool calls. - - `agent: optional object { agent_name }` + - `type: "custom"` - The agent that produced this item. + The type of the custom tool. Always `custom`. - - `content: optional array of object { text, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Reasoning text content. + The tool invocation context(s). - - `encrypted_content: optional string` + - `"direct"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"programmatic"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `defer_loading: optional boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Whether this tool should be deferred and discovered via tool search. - - `program: object { id, call_id, code, 3 more }` + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the program item. + - `format: optional object { type } or object { definition, syntax, type }` - - `call_id: string` + The input format for the custom tool. Default is unconstrained text. - The stable call ID of the program item. + - `text: object { type }` - - `code: string` + Unconstrained free-form text. - The JavaScript source executed by programmatic tool calling. + - `grammar: object { definition, syntax, type }` - - `fingerprint: string` + A grammar defined by the user. - Opaque program replay fingerprint that must be round-tripped. + - `definition: string` - - `type: "program"` + The grammar definition. - The type of the item. Always `program`. + - `syntax: "lark" or "regex"` - - `agent: optional object { agent_name }` + The syntax of the grammar definition. One of `lark` or `regex`. - The agent that produced this item. + - `"lark"` - - `agent_name: string` + - `"regex"` - The canonical name of the agent that produced this item. + - `type: "grammar"` - - `program_output: object { id, call_id, result, 3 more }` + Grammar format. Always `grammar`. - - `id: string` + - `beta_namespace_tool: object { description, name, tools, type }` - The unique ID of the program output item. + Groups function/custom tools under a shared namespace. - - `call_id: string` + - `description: string` - The call ID of the program item. + A description of the namespace shown to the model. - - `result: string` + - `name: string` - The result produced by the program item. + The namespace name used in tool calls (for example, `crm`). - - `status: "completed" or "incomplete"` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - The terminal status of the program output item. + The function/custom tools available inside this namespace. - - `"completed"` + - `function: object { name, type, allowed_callers, 5 more }` - - `"incomplete"` + - `name: string` - - `type: "program_output"` + - `type: "function"` - The type of the item. Always `program_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `defer_loading: optional boolean` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + Whether this function should be deferred and discovered via tool search. - - `id: string` + - `description: optional string` - The unique ID of the tool search call item. + - `output_schema: optional map[unknown]` - - `arguments: unknown` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Arguments used for the tool search call. + - `parameters: optional unknown` - - `call_id: string` + - `strict: optional boolean` - The unique ID of the tool search call generated by the model. + 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. - - `execution: "server" or "client"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - Whether tool search was executed by the server or by the client. + 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) - - `"server"` + - `name: string` - - `"client"` + The name of the custom tool, used to identify it in tool calls. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "custom"` - The status of the tool search call item that was recorded. + The type of the custom tool. Always `custom`. - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `defer_loading: optional boolean` - - `type: "tool_search_call"` + Whether this tool should be deferred and discovered via tool search. - The type of the item. Always `tool_search_call`. + - `description: optional string` - - `agent: optional object { agent_name }` + Optional description of the custom tool, used to provide more context. - The agent that produced this item. + - `format: optional object { type } or object { definition, syntax, type }` - - `agent_name: string` + The input format for the custom tool. Default is unconstrained text. - The canonical name of the agent that produced this item. + - `type: "namespace"` - - `created_by: optional string` + The type of the tool. Always `namespace`. - The identifier of the actor that created the item. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + Hosted or BYOT tool search configuration for deferred tools. - - `id: string` + - `type: "tool_search"` - The unique ID of the tool search output item. + The type of the tool. Always `tool_search`. - - `call_id: string` + - `description: optional string` - The unique ID of the tool search call generated by the model. + Description shown to the model for a client-executed tool search tool. - - `execution: "server" or "client"` + - `execution: optional "server" or "client"` - Whether tool search was executed by the server or by the client. + Whether tool search is executed by the server or by the client. - `"server"` - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the tool search output item that was recorded. - - - `"in_progress"` + - `parameters: optional unknown` - - `"completed"` + Parameter schema for a client-executed tool search tool. - - `"incomplete"` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `tools: array of BetaTool` + 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). - The loaded tool definitions returned by tool search. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - 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). + - `"web_search_preview"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `"web_search_preview_2025_03_11"` - 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). + - `search_content_types: optional array of "text" or "image"` - - `beta_computer_tool: object { type }` + - `"text"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"image"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `search_context_size: optional "low" or "medium" or "high"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + 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. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `"low"` - 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). + - `"medium"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `"high"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `user_location: optional object { type, city, country, 2 more }` - - `code_interpreter: object { container, type, allowed_callers }` + The user's location. - A tool that runs Python code to help generate a response to a prompt. + - `type: "approximate"` - - `programmatic_tool_calling: object { type }` + The type of location approximation. Always `approximate`. - - `image_generation: object { type, action, background, 9 more }` + - `city: optional string` - A tool that generates images using the GPT image models. + Free text input for the city of the user, e.g. `San Francisco`. - - `local_shell: object { type }` + - `country: optional string` - A tool that allows the model to execute shell commands in a local environment. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `region: optional string` - A tool that allows the model to execute shell commands. + Free text input for the region of the user, e.g. `California`. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `timezone: optional string` - 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) + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `beta_namespace_tool: object { description, name, tools, type }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - Groups function/custom tools under a shared namespace. + Allows the assistant to create, delete, or update files using unified diffs. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `type: "apply_patch"` - Hosted or BYOT tool search configuration for deferred tools. + The type of the tool. Always `apply_patch`. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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). + The tool invocation context(s). - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"direct"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"programmatic"` - `type: "tool_search_output"` @@ -82412,10 +94195,44 @@ openai beta:responses compact \ The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + - `type: "code_interpreter_call"` The type of the code interpreter tool call. Always `code_interpreter_call`. @@ -82424,6 +94241,10 @@ openai beta:responses compact \ The agent that produced this item. + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `local_shell_call: object { id, action, call_id, 3 more }` A tool call to run a command on the local shell. @@ -83051,1000 +94872,80 @@ openai beta:responses compact \ The agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `namespace: optional string` - - The namespace of the custom tool being called. - - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - The output of a custom tool call from your code, being sent back to the model. - - - `id: string` - - The unique ID of the custom tool call output item. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `parallel_tool_calls: boolean` - - Whether to allow the model to run tool calls in parallel. - - - `temperature: number` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. - - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. - - - `beta_tool_choice_options: "none" or "auto" or "required"` - - Controls which (if any) tool is called by the model. - - `none` means the model will not call any tool and instead generates a message. - - `auto` means the model can pick between generating a message or calling one or - more tools. - - `required` means the model must call one or more tools. - - - `"none"` - - - `"auto"` - - - `"required"` - - - `beta_tool_choice_allowed: object { mode, tools, type }` - - Constrains the tools available to the model to a pre-defined set. - - - `mode: "auto" or "required"` - - Constrains the tools available to the model to a pre-defined set. - - `auto` allows the model to pick from among the allowed tools and generate a - message. - - `required` requires the model to call one or more of the allowed tools. - - - `"auto"` - - - `"required"` - - - `tools: array of map[unknown]` - - A list of tool definitions that the model should be allowed to call. - - For the Responses API, the list of tool definitions might look like: - - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` - - - `type: "allowed_tools"` - - Allowed tool configuration type. Always `allowed_tools`. - - - `beta_tool_choice_types: object { type }` - - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - Allowed values are: - - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` - - - `"file_search"` - - - `"web_search_preview"` - - - `"computer"` - - - `"computer_use_preview"` - - - `"computer_use"` - - - `"web_search_preview_2025_03_11"` - - - `"image_generation"` - - - `"code_interpreter"` - - - `beta_tool_choice_function: object { name, type }` - - Use this option to force the model to call a specific function. - - - `name: string` - - The name of the function to call. - - - `type: "function"` - - For function calling, the type is always `function`. - - - `beta_tool_choice_mcp: object { server_label, type, name }` - - Use this option to force the model to call a specific tool on a remote MCP server. - - - `server_label: string` - - The label of the MCP server to use. - - - `type: "mcp"` - - For MCP tools, the type is always `mcp`. - - - `name: optional string` - - The name of the tool to call on the server. - - - `beta_tool_choice_custom: object { name, type }` - - Use this option to force the model to call a specific custom tool. - - - `name: string` - - The name of the custom tool to call. - - - `type: "custom"` - - For custom tool calling, the type is always `custom`. - - - `BetaSpecificProgrammaticToolCallingParam: object { type }` - - - `beta_tool_choice_apply_patch: object { type }` - - Forces the model to call the apply_patch tool when executing a tool call. - - - `type: "apply_patch"` - - The tool to call. Always `apply_patch`. - - - `beta_tool_choice_shell: object { type }` - - Forces the model to call the shell tool when a tool call is required. - - - `type: "shell"` - - The tool to call. Always `shell`. - - - `tools: array of BetaTool` - - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. - - We support the following categories of tools: - - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. - - - `beta_function_tool: object { name, parameters, strict, 5 more }` - - 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). - - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - 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). - - - `beta_computer_tool: object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - 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: object { server_label, type, allowed_callers, 9 more }` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - - `code_interpreter: object { container, type, allowed_callers }` - - A tool that runs Python code to help generate a response to a prompt. - - - `programmatic_tool_calling: object { type }` - - - `image_generation: object { type, action, background, 9 more }` - - A tool that generates images using the GPT image models. - - - `local_shell: object { type }` - - A tool that allows the model to execute shell commands in a local environment. - - - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - A tool that allows the model to execute shell commands. - - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - 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) - - - `beta_namespace_tool: object { description, name, tools, type }` - - Groups function/custom tools under a shared namespace. - - - `beta_tool_search_tool: object { type, description, execution, parameters }` - - Hosted or BYOT tool search configuration for deferred tools. - - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `beta_apply_patch_tool: object { type, allowed_callers }` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `top_p: number` - - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. - - We generally recommend altering this or `temperature` but not both. - - - `background: optional boolean` - - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). - - - `completed_at: optional number` - - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. - - - `conversation: optional object { id }` - - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - - `id: string` - - The unique ID of the conversation that this response was associated with. - - - `max_output_tokens: optional number` - - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - - `max_tool_calls: optional number` - - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - - `moderation: optional object { input, output }` - - Moderation results for the response input and output, if moderated completions were requested. - - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - Moderation for the response input. - - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - A moderation result produced for the response input or output. - - - `categories: map[boolean]` - - A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - - `category_applied_input_types: map[array of "text" or "image"]` - - Which modalities of input are reflected by the score for each category. - - - `"text"` - - - `"image"` - - - `category_scores: map[number]` - - A dictionary of moderation categories to scores. - - - `flagged: boolean` - - A boolean indicating whether the content was flagged by any category. - - - `model: string` - - The moderation model that produced this result. - - - `type: "moderation_result"` - - The object type, which was always `moderation_result` for successful moderation results. - - - `error: object { code, message, type }` - - An error produced while attempting moderation for the response input or output. - - - `code: string` - - The error code. - - - `message: string` - - The error message. - - - `type: "error"` - - The object type, which was always `error` for moderation failures. - - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - Moderation for the response output. - - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - A moderation result produced for the response input or output. - - - `categories: map[boolean]` - - A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - - `category_applied_input_types: map[array of "text" or "image"]` - - Which modalities of input are reflected by the score for each category. - - - `"text"` - - - `"image"` - - - `category_scores: map[number]` - - A dictionary of moderation categories to scores. - - - `flagged: boolean` - - A boolean indicating whether the content was flagged by any category. - - - `model: string` - - The moderation model that produced this result. - - - `type: "moderation_result"` - - The object type, which was always `moderation_result` for successful moderation results. - - - `error: object { code, message, type }` - - An error produced while attempting moderation for the response input or output. - - - `code: string` - - The error code. - - - `message: string` - - The error message. - - - `type: "error"` - - The object type, which was always `error` for moderation failures. - - - `previous_response_id: optional string` - - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - - `prompt: optional object { id, variables, version }` - - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - - `id: string` - - The unique identifier of the prompt template to use. - - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. - - - `union_member_0: string` - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `version: optional string` - - Optional version of the prompt template. - - - `prompt_cache_key: optional string` - - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - - `prompt_cache_options: optional object { mode, ttl }` - - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - - `mode: "implicit" or "explicit"` - - Whether implicit prompt-cache breakpoints were enabled. - - - `"implicit"` - - - `"explicit"` - - - `ttl: "30m"` - - The minimum lifetime applied to each cache breakpoint. - - - `"30m"` - - - `prompt_cache_retention: optional "in_memory" or "24h"` - - Deprecated. Use `prompt_cache_options.ttl` instead. - - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - - `"in_memory"` - - - `"24h"` - - - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - **gpt-5 and o-series models only** - - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - - `context: optional "auto" or "current_turn" or "all_turns"` - - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. - - - `"auto"` - - - `"current_turn"` - - - `"all_turns"` - - - `effort: optional "none" or "minimal" or "low" or 4 more` - - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. - - - `"none"` - - - `"minimal"` - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"xhigh"` - - - `"max"` - - - `generate_summary: optional "auto" or "concise" or "detailed"` - - **Deprecated:** use `summary` instead. - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - - `"auto"` - - - `"concise"` - - - `"detailed"` - - - `mode: optional string or "standard" or "pro"` - - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - - - `"standard"` - - - `"pro"` - - - `summary: optional "auto" or "concise" or "detailed"` - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - - `"auto"` - - - `"concise"` - - - `"detailed"` - - - `safety_identifier: optional string` - - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - Specifies the processing type used for serving the request. - - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. - - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - - `"auto"` - - - `"default"` - - - `"flex"` - - - `"scale"` - - - `"priority"` - - - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. - - - `"completed"` - - - `"failed"` - - - `"in_progress"` - - - `"cancelled"` - - - `"queued"` - - - `"incomplete"` - - - `text: optional object { format, verbosity }` - - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: - - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - An object specifying the format that the model must output. - - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - The default format is `{ "type": "text" }` with no additional options. - - **Not recommended for gpt-4o and newer models:** - - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. - - - `text: object { type }` - - Default response format. Used to generate text responses. - - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `name: string` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `schema: map[unknown]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `type: "json_schema"` - - The type of response format being defined. Always `json_schema`. - - - `description: optional string` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `strict: optional boolean` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_object: object { type }` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `verbosity: optional "low" or "medium" or "high"` - - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `top_logprobs: optional number` - - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - - - `truncation: optional "auto" or "disabled"` - - The truncation strategy to use for the model response. - - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. - - - `"auto"` - - - `"disabled"` - - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. - - - `input_tokens: number` - - The number of input tokens. - - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - A detailed breakdown of the input tokens. - - - `cache_write_tokens: number` - - The number of input tokens that were written to the cache. - - - `cached_tokens: number` - - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - - `output_tokens: number` - - The number of output tokens. - - - `output_tokens_details: object { reasoning_tokens }` - - A detailed breakdown of the output tokens. - - - `reasoning_tokens: number` - - The number of reasoning tokens. - - - `total_tokens: number` - - The total number of tokens used. - - - `user: optional string` - - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - - `sequence_number: number` - - The sequence number of this event. - - - `type: "response.incomplete"` - - The type of the event. Always `response.incomplete`. - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Input - -- `beta_response_input: array of BetaResponseInputItem` - - A list of one or many input items to the model, containing - different content types. - - - `beta_easy_input_message: object { content, role, phase, type }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: string or BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `Text input: string` - - A text input to the model. - - - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `role: "user" or "assistant" or "system" or "developer"` - - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - - - `"user"` + - `caller: optional object { type } or object { caller_id, type }` - - `"assistant"` + The execution context that produced this tool call. - - `"system"` + - `direct: object { type }` - - `"developer"` + - `program: object { caller_id, type }` - - `phase: optional "commentary"` + - `caller_id: string` - 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. + The call ID of the program item that produced this tool call. - - `"commentary"` + - `type: "program"` - - `type: optional "message"` + - `namespace: optional string` - The type of the message input. Always `message`. + The namespace of the custom tool being called. - - `"message"` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `message: object { content, role, agent, 2 more }` + The output of a custom tool call from your code, being sent back to the model. - 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. + - `id: string` - - `content: array of BetaResponseInputContent` + The unique ID of the custom tool call output item. - A list of one or many input items to the model, containing different content - types. + - `status: "in_progress" or "completed" or "incomplete"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A text input to the model. + - `"in_progress"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `"completed"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"incomplete"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `created_by: optional string` - A file input to the model. + The identifier of the actor that created the item. - - `role: "user" or "system" or "developer"` + - `output_index: number` - The role of the message input. One of `user`, `system`, or `developer`. + The index of the output item that was added. - - `"user"` + - `sequence_number: number` - - `"system"` + The sequence number of this event. - - `"developer"` + - `type: "response.output_item.added"` + + The type of the event. Always `response.output_item.added`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` +### Beta Response Output Item Done Event - - `"incomplete"` +- `beta_response_output_item_done_event: object { item, output_index, sequence_number, 2 more }` - - `type: optional "message"` + Emitted when an output item is marked done. - The type of the message input. Always set to `message`. + - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` - - `"message"` + The output item that was marked done. - `beta_response_output_message: object { id, content, role, 4 more }` @@ -84217,7 +95118,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -84225,6 +95126,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -84299,36 +95202,58 @@ openai beta:responses compact \ The text that was retrieved from the file. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - 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. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `call_id: string` - An identifier used when responding to the tool call with output. + The unique ID of the function tool call generated by the model. - - `pending_safety_checks: array of object { id, code, message }` + - `name: string` - The pending safety checks for the computer call. + The name of the function to run. - - `id: string` + - `type: "function_call"` - The ID of the pending safety check. + The type of the function tool call. Always `function_call`. - - `code: optional string` + - `id: optional string` - The type of the pending safety check. + The unique ID of the function tool call. - - `message: optional string` + - `agent: optional object { agent_name }` - Details about the pending safety check. + The agent that produced this item. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -84339,278 +95264,333 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "computer_call"` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - The type of the computer call. Always `computer_call`. + - `id: string` - - `"computer_call"` + The unique ID of the function call tool output. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `call_id: string` - A click action. + The unique ID of the function tool call generated by the model. - - `click: object { button, type, x, 2 more }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A click action. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `button: "left" or "right" or "wheel" or 2 more` + - `string output: string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + A string of the output of the function call. - - `"left"` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"right"` + Text, image, or file output of the function call. - - `"wheel"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"back"` + A text input to the model. - - `"forward"` + - `text: string` - - `type: "click"` + The text input to the model. - Specifies the event type. For a click action, this property is always `click`. + - `type: "input_text"` - - `x: number` + The type of the input item. Always `input_text`. - The x-coordinate where the click occurred. + - `prompt_cache_breakpoint: optional object { mode }` - - `y: number` + 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. - The y-coordinate where the click occurred. + - `mode: "explicit"` - - `keys: optional array of string` + The breakpoint mode. Always `explicit`. - The keys being held while clicking. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `double_click: object { keys, type, x, y }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A double click action. + - `detail: "low" or "high" or "auto" or "original"` - - `keys: array of string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The keys being held while double-clicking. + - `"low"` - - `type: "double_click"` + - `"high"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"auto"` - - `x: number` + - `"original"` - The x-coordinate where the double click occurred. + - `type: "input_image"` - - `y: number` + The type of the input item. Always `input_image`. - The y-coordinate where the double click occurred. + - `file_id: optional string` - - `drag: object { path, type, keys }` + The ID of the file to be sent to the model. - A drag action. + - `image_url: optional string` - - `path: array of object { x, y }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `prompt_cache_breakpoint: optional object { mode }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + 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. - - `x: number` + - `mode: "explicit"` - The x-coordinate. + The breakpoint mode. Always `explicit`. - - `y: number` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The y-coordinate. + A file input to the model. - - `type: "drag"` + - `type: "input_file"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The type of the input item. Always `input_file`. - - `keys: optional array of string` + - `detail: optional "auto" or "low" or "high"` - The keys being held while dragging the mouse. + 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`. - - `keypress: object { keys, type }` + - `"auto"` - A collection of keypresses the model would like to perform. + - `"low"` - - `keys: array of string` + - `"high"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `file_data: optional string` - - `type: "keypress"` + The content of the file to be sent to the model. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `file_id: optional string` - - `move: object { type, x, y, keys }` + The ID of the file to be sent to the model. - A mouse move action. + - `file_url: optional string` - - `type: "move"` + The URL of the file to be sent to the model. - Specifies the event type. For a move action, this property is always set to `move`. + - `filename: optional string` - - `x: number` + The name of the file to be sent to the model. - The x-coordinate to move to. + - `prompt_cache_breakpoint: optional object { mode }` - - `y: number` + 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. - The y-coordinate to move to. + - `mode: "explicit"` - - `keys: optional array of string` + The breakpoint mode. Always `explicit`. - The keys being held while moving the mouse. + - `status: "in_progress" or "completed" or "incomplete"` - - `screenshot: object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A screenshot action. + - `"in_progress"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"completed"` - A scroll action. + - `"incomplete"` - - `scroll_x: number` + - `type: "function_call_output"` - The horizontal scroll distance. + The type of the function tool call output. Always `function_call_output`. - - `scroll_y: number` + - `agent: optional object { agent_name }` - The vertical scroll distance. + The agent that produced this item. - - `type: "scroll"` + - `agent_name: string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The canonical name of the agent that produced this item. - - `x: number` + - `caller: optional object { type } or object { caller_id, type }` - The x-coordinate where the scroll occurred. + The execution context that produced this tool call. - - `y: number` + - `direct: object { type }` - The y-coordinate where the scroll occurred. + - `program: object { caller_id, type }` - - `keys: optional array of string` + - `caller_id: string` - The keys being held while scrolling. + The call ID of the program item that produced this tool call. - - `type: object { text, type }` + - `type: "program"` - An action to type in text. + The caller type. Always `program`. - - `text: string` + - `created_by: optional string` - The text to type. + The identifier of the actor that created the item. - - `type: "type"` + - `agent_message: object { id, author, content, 3 more }` - Specifies the event type. For a type action, this property is always set to `type`. + - `id: string` - - `wait: object { type }` + The unique ID of the agent message. - A wait action. + - `author: string` - - `actions: optional array of BetaComputerAction` + The sending agent identity. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `click: object { button, type, x, 2 more }` + Encrypted content sent between agents. - A click action. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `double_click: object { keys, type, x, y }` + A text input to the model. - A double click action. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `drag: object { path, type, keys }` + A text output from the model. - A drag action. + - `text: object { text, type }` - - `keypress: object { keys, type }` + A text content. - A collection of keypresses the model would like to perform. + - `text: string` - - `move: object { type, x, y, keys }` + - `type: "text"` - A mouse move action. + - `summary_text: object { text, type }` - - `screenshot: object { type }` + A summary text from the model. - A screenshot action. + - `text: string` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + A summary of the reasoning output from the model so far. - A scroll action. + - `type: "summary_text"` - - `type: object { text, type }` + The type of the object. Always `summary_text`. - An action to type in text. + - `reasoning_text: object { text, type }` - - `wait: object { type }` + Reasoning text from the model. - A wait action. + - `text: string` - - `agent: optional object { agent_name }` + The reasoning text from the model. - The agent that produced this item. + - `type: "reasoning_text"` - - `agent_name: string` + The type of the reasoning text. Always `reasoning_text`. - The canonical name of the agent that produced this item. + - `beta_response_output_refusal: object { refusal, type }` - - `computer_call_output: object { call_id, output, type, 4 more }` + A refusal from the model. - The output of a computer tool call. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `call_id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The ID of the computer tool call that produced the output. + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - - `output: object { type, file_id, image_url }` + A screenshot of a computer. - A computer screenshot image used with the computer use tool. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "computer_screenshot"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"low"` - - `file_id: optional string` + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` The identifier of an uploaded file that contains the screenshot. - - `image_url: optional string` + - `image_url: string` The URL of the screenshot image. - - `type: "computer_call_output"` + - `type: "computer_screenshot"` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `id: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the computer tool call output. + 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. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `mode: "explicit"` - The safety checks reported by the API that have been acknowledged by the developer. + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `multi_agent_call: object { id, action, arguments, 3 more }` - `id: string` - The ID of the pending safety check. + The unique ID of the multi-agent call item. - - `code: optional string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The type of the pending safety check. + The multi-agent action to execute. - - `message: optional string` + - `"spawn_agent"` - Details about the pending safety check. + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` @@ -84620,15 +95600,61 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `id: string` - - `"in_progress"` + The unique ID of the multi-agent call output item. - - `"completed"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"incomplete"` + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of BetaResponseOutputText` + + Text output returned by the multi-agent action. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `type: "multi_agent_call_output"` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `beta_response_function_web_search: object { id, action, status, 2 more }` @@ -84724,303 +95750,330 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + 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. - - `arguments: string` + - `id: string` - A JSON string of the arguments to pass to the function. + The unique ID of the computer call. - `call_id: string` - The unique ID of the function tool call generated by the model. + An identifier used when responding to the tool call with output. - - `name: string` + - `pending_safety_checks: array of object { id, code, message }` - The name of the function to run. + The pending safety checks for the computer call. - - `type: "function_call"` + - `id: string` - The type of the function tool call. Always `function_call`. + The ID of the pending safety check. - - `id: optional string` + - `code: optional string` - The unique ID of the function tool call. + The type of the pending safety check. - - `agent: optional object { agent_name }` + - `message: optional string` - The agent that produced this item. + Details about the pending safety check. - - `agent_name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `caller: optional object { type } or object { caller_id, type }` + - `"in_progress"` - The execution context that produced this tool call. + - `"completed"` - - `direct: object { type }` + - `"incomplete"` - - `program: object { caller_id, type }` + - `type: "computer_call"` - - `caller_id: string` + The type of the computer call. Always `computer_call`. - The call ID of the program item that produced this tool call. + - `"computer_call"` - - `type: "program"` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `namespace: optional string` + A click action. - The namespace of the function to run. + - `click: object { button, type, x, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A click action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `button: "left" or "right" or "wheel" or 2 more` - - `"in_progress"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"completed"` + - `"left"` - - `"incomplete"` + - `"right"` - - `function_call_output: object { call_id, output, type, 4 more }` + - `"wheel"` - The output of a function tool call. + - `"back"` - - `call_id: string` + - `"forward"` - The unique ID of the function tool call generated by the model. + - `type: "click"` - - `output: string or BetaResponseFunctionCallOutputItemList` + Specifies the event type. For a click action, this property is always `click`. - Text, image, or file output of the function tool call. + - `x: number` - - `union_member_0: string` + The x-coordinate where the click occurred. - A JSON string of the output of the function tool call. + - `y: number` - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + The y-coordinate where the click occurred. - An array of content outputs (text, image, file) for the function tool call. + - `keys: optional array of string` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + The keys being held while clicking. - A text input to the model. + - `double_click: object { keys, type, x, y }` - - `text: string` + A double click action. - The text input to the model. + - `keys: array of string` - - `type: "input_text"` + The keys being held while double-clicking. - The type of the input item. Always `input_text`. + - `type: "double_click"` - - `prompt_cache_breakpoint: optional object { mode }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - 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. + - `x: number` - - `mode: "explicit"` + The x-coordinate where the double click occurred. - The breakpoint mode. Always `explicit`. + - `y: number` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + The y-coordinate where the double click occurred. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `drag: object { path, type, keys }` - - `type: "input_image"` + A drag action. - The type of the input item. Always `input_image`. + - `path: array of object { x, y }` - - `detail: optional "low" or "high" or "auto" or "original"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"low"` + - `x: number` - - `"high"` + The x-coordinate. - - `"auto"` + - `y: number` - - `"original"` + The y-coordinate. - - `file_id: optional string` + - `type: "drag"` - The ID of the file to be sent to the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `image_url: optional string` + - `keys: optional array of string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The keys being held while dragging the mouse. - - `prompt_cache_breakpoint: optional object { mode }` + - `keypress: object { keys, type }` - 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. + A collection of keypresses the model would like to perform. - - `mode: "explicit"` + - `keys: array of string` - The breakpoint mode. Always `explicit`. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `type: "keypress"` - A file input to the model. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: "input_file"` + - `move: object { type, x, y, keys }` - The type of the input item. Always `input_file`. + A mouse move action. - - `detail: optional "auto" or "low" or "high"` + - `type: "move"` - 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`. + Specifies the event type. For a move action, this property is always set to `move`. - - `"auto"` + - `x: number` - - `"low"` + The x-coordinate to move to. - - `"high"` + - `y: number` - - `file_data: optional string` + The y-coordinate to move to. - The base64-encoded data of the file to be sent to the model. + - `keys: optional array of string` - - `file_id: optional string` + The keys being held while moving the mouse. - The ID of the file to be sent to the model. + - `screenshot: object { type }` - - `file_url: optional string` + A screenshot action. - The URL of the file to be sent to the model. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `filename: optional string` + A scroll action. - The name of the file to be sent to the model. + - `scroll_x: number` - - `prompt_cache_breakpoint: optional object { mode }` + The horizontal scroll distance. - 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. + - `scroll_y: number` - - `mode: "explicit"` + The vertical scroll distance. - The breakpoint mode. Always `explicit`. + - `type: "scroll"` - - `type: "function_call_output"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The type of the function tool call output. Always `function_call_output`. + - `x: number` - - `id: optional string` + The x-coordinate where the scroll occurred. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `y: number` - - `agent: optional object { agent_name }` + The y-coordinate where the scroll occurred. - The agent that produced this item. + - `keys: optional array of string` - - `agent_name: string` + The keys being held while scrolling. - The canonical name of the agent that produced this item. + - `type: object { text, type }` - - `caller: optional object { type } or object { caller_id, type }` + An action to type in text. - The execution context that produced this tool call. + - `text: string` - - `direct: object { type }` + The text to type. - - `program: object { caller_id, type }` + - `type: "type"` - - `caller_id: string` + Specifies the event type. For a type action, this property is always set to `type`. - The call ID of the program item that produced this tool call. + - `wait: object { type }` - - `type: "program"` + A wait action. - The caller type. Always `program`. + - `actions: optional array of BetaComputerAction` - - `status: optional "in_progress" or "completed" or "incomplete"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `click: object { button, type, x, 2 more }` - - `"in_progress"` + A click action. - - `"completed"` + - `double_click: object { keys, type, x, y }` - - `"incomplete"` + A double click action. - - `agent_message: object { author, content, recipient, 3 more }` + - `drag: object { path, type, keys }` - A message routed between agents. + A drag action. - - `author: string` + - `keypress: object { keys, type }` - The sending agent identity. + A collection of keypresses the model would like to perform. - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `move: object { type, x, y, keys }` - Plaintext, image, or encrypted content sent between agents. + A mouse move action. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `screenshot: object { type }` - A text input to the model. + A screenshot action. - - `text: string` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - The text input to the model. + A scroll action. - - `type: "input_text"` + - `type: object { text, type }` - The type of the input item. Always `input_text`. + An action to type in text. - - `prompt_cache_breakpoint: optional object { mode }` + - `wait: object { type }` - 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. + A wait action. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The agent that produced this item. - - `type: "input_image"` + - `agent_name: string` - The type of the input item. Always `input_image`. + The canonical name of the agent that produced this item. - - `detail: optional "low" or "high" or "auto" or "original"` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - `file_id: optional string` - The ID of the file to be sent to the model. + The identifier of an uploaded file that contains the screenshot. - `image_url: optional string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The URL of the screenshot image. - - `prompt_cache_breakpoint: optional object { mode }` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - 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. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `encrypted_content: object { encrypted_content, type }` + - `"completed"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"incomplete"` - - `encrypted_content: string` + - `"failed"` - Opaque encrypted content. + - `"in_progress"` - - `type: "encrypted_content"` + - `type: "computer_call_output"` - The type of the input item. Always `encrypted_content`. + The type of the computer tool call output. Always `computer_call_output`. - - `recipient: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The destination agent identity. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "agent_message"` + - `id: string` - The item type. Always `agent_message`. + The ID of the pending safety check. - - `id: optional string` + - `code: optional string` - The unique ID of this agent message item. + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -85030,39 +96083,36 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. - - - `"spawn_agent"` + - `created_by: optional string` - - `"interrupt_agent"` + The identifier of the actor that created the item. - - `"list_agents"` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `"send_message"` + 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). - - `"followup_task"` + - `id: string` - - `"wait_agent"` + The unique identifier of the reasoning content. - - `arguments: string` + - `summary: array of object { text, type }` - The action arguments as a JSON string. + Reasoning summary content. - - `call_id: string` + - `text: string` - The unique ID linking this call to its output. + A summary of the reasoning output from the model so far. - - `type: "multi_agent_call"` + - `type: "summary_text"` - The item type. Always `multi_agent_call`. + The type of the object. Always `summary_text`. - - `id: optional string` + - `type: "reasoning"` - The unique ID of this multi-agent call. + The type of the object. Always `reasoning`. - `agent: optional object { agent_name }` @@ -85072,139 +96122,133 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. + - `content: optional array of object { text, type }` - - `"spawn_agent"` + Reasoning text content. - - `"interrupt_agent"` + - `text: string` - - `"list_agents"` + The reasoning text from the model. - - `"send_message"` + - `type: "reasoning_text"` - - `"followup_task"` + The type of the reasoning text. Always `reasoning_text`. - - `"wait_agent"` + - `encrypted_content: optional string` - - `call_id: string` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The unique ID of the multi-agent call. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `output: array of object { text, type, annotations }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Text output returned by the multi-agent action. + - `"in_progress"` - - `text: string` + - `"completed"` - The text content. + - `"incomplete"` - - `type: "output_text"` + - `program: object { id, call_id, code, 3 more }` - The content type. Always `output_text`. + - `id: string` - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + The unique ID of the program item. - Citations associated with the text content. + - `call_id: string` - - `union_member_0: array of object { file_id, filename, index, type }` + The stable call ID of the program item. - - `file_id: string` + - `code: string` - The ID of the file. + The JavaScript source executed by programmatic tool calling. - - `filename: string` + - `fingerprint: string` - The filename of the file cited. + Opaque program replay fingerprint that must be round-tripped. - - `index: number` + - `type: "program"` - The index of the file in the list of files. + The type of the item. Always `program`. - - `type: "file_citation"` + - `agent: optional object { agent_name }` - The citation type. Always `file_citation`. + The agent that produced this item. - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + - `agent_name: string` - - `end_index: number` + The canonical name of the agent that produced this item. - The index of the last character of the citation in the message. + - `program_output: object { id, call_id, result, 3 more }` - - `start_index: number` + - `id: string` - The index of the first character of the citation in the message. + The unique ID of the program output item. - - `title: string` + - `call_id: string` - The title of the cited resource. + The call ID of the program item. - - `type: "url_citation"` + - `result: string` - The citation type. Always `url_citation`. + The result produced by the program item. - - `url: string` + - `status: "completed" or "incomplete"` - The URL of the cited resource. + The terminal status of the program output item. - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + - `"completed"` - - `container_id: string` + - `"incomplete"` - The ID of the container. + - `type: "program_output"` - - `end_index: number` + The type of the item. Always `program_output`. - The index of the last character of the citation in the message. + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The ID of the container file. + - `agent_name: string` - - `filename: string` + The canonical name of the agent that produced this item. - The filename of the container file cited. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `start_index: number` + - `id: string` - The index of the first character of the citation in the message. + The unique ID of the tool search call item. - - `type: "container_file_citation"` + - `arguments: unknown` - The citation type. Always `container_file_citation`. + Arguments used for the tool search call. - - `type: "multi_agent_call_output"` + - `call_id: string` - The item type. Always `multi_agent_call_output`. + The unique ID of the tool search call generated by the model. - - `id: optional string` + - `execution: "server" or "client"` - The unique ID of this multi-agent call output. + Whether tool search was executed by the server or by the client. - - `agent: optional object { agent_name }` + - `"server"` - The agent that produced this item. + - `"client"` - - `agent_name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the tool search call item that was recorded. - - `tool_search_call: object { arguments, type, id, 4 more }` + - `"in_progress"` - - `arguments: unknown` + - `"completed"` - The arguments supplied to the tool search call. + - `"incomplete"` - `type: "tool_search_call"` - The item type. Always `tool_search_call`. - - - `id: optional string` - - The unique ID of this tool search call. + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -85214,11 +96258,21 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` The unique ID of the tool search call generated by the model. - - `execution: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -85226,9 +96280,9 @@ openai beta:responses compact \ - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -85236,11 +96290,9 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `tools: array of BetaTool` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -85335,7 +96387,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -85345,7 +96397,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -85392,7 +96448,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -85402,7 +96458,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -86274,11 +97334,7 @@ openai beta:responses compact \ - `type: "tool_search_output"` - The item type. Always `tool_search_output`. - - - `id: optional string` - - The unique ID of this tool search output. + The type of the item. Always `tool_search_output`. - `agent: optional object { agent_name }` @@ -86288,37 +97344,39 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` - The unique ID of the tool search call generated by the model. + The identifier of the actor that created the item. - - `execution: optional "server" or "client"` + - `additional_tools: object { id, role, tools, 2 more }` - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the additional tools item. - - `"client"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + The role that provided the additional tools. - The status of the tool search output. + - `"unknown"` - - `"in_progress"` + - `"user"` - - `"completed"` + - `"assistant"` - - `"incomplete"` + - `"system"` - - `additional_tools: object { role, tools, type, 2 more }` + - `"critic"` - - `role: "developer"` + - `"discriminator"` - The role that provided the additional tools. Only `developer` is supported. + - `"developer"` + + - `"tool"` - `tools: array of BetaTool` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -86386,11 +97444,7 @@ openai beta:responses compact \ - `type: "additional_tools"` - The item type. Always `additional_tools`. - - - `id: optional string` - - The unique ID of this additional tools item. + The type of the item. Always `additional_tools`. - `agent: optional object { agent_name }` @@ -86400,85 +97454,22 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: string` - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - Reasoning summary content. - - - `text: string` - - A summary of the reasoning output from the model so far. - - - `type: "summary_text"` - - The type of the object. Always `summary_text`. - - - `type: "reasoning"` - - The type of the object. Always `reasoning`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `content: optional array of object { text, type }` - - Reasoning text content. - - - `text: string` - - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - - `encrypted_content: optional string` - - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The unique ID of the compaction item. - `encrypted_content: string` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: "compaction"` The type of the item. Always `compaction`. - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -86487,6 +97478,10 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -86690,9 +97685,13 @@ openai beta:responses compact \ - `"incomplete"` - - `shell_call: object { action, call_id, type, 5 more }` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - A tool representing a request to execute one or more shell commands. + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. - `action: object { commands, max_output_length, timeout_ms }` @@ -86700,27 +97699,53 @@ openai beta:responses compact \ - `commands: array of string` - Ordered shell commands for the execution environment to run. - - - `max_output_length: optional number` + - `max_output_length: number` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - - `timeout_ms: optional number` + - `timeout_ms: number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `type: "shell_call"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The type of the item. Always `shell_call`. + Represents the use of a local environment to perform shell actions. - - `id: optional string` + - `beta_response_local_environment: object { type }` - The unique ID of the shell tool call. Populated when this item is returned via API. + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. - `agent: optional object { agent_name }` @@ -86744,41 +97769,33 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `beta_local_environment: object { type, skills }` - - - `beta_container_reference: object { container_id, type }` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: optional string` - - `"in_progress"` + The ID of the entity that created this tool call. - - `"completed"` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `"incomplete"` + The output of a shell tool call that was emitted. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `id: string` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `max_output_length: number` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents - `outcome: object { type } or object { exit_code, type }` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `timeout: object { type }` @@ -86790,7 +97807,7 @@ openai beta:responses compact \ - `exit_code: number` - The exit code returned by the shell process. + Exit code from the shell process. - `type: "exit"` @@ -86798,19 +97815,29 @@ openai beta:responses compact \ - `stderr: string` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: string` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: "shell_call_output"` + - `created_by: optional string` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `id: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. - `agent: optional object { agent_name }` @@ -86834,25 +97861,17 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `max_output_length: optional number` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` @@ -86860,51 +97879,51 @@ openai beta:responses compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `create_file: object { diff, path, type }` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: string` - Unified diff content to apply when creating the file. + Diff to apply. - `path: string` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: "create_file"` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `delete_file: object { path, type }` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: string` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: "delete_file"` - The operation type. Always `delete_file`. + Delete the specified file. - `update_file: object { diff, path, type }` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: string` - Unified diff content to apply to the existing file. + Diff to apply. - `path: string` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: "update_file"` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `status: "in_progress" or "completed"` @@ -86918,10 +97937,6 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call`. - - `id: optional string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -86944,11 +97959,17 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. + - `created_by: optional string` - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + The ID of the entity that created this tool call. - The streamed output emitted by an apply patch tool call. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: string` @@ -86966,10 +97987,6 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call_output`. - - `id: optional string` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -86992,123 +98009,13 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `output: optional string` - - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - A list of tools available on an MCP server. - - - `id: string` - - The unique ID of the list. - - - `server_label: string` - - The label of the MCP server. - - - `tools: array of object { input_schema, name, annotations, description }` - - The tools available on the server. - - - `input_schema: unknown` - - The JSON schema describing the tool's input. - - - `name: string` - - The name of the tool. - - - `annotations: optional unknown` - - Additional annotations about the tool. - - - `description: optional string` - - The description of the tool. - - - `type: "mcp_list_tools"` - - The type of the item. Always `mcp_list_tools`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `error: optional string` - - Error message if the server could not list tools. - - - `mcp_approval_request: object { id, arguments, name, 3 more }` - - A request for human approval of a tool invocation. - - - `id: string` - - The unique ID of the approval request. - - - `arguments: string` - - A JSON string of arguments for the tool. - - - `name: string` - - The name of the tool to run. - - - `server_label: string` - - The label of the MCP server making the request. - - - `type: "mcp_approval_request"` - - The type of the item. Always `mcp_approval_request`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - - A response to an MCP approval request. - - - `approval_request_id: string` - - The ID of the approval request being answered. - - - `approve: boolean` - - Whether the request was approved. - - - `type: "mcp_approval_response"` - - The type of the item. Always `mcp_approval_response`. - - - `id: optional string` - - The unique ID of the approval response - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` + - `created_by: optional string` - The canonical name of the agent that produced this item. + The ID of the entity that created this tool call output. - - `reason: optional string` + - `output: optional string` - Optional reason for the decision. + Optional textual output returned by the apply patch tool. - `mcp_call: object { id, arguments, name, 7 more }` @@ -87169,106 +98076,105 @@ openai beta:responses compact \ - `"failed"` - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The output of a custom tool call from your code, being sent back to the model. + A list of tools available on an MCP server. - - `call_id: string` + - `id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the list. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `server_label: string` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The label of the MCP server. - - `string output: string` + - `tools: array of object { input_schema, name, annotations, description }` - A string of the output of the custom tool call. + The tools available on the server. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `input_schema: unknown` - Text, image, or file output of the custom tool call. + The JSON schema describing the tool's input. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `name: string` - A text input to the model. + The name of the tool. - - `text: string` + - `annotations: optional unknown` - The text input to the model. + Additional annotations about the tool. - - `type: "input_text"` + - `description: optional string` - The type of the input item. Always `input_text`. + The description of the tool. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "mcp_list_tools"` - 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. + The type of the item. Always `mcp_list_tools`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `agent: optional object { agent_name }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The agent that produced this item. - - `detail: "low" or "high" or "auto" or "original"` + - `agent_name: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The canonical name of the agent that produced this item. - - `type: "input_image"` + - `error: optional string` - The type of the input item. Always `input_image`. + Error message if the server could not list tools. - - `file_id: optional string` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - The ID of the file to be sent to the model. + A request for human approval of a tool invocation. - - `image_url: optional string` + - `id: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The unique ID of the approval request. - - `prompt_cache_breakpoint: optional object { mode }` + - `arguments: string` - 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. + A JSON string of arguments for the tool. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `name: string` - A file input to the model. + The name of the tool to run. - - `type: "input_file"` + - `server_label: string` - The type of the input item. Always `input_file`. + The label of the MCP server making the request. - - `detail: optional "auto" or "low" or "high"` + - `type: "mcp_approval_request"` - 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`. + The type of the item. Always `mcp_approval_request`. - - `file_data: optional string` + - `agent: optional object { agent_name }` - The content of the file to be sent to the model. + The agent that produced this item. - - `file_id: optional string` + - `agent_name: string` - The ID of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_url: optional string` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - The URL of the file to be sent to the model. + A response to an MCP approval request. - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique ID of the approval response - - `prompt_cache_breakpoint: optional object { mode }` + - `approval_request_id: string` - 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. + The ID of the approval request being answered. - - `type: "custom_tool_call_output"` + - `approve: boolean` - The type of the custom tool call output. Always `custom_tool_call_output`. + Whether the request was approved. - - `id: optional string` + - `type: "mcp_approval_response"` - The unique ID of the custom tool call output in the OpenAI platform. + The type of the item. Always `mcp_approval_response`. - `agent: optional object { agent_name }` @@ -87278,21 +98184,9 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` + - `reason: optional string` - The caller type. Always `program`. + Optional reason for the decision. - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` @@ -87344,99 +98238,213 @@ openai beta:responses compact \ The namespace of the custom tool being called. - - `compaction_trigger: object { type, agent }` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - Compacts the current context. Must be the final input item. + The output of a custom tool call from your code, being sent back to the model. - - `type: "compaction_trigger"` + - `id: string` - The type of the item. Always `compaction_trigger`. + The unique ID of the custom tool call output item. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `output_index: number` + + The index of the output item that was marked done. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.output_item.done"` + + The type of the event. Always `response.output_item.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `item_reference: object { id, agent, type }` +### Beta Response Output Message - An internal identifier for an item to reference. +- `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. - `id: string` - The ID of the item to reference. + The unique ID of the output message. - - `agent: optional object { agent_name }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The agent that produced this item. + The content of the output message. - - `agent_name: string` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - The canonical name of the agent that produced this item. + A text output from the model. - - `type: optional "item_reference"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The type of item to reference. Always `item_reference`. + The annotations of the text output. - - `"item_reference"` + - `file_citation: object { file_id, filename, index, type }` - - `program: object { id, call_id, code, 3 more }` + A citation to a file. - - `id: string` + - `file_id: string` - The unique ID of this program item. + The ID of the file. - - `call_id: string` + - `filename: string` - The stable call ID of the program item. + The filename of the file cited. - - `code: string` + - `index: number` - The JavaScript source executed by programmatic tool calling. + The index of the file in the list of files. - - `fingerprint: string` + - `type: "file_citation"` - Opaque program replay fingerprint that must be round-tripped. + The type of the file citation. Always `file_citation`. - - `type: "program"` + - `url_citation: object { end_index, start_index, title, 2 more }` - The item type. Always `program`. + A citation for a web resource used to generate a model response. - - `agent: optional object { agent_name }` + - `end_index: number` - The agent that produced this item. + The index of the last character of the URL citation in the message. - - `agent_name: string` + - `start_index: number` - The canonical name of the agent that produced this item. + The index of the first character of the URL citation in the message. - - `program_output: object { id, call_id, result, 3 more }` + - `title: string` - - `id: string` + The title of the web resource. - The unique ID of this program output item. + - `type: "url_citation"` - - `call_id: string` + The type of the URL citation. Always `url_citation`. - The call ID of the program item. + - `url: string` - - `result: string` + The URL of the web resource. - The result produced by the program item. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `status: "completed" or "incomplete"` + A citation for a container file used to generate a model response. - The terminal status of the program output. + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `file_path: object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `beta_response_output_refusal: object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` + - `type: "message"` - The item type. Always `program_output`. + The type of the output message. Always `message`. - `agent: optional object { agent_name }` @@ -87446,214 +98454,224 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Input Audio + - `phase: optional "commentary" or "final_answer"` -- `beta_response_input_audio: object { input_audio, type }` + 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. - An audio input to the model. + - `"commentary"` - - `input_audio: object { data, format }` + - `"final_answer"` - - `data: string` +### Beta Response Output Refusal - Base64-encoded audio data. +- `beta_response_output_refusal: object { refusal, type }` - - `format: "mp3" or "wav"` + A refusal from the model. - The format of the audio data. Currently supported formats are `mp3` and - `wav`. + - `refusal: string` - - `"mp3"` + The refusal explanation from the model. - - `"wav"` + - `type: "refusal"` - - `type: "input_audio"` + The type of the refusal. Always `refusal`. - The type of the input item. Always `input_audio`. +### Beta Response Output Text -### Beta Response Input Content +- `beta_response_output_text: object { annotations, text, type, logprobs }` -- `beta_response_input_content: BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A text output from the model. - A text input to the model. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The annotations of the text output. - A text input to the model. + - `file_citation: object { file_id, filename, index, type }` - - `text: string` + A citation to a file. - The text input to the model. + - `file_id: string` - - `type: "input_text"` + The ID of the file. - The type of the input item. Always `input_text`. + - `filename: string` - - `prompt_cache_breakpoint: optional object { mode }` + The filename of the file cited. - 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. + - `index: number` - - `mode: "explicit"` + The index of the file in the list of files. - The breakpoint mode. Always `explicit`. + - `type: "file_citation"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The type of the file citation. Always `file_citation`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `url_citation: object { end_index, start_index, title, 2 more }` - - `detail: "low" or "high" or "auto" or "original"` + A citation for a web resource used to generate a model response. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `end_index: number` - - `"low"` + The index of the last character of the URL citation in the message. - - `"high"` + - `start_index: number` - - `"auto"` + The index of the first character of the URL citation in the message. - - `"original"` + - `title: string` - - `type: "input_image"` + The title of the web resource. - The type of the input item. Always `input_image`. + - `type: "url_citation"` - - `file_id: optional string` + The type of the URL citation. Always `url_citation`. - The ID of the file to be sent to the model. + - `url: string` - - `image_url: optional string` + The URL of the web resource. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `prompt_cache_breakpoint: optional object { mode }` + A citation for a container file used to generate a model response. - 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. + - `container_id: string` - - `mode: "explicit"` + The ID of the container file. - The breakpoint mode. Always `explicit`. + - `end_index: number` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The index of the last character of the container file citation in the message. - A file input to the model. + - `file_id: string` - - `type: "input_file"` + The ID of the file. - The type of the input item. Always `input_file`. + - `filename: string` - - `detail: optional "auto" or "low" or "high"` + The filename of the container file cited. - 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`. + - `start_index: number` - - `"auto"` + The index of the first character of the container file citation in the message. - - `"low"` + - `type: "container_file_citation"` - - `"high"` + The type of the container file citation. Always `container_file_citation`. - - `file_data: optional string` + - `file_path: object { file_id, index, type }` - The content of the file to be sent to the model. + A path to a file. - - `file_id: optional string` + - `file_id: string` - The ID of the file to be sent to the model. + The ID of the file. - - `file_url: optional string` + - `index: number` - The URL of the file to be sent to the model. + The index of the file in the list of files. - - `filename: optional string` + - `type: "file_path"` - The name of the file to be sent to the model. + The type of the file path. Always `file_path`. - - `prompt_cache_breakpoint: optional object { mode }` + - `text: string` - 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. + The text output from the model. - - `mode: "explicit"` + - `type: "output_text"` - The breakpoint mode. Always `explicit`. + The type of the output text. Always `output_text`. -### Beta Response Input File + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` -- `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `token: string` - A file input to the model. + - `bytes: array of number` - - `type: "input_file"` + - `logprob: number` - The type of the input item. Always `input_file`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `detail: optional "auto" or "low" or "high"` + - `token: string` - 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`. + - `bytes: array of number` - - `"auto"` + - `logprob: number` - - `"low"` +### Beta Response Output Text Annotation Added Event - - `"high"` +- `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` - - `file_data: optional string` + Emitted when an annotation is added to output text content. - The content of the file to be sent to the model. + - `annotation: unknown` - - `file_id: optional string` + The annotation object being added. (See annotation schema for details.) - The ID of the file to be sent to the model. + - `annotation_index: number` - - `file_url: optional string` + The index of the annotation within the content part. - The URL of the file to be sent to the model. + - `content_index: number` - - `filename: optional string` + The index of the content part within the output item. - The name of the file to be sent to the model. + - `item_id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique identifier of the item to which the annotation is being added. - 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. + - `output_index: number` - - `mode: "explicit"` + The index of the output item in the response's output array. - The breakpoint mode. Always `explicit`. + - `sequence_number: number` -### Beta Response Input File Content + The sequence number of this event. -- `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `type: "response.output_text.annotation.added"` - A file input to the model. + The type of the event. Always 'response.output_text.annotation.added'. - - `type: "input_file"` + - `agent: optional object { agent_name }` - The type of the input item. Always `input_file`. + The agent that owns this multi-agent streaming event. - - `detail: optional "auto" or "low" or "high"` + - `agent_name: string` - 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`. + The canonical name of the agent that produced this item. - - `"auto"` +### Beta Response Prompt - - `"low"` +- `beta_response_prompt: object { id, variables, version }` - - `"high"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `file_data: optional string` + - `id: string` - The base64-encoded data of the file to be sent to the model. + The unique identifier of the prompt template to use. - - `file_id: optional string` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - The ID of the file to be sent to the model. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `file_url: optional string` + - `union_member_0: string` - The URL of the file to be sent to the model. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `filename: optional string` + A text input to the model. - The name of the file to be sent to the model. + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. - `prompt_cache_breakpoint: optional object { mode }` @@ -87663,9 +98681,7 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. -### Beta Response Input Image - -- `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -87701,35 +98717,39 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. -### Beta Response Input Image Content + - `beta_response_input_file: object { type, detail, file_data, 4 more }` -- `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + A file input to the model. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `type: "input_file"` - - `type: "input_image"` + The type of the input item. Always `input_file`. - The type of the input item. Always `input_image`. + - `detail: optional "auto" or "low" or "high"` - - `detail: optional "low" or "high" or "auto" or "original"` + 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`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"auto"` - `"low"` - `"high"` - - `"auto"` + - `file_data: optional string` - - `"original"` + The content of the file to be sent to the model. - `file_id: optional string` The ID of the file to be sent to the model. - - `image_url: optional string` + - `file_url: optional string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. - `prompt_cache_breakpoint: optional object { mode }` @@ -87739,15 +98759,107 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. -### Beta Response Input Item + - `version: optional string` -- `beta_response_input_item: BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + Optional version of the prompt template. - 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. +### Beta Response Queued Event + +- `beta_response_queued_event: object { response, sequence_number, type, agent }` + + Emitted when a response is queued and waiting to be processed. + + - `response: object { id, created_at, error, 31 more }` + + The full response object that is queued. + + - `id: string` + + Unique identifier for this Response. + + - `created_at: number` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: object { code, message }` + + An error object returned when the model fails to generate a Response. + + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"bio_policy"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `message: string` + + A human-readable description of the error. + + - `incomplete_details: object { reason }` + + Details about why the response is incomplete. + + - `reason: optional "max_output_tokens" or "content_filter"` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: string or array of BetaResponseInputItem` + + A system (or developer) message inserted into the model's context. + + When using 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. + + - `union_member_0: string` + + A text input to the model, equivalent to a text input with the + `developer` role. + + - `Input item list: array of BetaResponseInputItem` + + A list of one or many input items to the model, containing + different content types. - `beta_easy_input_message: object { content, role, phase, type }` @@ -87882,7 +98994,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -87890,6 +99002,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -88125,7 +99239,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -88133,6 +99247,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -89243,7 +100359,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -89253,7 +100369,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -89300,7 +100420,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -89310,7 +100430,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -91354,1155 +102478,334 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Input Message Content List - -- `beta_response_input_message_content_list: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - -### Beta Response Input Message Item - -- `beta_response_input_message_item: object { id, content, role, 3 more }` - - - `id: string` - - The unique ID of the message input. - - - `content: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `role: "user" or "system" or "developer"` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `"user"` - - - `"system"` - - - `"developer"` - - - `type: "message"` - - The type of the message input. Always set to `message`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - -### Beta Response Input Text - -- `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - -### Beta Response Input Text Content - -- `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - -### Beta Response Item - -- `beta_response_item: BetaResponseInputMessageItem or BetaResponseOutputMessage or BetaResponseFileSearchToolCall or 29 more` - - Content item used to generate a response. - - - `beta_response_input_message_item: object { id, content, role, 3 more }` - - - `id: string` - - The unique ID of the message input. - - - `content: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `role: "user" or "system" or "developer"` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `"user"` - - - `"system"` - - - `"developer"` - - - `type: "message"` - - The type of the message input. Always set to `message`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `beta_response_output_message: object { id, content, role, 4 more }` - - An output message from the model. - - - `id: string` - - The unique ID of the output message. - - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - The content of the output message. - - - `beta_response_output_text: object { annotations, text, type, logprobs }` - - A text output from the model. - - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - The annotations of the text output. - - - `file_citation: object { file_id, filename, index, type }` - - A citation to a file. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the file cited. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_citation"` - - The type of the file citation. Always `file_citation`. - - - `url_citation: object { end_index, start_index, title, 2 more }` - - A citation for a web resource used to generate a model response. - - - `end_index: number` - - The index of the last character of the URL citation in the message. - - - `start_index: number` - - The index of the first character of the URL citation in the message. - - - `title: string` - - The title of the web resource. - - - `type: "url_citation"` - - The type of the URL citation. Always `url_citation`. - - - `url: string` - - The URL of the web resource. - - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - A citation for a container file used to generate a model response. - - - `container_id: string` - - The ID of the container file. - - - `end_index: number` - - The index of the last character of the container file citation in the message. - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the container file cited. - - - `start_index: number` - - The index of the first character of the container file citation in the message. - - - `type: "container_file_citation"` - - The type of the container file citation. Always `container_file_citation`. - - - `file_path: object { file_id, index, type }` - - A path to a file. - - - `file_id: string` - - The ID of the file. - - - `index: number` - - The index of the file in the list of files. - - - `type: "file_path"` - - The type of the file path. Always `file_path`. - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - - `token: string` - - - `bytes: array of number` - - - `logprob: number` - - - `top_logprobs: array of object { token, bytes, logprob }` - - - `token: string` - - - `bytes: array of number` - - - `logprob: number` - - - `beta_response_output_refusal: object { refusal, type }` - - A refusal from the model. - - - `refusal: string` - - The refusal explanation from the model. - - - `type: "refusal"` - - The type of the refusal. Always `refusal`. - - - `role: "assistant"` - - The role of the output message. Always `assistant`. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: "message"` - - The type of the output message. Always `message`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `phase: optional "commentary"` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` - - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - - `id: string` - - The unique ID of the file search tool call. - - - `queries: array of string` - - The queries used to search for files. - - - `status: "in_progress" or "searching" or "completed" or 2 more` - - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, - - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - - `"incomplete"` - - - `"failed"` - - - `type: "file_search_call"` - - The type of the file search tool call. Always `file_search_call`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. - - - `attributes: optional map[string or number or boolean]` + - `metadata: map[string]` 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. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `file_id: optional string` - - The unique ID of the file. - - - `filename: optional string` - - The name of the file. - - - `score: optional number` - - The relevance score of the file - a value between 0 and 1. - - - `text: optional string` - - The text that was retrieved from the file. - - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - - `id: string` - - The unique ID of the computer call. - - - `call_id: string` - - An identifier used when responding to the tool call with output. - - - `pending_safety_checks: array of object { id, code, message }` - - The pending safety checks for the computer call. - - - `id: string` - - The ID of the pending safety check. - - - `code: optional string` - - The type of the pending safety check. - - - `message: optional string` - - Details about the pending safety check. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: "computer_call"` - - The type of the computer call. Always `computer_call`. - - - `"computer_call"` - - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - A click action. - - - `click: object { button, type, x, 2 more }` - - A click action. - - - `button: "left" or "right" or "wheel" or 2 more` - - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - - `"left"` - - - `"right"` - - - `"wheel"` - - - `"back"` - - - `"forward"` - - - `type: "click"` - - Specifies the event type. For a click action, this property is always `click`. - - - `x: number` - - The x-coordinate where the click occurred. - - - `y: number` - - The y-coordinate where the click occurred. - - - `keys: optional array of string` - - The keys being held while clicking. - - - `double_click: object { keys, type, x, y }` - - A double click action. - - - `keys: array of string` - - The keys being held while double-clicking. - - - `type: "double_click"` - - Specifies the event type. For a double click action, this property is always set to `double_click`. - - - `x: number` - - The x-coordinate where the double click occurred. - - - `y: number` - - The y-coordinate where the double click occurred. - - - `drag: object { path, type, keys }` - - A drag action. - - - `path: array of object { x, y }` - - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` - - - `x: number` - - The x-coordinate. - - - `y: number` - - The y-coordinate. + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `type: "drag"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `keys: optional array of string` + Model ID used to generate the response, like `gpt-4o` 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. - The keys being held while dragging the mouse. + - `"gpt-5.6-sol"` - - `keypress: object { keys, type }` + - `"gpt-5.6-terra"` - A collection of keypresses the model would like to perform. + - `"gpt-5.6-luna"` - - `keys: array of string` + - `"gpt-5.4"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"gpt-5.4-mini"` - - `type: "keypress"` + - `"gpt-5.4-nano"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"gpt-5.4-mini-2026-03-17"` - - `move: object { type, x, y, keys }` + - `"gpt-5.4-nano-2026-03-17"` - A mouse move action. + - `"gpt-5.3-chat-latest"` - - `type: "move"` + - `"gpt-5.2"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"gpt-5.2-2025-12-11"` - - `x: number` + - `"gpt-5.2-chat-latest"` - The x-coordinate to move to. + - `"gpt-5.2-pro"` - - `y: number` + - `"gpt-5.2-pro-2025-12-11"` - The y-coordinate to move to. + - `"gpt-5.1"` - - `keys: optional array of string` + - `"gpt-5.1-2025-11-13"` - The keys being held while moving the mouse. + - `"gpt-5.1-codex"` - - `screenshot: object { type }` + - `"gpt-5.1-mini"` - A screenshot action. + - `"gpt-5.1-chat-latest"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"gpt-5"` - A scroll action. + - `"gpt-5-mini"` - - `scroll_x: number` + - `"gpt-5-nano"` - The horizontal scroll distance. + - `"gpt-5-2025-08-07"` - - `scroll_y: number` + - `"gpt-5-mini-2025-08-07"` - The vertical scroll distance. + - `"gpt-5-nano-2025-08-07"` - - `type: "scroll"` + - `"gpt-5-chat-latest"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"gpt-4.1"` - - `x: number` + - `"gpt-4.1-mini"` - The x-coordinate where the scroll occurred. + - `"gpt-4.1-nano"` - - `y: number` + - `"gpt-4.1-2025-04-14"` - The y-coordinate where the scroll occurred. + - `"gpt-4.1-mini-2025-04-14"` - - `keys: optional array of string` + - `"gpt-4.1-nano-2025-04-14"` - The keys being held while scrolling. + - `"o4-mini"` - - `type: object { text, type }` + - `"o4-mini-2025-04-16"` - An action to type in text. + - `"o3"` - - `text: string` + - `"o3-2025-04-16"` - The text to type. + - `"o3-mini"` - - `type: "type"` + - `"o3-mini-2025-01-31"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"o1"` - - `wait: object { type }` + - `"o1-2024-12-17"` - A wait action. + - `"o1-preview"` - - `actions: optional array of BetaComputerAction` + - `"o1-preview-2024-09-12"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"o1-mini"` - - `click: object { button, type, x, 2 more }` + - `"o1-mini-2024-09-12"` - A click action. + - `"gpt-4o"` - - `double_click: object { keys, type, x, y }` + - `"gpt-4o-2024-11-20"` - A double click action. + - `"gpt-4o-2024-08-06"` - - `drag: object { path, type, keys }` + - `"gpt-4o-2024-05-13"` - A drag action. + - `"gpt-4o-audio-preview"` - - `keypress: object { keys, type }` + - `"gpt-4o-audio-preview-2024-10-01"` - A collection of keypresses the model would like to perform. + - `"gpt-4o-audio-preview-2024-12-17"` - - `move: object { type, x, y, keys }` + - `"gpt-4o-audio-preview-2025-06-03"` - A mouse move action. + - `"gpt-4o-mini-audio-preview"` - - `screenshot: object { type }` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - A screenshot action. + - `"gpt-4o-search-preview"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"gpt-4o-mini-search-preview"` - A scroll action. + - `"gpt-4o-search-preview-2025-03-11"` - - `type: object { text, type }` + - `"gpt-4o-mini-search-preview-2025-03-11"` - An action to type in text. + - `"chatgpt-4o-latest"` - - `wait: object { type }` + - `"codex-mini-latest"` - A wait action. + - `"gpt-4o-mini"` - - `agent: optional object { agent_name }` + - `"gpt-4o-mini-2024-07-18"` - The agent that produced this item. + - `"gpt-4-turbo"` - - `agent_name: string` + - `"gpt-4-turbo-2024-04-09"` - The canonical name of the agent that produced this item. + - `"gpt-4-0125-preview"` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `"gpt-4-turbo-preview"` - - `id: string` + - `"gpt-4-1106-preview"` - The unique ID of the computer call tool output. + - `"gpt-4-vision-preview"` - - `call_id: string` + - `"gpt-4"` - The ID of the computer tool call that produced the output. + - `"gpt-4-0314"` - - `output: object { type, file_id, image_url }` + - `"gpt-4-0613"` - A computer screenshot image used with the computer use tool. + - `"gpt-4-32k"` - - `type: "computer_screenshot"` + - `"gpt-4-32k-0314"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"gpt-4-32k-0613"` - - `file_id: optional string` + - `"gpt-3.5-turbo"` - The identifier of an uploaded file that contains the screenshot. + - `"gpt-3.5-turbo-16k"` - - `image_url: optional string` + - `"gpt-3.5-turbo-0301"` - The URL of the screenshot image. + - `"gpt-3.5-turbo-0613"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `"gpt-3.5-turbo-1106"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"gpt-3.5-turbo-0125"` - - `"completed"` + - `"gpt-3.5-turbo-16k-0613"` - - `"incomplete"` + - `"o1-pro"` - - `"failed"` + - `"o1-pro-2025-03-19"` - - `"in_progress"` + - `"o3-pro"` - - `type: "computer_call_output"` + - `"o3-pro-2025-06-10"` - The type of the computer tool call output. Always `computer_call_output`. + - `"o3-deep-research"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"o3-deep-research-2025-06-26"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `"o4-mini-deep-research"` - - `id: string` + - `"o4-mini-deep-research-2025-06-26"` - The ID of the pending safety check. + - `"computer-use-preview"` - - `code: optional string` + - `"computer-use-preview-2025-03-11"` - The type of the pending safety check. + - `"gpt-5-codex"` - - `message: optional string` + - `"gpt-5-pro"` - Details about the pending safety check. + - `"gpt-5-pro-2025-10-06"` - - `agent: optional object { agent_name }` + - `"gpt-5.1-codex-max"` - The agent that produced this item. + - `object: "response"` - - `agent_name: string` + The object type of this resource - always set to `response`. - The canonical name of the agent that produced this item. + - `output: array of BetaResponseOutputItem` - - `created_by: optional string` + An array of content items generated by the model. - The identifier of the actor that created the item. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `beta_response_output_message: object { id, content, role, 4 more }` - 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. + An output message from the model. - `id: string` - The unique ID of the web search tool call. + The unique ID of the output message. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - 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). + The content of the output message. - - `search: object { type, queries, query, sources }` + - `role: "assistant"` - Action type "search" - Performs a web search query. + The role of the output message. Always `assistant`. - - `type: "search"` + - `status: "in_progress" or "completed" or "incomplete"` - The action type. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `queries: optional array of string` + - `type: "message"` - The search queries. + The type of the output message. Always `message`. - - `query: optional string` + - `agent: optional object { agent_name }` - The search query. + The agent that produced this item. - - `sources: optional array of object { type, url }` + - `phase: optional "commentary" or "final_answer"` - The sources used in the search. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `type: "url"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The type of source. Always `url`. + 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. - - `url: string` + - `id: string` - The URL of the source. + The unique ID of the file search tool call. - - `open_page: object { type, url }` + - `queries: array of string` - Action type "open_page" - Opens a specific URL from search results. + The queries used to search for files. - - `type: "open_page"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The action type. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `url: optional string` + - `type: "file_search_call"` - The URL opened by the model. + The type of the file search tool call. Always `file_search_call`. - - `find_in_page: object { pattern, type, url }` + - `agent: optional object { agent_name }` - Action type "find_in_page": Searches for a pattern within a loaded page. + The agent that produced this item. - - `pattern: string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The pattern or text to search for within the page. + The results of the file search tool call. - - `type: "find_in_page"` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The action type. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `url: string` + - `arguments: string` - The URL of the page searched for the pattern. + A JSON string of the arguments to pass to the function. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `call_id: string` - The status of the web search tool call. + The unique ID of the function tool call generated by the model. - - `"in_progress"` + - `name: string` - - `"searching"` + The name of the function to run. - - `"completed"` + - `type: "function_call"` - - `"failed"` + The type of the function tool call. Always `function_call`. - - `type: "web_search_call"` + - `id: optional string` - The type of the web search tool call. Always `web_search_call`. + The unique ID of the function tool call. - `agent: optional object { agent_name }` The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` + - `caller: optional object { type } or object { caller_id, type }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The execution context that produced this tool call. - - `id: string` + - `namespace: optional string` - The unique ID of the function tool call. + The namespace of the function to run. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `created_by: optional string` - - The identifier of the actor that created the item. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - `id: string` @@ -92530,74 +102833,14 @@ openai beta:responses compact \ A text input to the model. - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `file_data: optional string` - - The content of the file to be sent to the model. - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `file_url: optional string` - - The URL of the file to be sent to the model. - - - `filename: optional string` - - The name of the file to be sent to the model. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or @@ -92869,6 +103112,245 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. + - `beta_response_function_web_search: object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `actions: optional array of BetaComputerAction` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: object { type, file_id, image_url }` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - `id: string` @@ -92953,1407 +103435,1723 @@ openai beta:responses compact \ Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `name: string` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The name of the function to call. + 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). - - `parameters: map[unknown]` + - `beta_computer_tool: object { type }` - A JSON schema object describing the parameters of the function. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `strict: boolean` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - Whether strict parameter validation is enforced for this function tool. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "function"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the function tool. Always `function`. + 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). - - `allowed_callers: optional array of "direct" or "programmatic"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The tool invocation context(s). + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"direct"` + - `code_interpreter: object { container, type, allowed_callers }` - - `"programmatic"` + A tool that runs Python code to help generate a response to a prompt. - - `defer_loading: optional boolean` + - `programmatic_tool_calling: object { type }` - Whether this function is deferred and loaded via tool search. + - `image_generation: object { type, action, background, 9 more }` - - `description: optional string` + A tool that generates images using the GPT image models. - A description of the function. Used by the model to determine whether or not to call the function. + - `local_shell: object { type }` - - `output_schema: optional map[unknown]` + A tool that allows the model to execute shell commands in a local environment. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "tool_search_output"` + + The type of the item. Always `tool_search_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `additional_tools: object { id, role, tools, 2 more }` + + - `id: string` + + The unique ID of the additional tools item. + + - `role: "unknown" or "user" or "assistant" or 5 more` + + The role that provided the additional tools. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `tools: array of BetaTool` + + The additional tool definitions made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "file_search"` + - `beta_computer_tool: object { type }` - The type of the file search tool. Always `file_search`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `vector_store_ids: array of string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The IDs of the vector stores to search. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `filters: optional object { key, type, value } or object { filters, type }` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - A filter to apply. + 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). - - `Comparison Filter: object { key, type, value }` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `key: string` + - `code_interpreter: object { container, type, allowed_callers }` - The key to compare against the value. + A tool that runs Python code to help generate a response to a prompt. - - `type: "eq" or "ne" or "gt" or 5 more` + - `programmatic_tool_calling: object { type }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `image_generation: object { type, action, background, 9 more }` - - `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 + A tool that generates images using the GPT image models. - - `"eq"` + - `local_shell: object { type }` - - `"ne"` + A tool that allows the model to execute shell commands in a local environment. - - `"gt"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"gte"` + A tool that allows the model to execute shell commands. - - `"lt"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"lte"` + 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) - - `"in"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `"nin"` + Groups function/custom tools under a shared namespace. - - `value: string or number or boolean or array of unknown` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The value to compare against the attribute key; supports string, number, or boolean types. + Hosted or BYOT tool search configuration for deferred tools. - - `union_member_0: string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `union_member_1: number` + 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). - - `union_member_2: boolean` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `union_member_3: array of unknown` + Allows the assistant to create, delete, or update files using unified diffs. - - `Compound Filter: object { filters, type }` + - `type: "additional_tools"` - Combine multiple filters using `and` or `or`. + The type of the item. Always `additional_tools`. - - `filters: array of object { key, type, value } or unknown` + - `agent: optional object { agent_name }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The agent that produced this item. - - `Comparison Filter: object { key, type, value }` + - `agent_name: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The canonical name of the agent that produced this item. - - `key: string` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - The key to compare against the value. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` - - `type: "eq" or "ne" or "gt" or 5 more` + - `max_output_length: number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Optional maximum number of characters to return from each command. - - `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 + - `timeout_ms: number` - - `"eq"` + Optional timeout in milliseconds for the commands. - - `"ne"` + - `call_id: string` - - `"gt"` + The unique ID of the shell tool call generated by the model. - - `"gte"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `"lt"` + Represents the use of a local environment to perform shell actions. - - `"lte"` + - `beta_response_local_environment: object { type }` - - `"in"` + Represents the use of a local environment to perform shell actions. - - `"nin"` + - `type: "local"` - - `value: string or number or boolean or array of unknown` + The environment type. Always `local`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `beta_response_container_reference: object { container_id, type }` - - `union_member_0: string` + Represents a container created with /v1/containers. - - `union_member_1: number` + - `container_id: string` - - `union_member_2: boolean` + - `type: "container_reference"` - - `union_member_3: array of unknown` + The environment type. Always `container_reference`. - - `union_member_1: unknown` + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "and" or "or"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Type of operation: `and` or `or`. + - `"in_progress"` - - `"and"` + - `"completed"` - - `"or"` + - `"incomplete"` - - `max_num_results: optional number` + - `type: "shell_call"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The type of the item. Always `shell_call`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `agent: optional object { agent_name }` - Ranking options for search. + The agent that produced this item. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `agent_name: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The canonical name of the agent that produced this item. - - `embedding_weight: number` + - `caller: optional object { type } or object { caller_id, type }` - The weight of the embedding in the reciprocal ranking fusion. + The execution context that produced this tool call. - - `text_weight: number` + - `direct: object { type }` - The weight of the text in the reciprocal ranking fusion. + - `program: object { caller_id, type }` - - `ranker: optional "auto" or "default-2024-11-15"` + - `caller_id: string` - The ranker to use for the file search. + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `"default-2024-11-15"` + - `created_by: optional string` - - `score_threshold: optional number` + The ID of the entity that created this tool call. - 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. + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `beta_computer_tool: object { type }` + The output of a shell tool call that was emitted. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `id: string` - - `type: "computer"` + The unique ID of the shell call output. Populated when this item is returned via API. - The type of the computer tool. Always `computer`. + - `call_id: string` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The unique ID of the shell tool call generated by the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `max_output_length: number` - - `display_height: number` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The height of the computer display. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `display_width: number` + An array of shell call output contents - The width of the computer display. + - `outcome: object { type } or object { exit_code, type }` - - `environment: "windows" or "mac" or "linux" or 2 more` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The type of computer environment to control. + - `timeout: object { type }` - - `"windows"` + Indicates that the shell call exceeded its configured time limit. - - `"mac"` + - `exit: object { exit_code, type }` - - `"linux"` + Indicates that the shell commands finished and returned an exit code. - - `"ubuntu"` + - `exit_code: number` - - `"browser"` + Exit code from the shell process. - - `type: "computer_use_preview"` + - `type: "exit"` - The type of the computer use tool. Always `computer_use_preview`. + The outcome type. Always `exit`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `stderr: string` - 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). + The standard error output that was captured. - - `type: "web_search" or "web_search_2025_08_26"` + - `stdout: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The standard output that was captured. - - `"web_search"` + - `created_by: optional string` - - `"web_search_2025_08_26"` + The identifier of the actor that created the item. - - `filters: optional object { allowed_domains }` + - `status: "in_progress" or "completed" or "incomplete"` - Filters for the search. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `allowed_domains: optional array of string` + - `"in_progress"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"completed"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"incomplete"` - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "shell_call_output"` - 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. + The type of the shell call output. Always `shell_call_output`. - - `"low"` + - `agent: optional object { agent_name }` - - `"medium"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `user_location: optional object { city, country, region, 2 more }` + The canonical name of the agent that produced this item. - The approximate location of the user. + - `caller: optional object { type } or object { caller_id, type }` - - `city: optional string` + The execution context that produced this tool call. - Free text input for the city of the user, e.g. `San Francisco`. + - `direct: object { type }` - - `country: optional string` + - `program: object { caller_id, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `caller_id: string` - - `region: optional string` + The call ID of the program item that produced this tool call. - Free text input for the region of the user, e.g. `California`. + - `type: "program"` - - `timezone: optional string` + - `created_by: optional string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The identifier of the actor that created the item. - - `type: optional "approximate"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - The type of location approximation. Always `approximate`. + A tool call that applies file diffs by creating, deleting, or updating files. - - `"approximate"` + - `id: string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `call_id: string` - - `server_label: string` + The unique ID of the apply patch tool call generated by the model. - A label for this MCP server, used to identify it in tool calls. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `type: "mcp"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The type of the MCP tool. Always `mcp`. + - `create_file: object { diff, path, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Instruction describing how to create a file via the apply_patch tool. - The tool invocation context(s). + - `diff: string` - - `"direct"` + Diff to apply. - - `"programmatic"` + - `path: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + Path of the file to create. - List of allowed tool names or a filter object. + - `type: "create_file"` - - `MCP allowed tools: array of string` + Create a new file with the provided diff. - A string array of allowed tool names + - `delete_file: object { path, type }` - - `MCP tool filter: object { read_only, tool_names }` + Instruction describing how to delete a file via the apply_patch tool. - A filter object to specify which tools are allowed. + - `path: string` - - `read_only: optional boolean` + Path of the file to delete. - 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. + - `type: "delete_file"` - - `tool_names: optional array of string` + Delete the specified file. - List of allowed tool names. + - `update_file: object { diff, path, type }` - - `authorization: optional string` + Instruction describing how to update a file via the apply_patch tool. - 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. + - `diff: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + Diff to apply. - 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). + - `path: string` - Currently supported `connector_id` values are: + Path of the file to update. - - 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` + - `type: "update_file"` - - `"connector_dropbox"` + Update an existing file with the provided diff. - - `"connector_gmail"` + - `status: "in_progress" or "completed"` - - `"connector_googlecalendar"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"connector_googledrive"` + - `"in_progress"` - - `"connector_microsoftteams"` + - `"completed"` - - `"connector_outlookcalendar"` + - `type: "apply_patch_call"` - - `"connector_outlookemail"` + The type of the item. Always `apply_patch_call`. - - `"connector_sharepoint"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `agent_name: string` - - `headers: optional map[string]` + The canonical name of the agent that produced this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `caller: optional object { type } or object { caller_id, type }` - - `require_approval: optional object { always, never } or "always" or "never"` + The execution context that produced this tool call. - Specify which of the MCP server's tools require approval. + - `direct: object { type }` - - `MCP tool approval filter: object { always, never }` + - `program: object { caller_id, type }` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `caller_id: string` - - `always: optional object { read_only, tool_names }` + The call ID of the program item that produced this tool call. - A filter object to specify which tools are allowed. + - `type: "program"` - - `read_only: optional boolean` + - `created_by: optional string` - 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. + The ID of the entity that created this tool call. - - `tool_names: optional array of string` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - List of allowed tool names. + The output emitted by an apply patch tool call. - - `never: optional object { read_only, tool_names }` + - `id: string` - A filter object to specify which tools are allowed. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `read_only: optional boolean` + - `call_id: string` - 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. + The unique ID of the apply patch tool call generated by the model. - - `tool_names: optional array of string` + - `status: "completed" or "failed"` - List of allowed tool names. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `MCP tool approval setting: "always" or "never"` + - `"completed"` - 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. + - `"failed"` - - `"always"` + - `type: "apply_patch_call_output"` - - `"never"` + The type of the item. Always `apply_patch_call_output`. - - `server_description: optional string` + - `agent: optional object { agent_name }` - Optional description of the MCP server, used to provide more context. + The agent that produced this item. - - `server_url: optional string` + - `agent_name: string` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The canonical name of the agent that produced this item. - - `tunnel_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - - `code_interpreter: object { container, type, allowed_callers }` + - `direct: object { type }` - A tool that runs Python code to help generate a response to a prompt. + - `program: object { caller_id, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `caller_id: string` - 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. + The call ID of the program item that produced this tool call. - - `union_member_0: string` + - `type: "program"` - The container ID. + - `created_by: optional string` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + The ID of the entity that created this tool call output. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `output: optional string` - - `type: "auto"` + Optional textual output returned by the apply patch tool. - Always `auto`. + - `mcp_call: object { id, arguments, name, 7 more }` - - `file_ids: optional array of string` + An invocation of a tool on an MCP server. - An optional list of uploaded files to make available to your code. + - `id: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The unique ID of the tool call. - The memory limit for the code interpreter container. + - `arguments: string` - - `"1g"` + A JSON string of the arguments passed to the tool. - - `"4g"` + - `name: string` - - `"16g"` + The name of the tool that was run. - - `"64g"` + - `server_label: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The label of the MCP server running the tool. - Network access policy for the container. + - `type: "mcp_call"` - - `beta_container_network_policy_disabled: object { type }` + The type of the item. Always `mcp_call`. - - `type: "disabled"` + - `agent: optional object { agent_name }` - Disable outbound network access. Always `disabled`. + The agent that produced this item. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `agent_name: string` - - `allowed_domains: array of string` + The canonical name of the agent that produced this item. - A list of allowed domains when type is `allowlist`. + - `approval_request_id: optional string` - - `type: "allowlist"` + 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. - Allow outbound network access only to specified domains. Always `allowlist`. + - `error: optional string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The error from the tool call, if any. - Optional domain-scoped secrets for allowlisted domains. + - `output: optional string` - - `domain: string` + The output from the tool call. - The domain associated with the secret. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `name: string` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The name of the secret to inject for the domain. + - `"in_progress"` - - `value: string` + - `"completed"` - The secret value to inject for the domain. + - `"incomplete"` - - `type: "code_interpreter"` + - `"calling"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"failed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The tool invocation context(s). + A list of tools available on an MCP server. - - `"direct"` + - `id: string` - - `"programmatic"` + The unique ID of the list. - - `programmatic_tool_calling: object { type }` + - `server_label: string` - - `image_generation: object { type, action, background, 9 more }` + The label of the MCP server. - A tool that generates images using the GPT image models. + - `tools: array of object { input_schema, name, annotations, description }` - - `type: "image_generation"` + The tools available on the server. - The type of the image generation tool. Always `image_generation`. + - `input_schema: unknown` - - `action: optional "generate" or "edit" or "auto"` + The JSON schema describing the tool's input. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `name: string` - - `"generate"` + The name of the tool. - - `"edit"` + - `annotations: optional unknown` - - `"auto"` + Additional annotations about the tool. - - `background: optional "transparent" or "opaque" or "auto"` + - `description: optional string` - 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. + The description of the tool. - `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. + - `type: "mcp_list_tools"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The type of the item. Always `mcp_list_tools`. - - `"transparent"` + - `agent: optional object { agent_name }` - - `"opaque"` + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `input_fidelity: optional "high" or "low"` + The canonical name of the agent that produced this item. - 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`. + - `error: optional string` - - `"high"` + Error message if the server could not list tools. - - `"low"` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `input_image_mask: optional object { file_id, image_url }` + A request for human approval of a tool invocation. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `id: string` - - `file_id: optional string` + The unique ID of the approval request. - File ID for the mask image. + - `arguments: string` - - `image_url: optional string` + A JSON string of arguments for the tool. - Base64-encoded mask image. + - `name: string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The name of the tool to run. - The image generation model to use. Default: `gpt-image-1`. + - `server_label: string` - - `"gpt-image-1"` + The label of the MCP server making the request. - - `"gpt-image-1-mini"` + - `type: "mcp_approval_request"` - - `"gpt-image-2"` + The type of the item. Always `mcp_approval_request`. - - `"gpt-image-2-2026-04-21"` + - `agent: optional object { agent_name }` - - `"gpt-image-1.5"` + The agent that produced this item. - - `"chatgpt-image-latest"` + - `agent_name: string` - - `moderation: optional "auto" or "low"` + The canonical name of the agent that produced this item. - Moderation level for the generated image. Default: `auto`. + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - - `"auto"` + A response to an MCP approval request. - - `"low"` + - `id: string` - - `output_compression: optional number` + The unique ID of the approval response - Compression level for the output image. Default: 100. + - `approval_request_id: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The ID of the approval request being answered. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `approve: boolean` - - `"png"` + Whether the request was approved. - - `"webp"` + - `type: "mcp_approval_response"` - - `"jpeg"` + The type of the item. Always `mcp_approval_response`. - - `partial_images: optional number` + - `agent: optional object { agent_name }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The agent that produced this item. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `agent_name: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The canonical name of the agent that produced this item. - - `"low"` + - `reason: optional string` - - `"medium"` + Optional reason for the decision. - - `"high"` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `"auto"` + A call to a custom tool created by the model. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `call_id: string` - 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`. + An identifier used to map this custom tool call to a tool call output. - - `"1024x1024"` + - `input: string` - - `"1024x1536"` + The input for the custom tool call generated by the model. - - `"1536x1024"` + - `name: string` - - `"auto"` + The name of the custom tool being called. - - `local_shell: object { type }` + - `type: "custom_tool_call"` - A tool that allows the model to execute shell commands in a local environment. + The type of the custom tool call. Always `custom_tool_call`. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `id: optional string` - A tool that allows the model to execute shell commands. + The unique ID of the custom tool call in the OpenAI platform. - - `type: "shell"` + - `agent: optional object { agent_name }` - The type of the shell tool. Always `shell`. + The agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `caller: optional object { type } or object { caller_id, type }` - The tool invocation context(s). + The execution context that produced this tool call. - - `"direct"` + - `namespace: optional string` - - `"programmatic"` + The namespace of the custom tool being called. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + The output of a custom tool call from your code, being sent back to the model. - - `type: "container_auto"` + - `id: string` - Automatically creates a container for this request + The unique ID of the custom tool call output item. - - `file_ids: optional array of string` + - `status: "in_progress" or "completed" or "incomplete"` - An optional list of uploaded files to make available to your code. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"in_progress"` - The memory limit for the container. + - `"completed"` - - `"1g"` + - `"incomplete"` - - `"4g"` + - `created_by: optional string` - - `"16g"` + The identifier of the actor that created the item. - - `"64g"` + - `parallel_tool_calls: boolean` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + Whether to allow the model to run tool calls in parallel. - Network access policy for the container. + - `temperature: number` - - `beta_container_network_policy_disabled: object { type }` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - An optional list of skills referenced by id or inline data. + - `beta_tool_choice_options: "none" or "auto" or "required"` - - `beta_skill_reference: object { skill_id, type, version }` + Controls which (if any) tool is called by the model. - - `skill_id: string` + `none` means the model will not call any tool and instead generates a message. - The ID of the referenced skill. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `type: "skill_reference"` + `required` means the model must call one or more tools. - References a skill created with the /v1/skills endpoint. + - `"none"` - - `version: optional string` + - `"auto"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"required"` - - `beta_inline_skill: object { description, name, source, type }` + - `beta_tool_choice_allowed: object { mode, tools, type }` - - `description: string` + Constrains the tools available to the model to a pre-defined set. - The description of the skill. + - `mode: "auto" or "required"` - - `name: string` + Constrains the tools available to the model to a pre-defined set. - The name of the skill. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `source: object { data, media_type, type }` + `required` requires the model to call one or more of the allowed tools. - Inline skill payload + - `"auto"` - - `data: string` + - `"required"` - Base64-encoded skill zip bundle. + - `tools: array of map[unknown]` - - `media_type: "application/zip"` + A list of tool definitions that the model should be allowed to call. - The media type of the inline skill payload. Must be `application/zip`. + For the Responses API, the list of tool definitions might look like: - - `type: "base64"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The type of the inline skill source. Must be `base64`. + - `type: "allowed_tools"` - - `type: "inline"` + Allowed tool configuration type. Always `allowed_tools`. - Defines an inline skill for this request. + - `beta_tool_choice_types: object { type }` - - `beta_local_environment: object { type, skills }` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `type: "local"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - Use a local computer environment. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `skills: optional array of BetaLocalSkill` + Allowed values are: - An optional list of skills. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `description: string` + - `"file_search"` - The description of the skill. + - `"web_search_preview"` - - `name: string` + - `"computer"` - The name of the skill. + - `"computer_use_preview"` - - `path: string` + - `"computer_use"` - The path to the directory containing the skill. + - `"web_search_preview_2025_03_11"` - - `beta_container_reference: object { container_id, type }` + - `"image_generation"` - - `container_id: string` + - `"code_interpreter"` - The ID of the referenced container. + - `beta_tool_choice_function: object { name, type }` - - `type: "container_reference"` + Use this option to force the model to call a specific function. - References a container created with the /v1/containers endpoint + - `name: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The name of the function to call. - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + - `type: "function"` - - `name: string` + For function calling, the type is always `function`. - The name of the custom tool, used to identify it in tool calls. + - `beta_tool_choice_mcp: object { server_label, type, name }` - - `type: "custom"` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the custom tool. Always `custom`. + - `server_label: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The label of the MCP server to use. - The tool invocation context(s). + - `type: "mcp"` - - `"direct"` + For MCP tools, the type is always `mcp`. - - `"programmatic"` + - `name: optional string` - - `defer_loading: optional boolean` + The name of the tool to call on the server. - Whether this tool should be deferred and discovered via tool search. + - `beta_tool_choice_custom: object { name, type }` - - `description: optional string` + Use this option to force the model to call a specific custom tool. - Optional description of the custom tool, used to provide more context. + - `name: string` - - `format: optional object { type } or object { definition, syntax, type }` + The name of the custom tool to call. - The input format for the custom tool. Default is unconstrained text. + - `type: "custom"` - - `text: object { type }` + For custom tool calling, the type is always `custom`. - Unconstrained free-form text. + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - - `grammar: object { definition, syntax, type }` + - `beta_tool_choice_apply_patch: object { type }` - A grammar defined by the user. + Forces the model to call the apply_patch tool when executing a tool call. - - `definition: string` + - `type: "apply_patch"` - The grammar definition. + The tool to call. Always `apply_patch`. - - `syntax: "lark" or "regex"` + - `beta_tool_choice_shell: object { type }` - The syntax of the grammar definition. One of `lark` or `regex`. + Forces the model to call the shell tool when a tool call is required. - - `"lark"` + - `type: "shell"` - - `"regex"` + The tool to call. Always `shell`. - - `type: "grammar"` + - `tools: array of BetaTool` - Grammar format. Always `grammar`. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `beta_namespace_tool: object { description, name, tools, type }` + We support the following categories of tools: - Groups function/custom tools under a shared namespace. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `description: string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - A description of the namespace shown to the model. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `name: string` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The namespace name used in tool calls (for example, `crm`). + 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). - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `beta_computer_tool: object { type }` - The function/custom tools available inside this namespace. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `function: object { name, type, allowed_callers, 5 more }` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `name: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "function"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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). - The tool invocation context(s). + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `"direct"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"programmatic"` + - `code_interpreter: object { container, type, allowed_callers }` - - `defer_loading: optional boolean` + A tool that runs Python code to help generate a response to a prompt. - Whether this function should be deferred and discovered via tool search. + - `programmatic_tool_calling: object { type }` - - `description: optional string` + - `image_generation: object { type, action, background, 9 more }` - - `output_schema: optional map[unknown]` + A tool that generates images using the GPT image models. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `local_shell: object { type }` - - `parameters: optional unknown` + A tool that allows the model to execute shell commands in a local environment. - - `strict: optional boolean` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - 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. + A tool that allows the model to execute shell commands. - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - `name: string` + - `beta_namespace_tool: object { description, name, tools, type }` - The name of the custom tool, used to identify it in tool calls. + Groups function/custom tools under a shared namespace. - - `type: "custom"` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The type of the custom tool. Always `custom`. + Hosted or BYOT tool search configuration for deferred tools. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The tool invocation context(s). + 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). - - `defer_loading: optional boolean` + - `beta_apply_patch_tool: object { type, allowed_callers }` - Whether this tool should be deferred and discovered via tool search. + Allows the assistant to create, delete, or update files using unified diffs. - - `description: optional string` + - `top_p: number` - Optional description of the custom tool, used to provide more context. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `format: optional object { type } or object { definition, syntax, type }` + We generally recommend altering this or `temperature` but not both. - The input format for the custom tool. Default is unconstrained text. + - `background: optional boolean` - - `type: "namespace"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The type of the tool. Always `namespace`. + - `completed_at: optional number` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - Hosted or BYOT tool search configuration for deferred tools. + - `conversation: optional object { id }` - - `type: "tool_search"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The type of the tool. Always `tool_search`. + - `id: string` - - `description: optional string` + The unique ID of the conversation that this response was associated with. - Description shown to the model for a client-executed tool search tool. + - `max_output_tokens: optional number` - - `execution: optional "server" or "client"` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - Whether tool search is executed by the server or by the client. + - `max_tool_calls: optional number` - - `"server"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `"client"` + - `moderation: optional object { input, output }` - - `parameters: optional unknown` + Moderation results for the response input and output, if moderated completions were requested. - Parameter schema for a client-executed tool search tool. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + Moderation for the response input. - 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). + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + A moderation result produced for the response input or output. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `categories: map[boolean]` - - `"web_search_preview"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"web_search_preview_2025_03_11"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `search_content_types: optional array of "text" or "image"` + Which modalities of input are reflected by the score for each category. - `"text"` - `"image"` - - `search_context_size: optional "low" or "medium" or "high"` - - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `category_scores: map[number]` - - `"low"` + A dictionary of moderation categories to scores. - - `"medium"` + - `flagged: boolean` - - `"high"` + A boolean indicating whether the content was flagged by any category. - - `user_location: optional object { type, city, country, 2 more }` + - `model: string` - The user's location. + The moderation model that produced this result. - - `type: "approximate"` + - `type: "moderation_result"` - The type of location approximation. Always `approximate`. + The object type, which was always `moderation_result` for successful moderation results. - - `city: optional string` + - `error: object { code, message, type }` - Free text input for the city of the user, e.g. `San Francisco`. + An error produced while attempting moderation for the response input or output. - - `country: optional string` + - `code: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The error code. - - `region: optional string` + - `message: string` - Free text input for the region of the user, e.g. `California`. + The error message. - - `timezone: optional string` + - `type: "error"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The object type, which was always `error` for moderation failures. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - Allows the assistant to create, delete, or update files using unified diffs. + Moderation for the response output. - - `type: "apply_patch"` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - The type of the tool. Always `apply_patch`. + A moderation result produced for the response input or output. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `categories: map[boolean]` - The tool invocation context(s). + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"direct"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"programmatic"` + Which modalities of input are reflected by the score for each category. - - `type: "tool_search_output"` + - `"text"` - The type of the item. Always `tool_search_output`. + - `"image"` - - `agent: optional object { agent_name }` + - `category_scores: map[number]` - The agent that produced this item. + A dictionary of moderation categories to scores. - - `agent_name: string` + - `flagged: boolean` - The canonical name of the agent that produced this item. + A boolean indicating whether the content was flagged by any category. - - `created_by: optional string` + - `model: string` - The identifier of the actor that created the item. + The moderation model that produced this result. - - `additional_tools: object { id, role, tools, 2 more }` + - `type: "moderation_result"` - - `id: string` + The object type, which was always `moderation_result` for successful moderation results. - The unique ID of the additional tools item. + - `error: object { code, message, type }` - - `role: "unknown" or "user" or "assistant" or 5 more` + An error produced while attempting moderation for the response input or output. - The role that provided the additional tools. + - `code: string` - - `"unknown"` + The error code. - - `"user"` + - `message: string` - - `"assistant"` + The error message. - - `"system"` + - `type: "error"` - - `"critic"` + The object type, which was always `error` for moderation failures. - - `"discriminator"` + - `previous_response_id: optional string` - - `"developer"` + 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`. - - `"tool"` + - `prompt: optional object { id, variables, version }` - - `tools: array of BetaTool` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The additional tool definitions made available at this item. + - `id: string` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The unique identifier of the prompt template to use. - 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). + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - 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). + - `union_member_0: string` - - `beta_computer_tool: object { type }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A text input to the model. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - 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). + A file input to the model. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `version: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Optional version of the prompt template. - - `code_interpreter: object { container, type, allowed_callers }` + - `prompt_cache_key: optional string` - A tool that runs Python code to help generate a response to a prompt. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `programmatic_tool_calling: object { type }` + - `prompt_cache_options: optional object { mode, ttl }` - - `image_generation: object { type, action, background, 9 more }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - A tool that generates images using the GPT image models. + - `mode: "implicit" or "explicit"` - - `local_shell: object { type }` + Whether implicit prompt-cache breakpoints were enabled. - A tool that allows the model to execute shell commands in a local environment. + - `"implicit"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `"explicit"` - A tool that allows the model to execute shell commands. + - `ttl: "30m"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The minimum lifetime applied to each cache breakpoint. - 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) + - `"30m"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `prompt_cache_retention: optional "in_memory" or "24h"` - Groups function/custom tools under a shared namespace. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - Hosted or BYOT tool search configuration for deferred tools. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - 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). + - `"in_memory"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"24h"` - Allows the assistant to create, delete, or update files using unified diffs. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `type: "additional_tools"` + **gpt-5 and o-series models only** - The type of the item. Always `additional_tools`. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `agent: optional object { agent_name }` + - `context: optional "auto" or "current_turn" or "all_turns"` - The agent that produced this item. + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"current_turn"` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `"all_turns"` - 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). + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `id: string` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The unique identifier of the reasoning content. + - `"none"` - - `summary: array of object { text, type }` + - `"minimal"` - Reasoning summary content. + - `"low"` - - `text: string` + - `"medium"` - A summary of the reasoning output from the model so far. + - `"high"` - - `type: "summary_text"` + - `"xhigh"` - The type of the object. Always `summary_text`. + - `"max"` - - `type: "reasoning"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The type of the object. Always `reasoning`. + **Deprecated:** use `summary` instead. - - `agent: optional object { agent_name }` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"concise"` - The canonical name of the agent that produced this item. + - `"detailed"` - - `content: optional array of object { text, type }` + - `mode: optional string or "standard" or "pro"` - Reasoning text content. + Controls the reasoning execution mode for the request. - - `text: string` + When returned on a response, this is the effective execution mode. - The reasoning text from the model. + - `"standard"` - - `type: "reasoning_text"` + - `"pro"` - The type of the reasoning text. Always `reasoning_text`. + - `summary: optional "auto" or "concise" or "detailed"` - - `encrypted_content: optional string` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"concise"` - - `"in_progress"` + - `"detailed"` - - `"completed"` + - `safety_identifier: optional string` - - `"incomplete"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `program: object { id, call_id, code, 3 more }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `id: string` + Specifies the processing type used for serving the request. - The unique ID of the program item. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `call_id: string` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The stable call ID of the program item. + - `"auto"` - - `code: string` + - `"default"` - The JavaScript source executed by programmatic tool calling. + - `"flex"` - - `fingerprint: string` + - `"scale"` - Opaque program replay fingerprint that must be round-tripped. + - `"priority"` - - `type: "program"` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - The type of the item. Always `program`. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `agent: optional object { agent_name }` + - `"completed"` - The agent that produced this item. + - `"failed"` - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"cancelled"` - - `program_output: object { id, call_id, result, 3 more }` + - `"queued"` - - `id: string` + - `"incomplete"` - The unique ID of the program output item. + - `text: optional object { format, verbosity }` - - `call_id: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The call ID of the program item. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `result: string` + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - The result produced by the program item. + An object specifying the format that the model must output. - - `status: "completed" or "incomplete"` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The terminal status of the program output item. + The default format is `{ "type": "text" }` with no additional options. - - `"completed"` + **Not recommended for gpt-4o and newer models:** - - `"incomplete"` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `type: "program_output"` + - `text: object { type }` - The type of the item. Always `program_output`. + Default response format. Used to generate text responses. - - `agent: optional object { agent_name }` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - The agent that produced this item. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `schema: map[unknown]` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `id: string` + - `type: "json_schema"` - The unique ID of the compaction item. + The type of response format being defined. Always `json_schema`. - - `encrypted_content: string` + - `description: optional string` - The encrypted content that was produced by compaction. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "compaction"` + - `strict: optional boolean` - The type of the item. Always `compaction`. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `agent: optional object { agent_name }` + - `json_object: object { type }` - The agent that produced this item. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `agent_name: string` + - `verbosity: optional "low" or "medium" or "high"` - The canonical name of the agent that produced this item. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `created_by: optional string` + - `"low"` - The identifier of the actor that created the item. + - `"medium"` - - `image_generation_call: object { id, result, status, 2 more }` + - `"high"` - An image generation request made by the model. + - `top_logprobs: optional number` - - `id: string` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The unique ID of the image generation call. + - `truncation: optional "auto" or "disabled"` - - `result: string` + The truncation strategy to use for the model response. - The generated image encoded in base64. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"auto"` - The status of the image generation call. + - `"disabled"` - - `"in_progress"` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `"completed"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `"generating"` + - `input_tokens: number` - - `"failed"` + The number of input tokens. - - `type: "image_generation_call"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The type of the image generation call. Always `image_generation_call`. + A detailed breakdown of the input tokens. - - `agent: optional object { agent_name }` + - `cache_write_tokens: number` - The agent that produced this item. + The number of input tokens that were written to the cache. - - `agent_name: string` + - `cached_tokens: number` - The canonical name of the agent that produced this item. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `output_tokens: number` - A tool call to run code. + The number of output tokens. - - `id: string` + - `output_tokens_details: object { reasoning_tokens }` - The unique ID of the code interpreter tool call. + A detailed breakdown of the output tokens. - - `code: string` + - `reasoning_tokens: number` - The code to run, or null if not available. + The number of reasoning tokens. - - `container_id: string` + - `total_tokens: number` - The ID of the container used to run the code. + The total number of tokens used. - - `outputs: array of object { logs, type } or object { type, url }` + - `user: optional string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `logs: object { logs, type }` + - `sequence_number: number` - The logs output from the code interpreter. + The sequence number for this event. - - `logs: string` + - `type: "response.queued"` - The logs output from the code interpreter. + The type of the event. Always 'response.queued'. - - `type: "logs"` + - `agent: optional object { agent_name }` - The type of the output. Always `logs`. + The agent that owns this multi-agent streaming event. - - `image: object { type, url }` + - `agent_name: string` - The image output from the code interpreter. + The canonical name of the agent that produced this item. - - `type: "image"` +### Beta Response Reasoning Item - The type of the output. Always `image`. +- `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `url: string` + 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). - The URL of the image output from the code interpreter. + - `id: string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The unique identifier of the reasoning content. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `summary: array of object { text, type }` - - `"in_progress"` + Reasoning summary content. - - `"completed"` + - `text: string` - - `"incomplete"` + A summary of the reasoning output from the model so far. - - `"interpreting"` + - `type: "summary_text"` - - `"failed"` + The type of the object. Always `summary_text`. - - `type: "code_interpreter_call"` + - `type: "reasoning"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the object. Always `reasoning`. - `agent: optional object { agent_name }` @@ -94363,932 +105161,924 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` - - A tool call to run a command on the local shell. - - - `id: string` + - `content: optional array of object { text, type }` - The unique ID of the local shell call. + Reasoning text content. - - `action: object { command, env, type, 3 more }` + - `text: string` - Execute a shell command on the server. + The reasoning text from the model. - - `command: array of string` + - `type: "reasoning_text"` - The command to run. + The type of the reasoning text. Always `reasoning_text`. - - `env: map[string]` + - `encrypted_content: optional string` - Environment variables to set for the command. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `type: "exec"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The type of the local shell action. Always `exec`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `timeout_ms: optional number` + - `"in_progress"` - Optional timeout in milliseconds for the command. + - `"completed"` - - `user: optional string` + - `"incomplete"` - Optional user to run the command as. +### Beta Response Reasoning Summary Part Added Event - - `working_directory: optional string` +- `beta_response_reasoning_summary_part_added_event: object { item_id, output_index, part, 4 more }` - Optional working directory to run the command in. + Emitted when a new reasoning summary part is added. - - `call_id: string` + - `item_id: string` - The unique ID of the local shell tool call generated by the model. + The ID of the item this summary part is associated with. - - `status: "in_progress" or "completed" or "incomplete"` + - `output_index: number` - The status of the local shell call. + The index of the output item this summary part is associated with. - - `"in_progress"` + - `part: object { text, type }` - - `"completed"` + The summary part that was added. - - `"incomplete"` + - `text: string` - - `type: "local_shell_call"` + The text of the summary part. - The type of the local shell call. Always `local_shell_call`. + - `type: "summary_text"` - - `agent: optional object { agent_name }` + The type of the summary part. Always `summary_text`. - The agent that produced this item. + - `sequence_number: number` - - `agent_name: string` + The sequence number of this event. - The canonical name of the agent that produced this item. + - `summary_index: number` - - `local_shell_call_output: object { id, output, type, 2 more }` + The index of the summary part within the reasoning summary. - The output of a local shell tool call. + - `type: "response.reasoning_summary_part.added"` - - `id: string` + The type of the event. Always `response.reasoning_summary_part.added`. - The unique ID of the local shell tool call generated by the model. + - `agent: optional object { agent_name }` - - `output: string` + The agent that owns this multi-agent streaming event. - A JSON string of the output of the local shell tool call. + - `agent_name: string` - - `type: "local_shell_call_output"` + The canonical name of the agent that produced this item. - The type of the local shell tool call output. Always `local_shell_call_output`. +### Beta Response Reasoning Summary Part Done Event - - `agent: optional object { agent_name }` +- `beta_response_reasoning_summary_part_done_event: object { item_id, output_index, part, 5 more }` - The agent that produced this item. + Emitted when a reasoning summary part is completed. - - `agent_name: string` + - `item_id: string` - The canonical name of the agent that produced this item. + The ID of the item this summary part is associated with. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `output_index: number` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The index of the output item this summary part is associated with. - - `"in_progress"` + - `part: object { text, type }` - - `"completed"` + The completed summary part. - - `"incomplete"` + - `text: string` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + The text of the summary part. - A tool call that executes one or more shell commands in a managed environment. + - `type: "summary_text"` - - `id: string` + The type of the summary part. Always `summary_text`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `sequence_number: number` - - `action: object { commands, max_output_length, timeout_ms }` + The sequence number of this event. - The shell commands and limits that describe how to run the tool call. + - `summary_index: number` - - `commands: array of string` + The index of the summary part within the reasoning summary. - - `max_output_length: number` + - `type: "response.reasoning_summary_part.done"` - Optional maximum number of characters to return from each command. + The type of the event. Always `response.reasoning_summary_part.done`. - - `timeout_ms: number` + - `agent: optional object { agent_name }` - Optional timeout in milliseconds for the commands. + The agent that owns this multi-agent streaming event. - - `call_id: string` + - `agent_name: string` - The unique ID of the shell tool call generated by the model. + The canonical name of the agent that produced this item. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `status: optional "incomplete"` - Represents the use of a local environment to perform shell actions. + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `beta_response_local_environment: object { type }` + - `"incomplete"` - Represents the use of a local environment to perform shell actions. +### Beta Response Reasoning Summary Text Delta Event - - `type: "local"` +- `beta_response_reasoning_summary_text_delta_event: object { delta, item_id, output_index, 4 more }` - The environment type. Always `local`. + Emitted when a delta is added to a reasoning summary text. - - `beta_response_container_reference: object { container_id, type }` + - `delta: string` - Represents a container created with /v1/containers. + The text delta that was added to the summary. - - `container_id: string` + - `item_id: string` - - `type: "container_reference"` + The ID of the item this summary text delta is associated with. - The environment type. Always `container_reference`. + - `output_index: number` - - `status: "in_progress" or "completed" or "incomplete"` + The index of the output item this summary text delta is associated with. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `sequence_number: number` - - `"in_progress"` + The sequence number of this event. - - `"completed"` + - `summary_index: number` - - `"incomplete"` + The index of the summary part within the reasoning summary. - - `type: "shell_call"` + - `type: "response.reasoning_summary_text.delta"` - The type of the item. Always `shell_call`. + The type of the event. Always `response.reasoning_summary_text.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` +### Beta Response Reasoning Summary Text Done Event - The execution context that produced this tool call. +- `beta_response_reasoning_summary_text_done_event: object { item_id, output_index, sequence_number, 4 more }` - - `direct: object { type }` + Emitted when a reasoning summary text is completed. - - `program: object { caller_id, type }` + - `item_id: string` - - `caller_id: string` + The ID of the item this summary text is associated with. - The call ID of the program item that produced this tool call. + - `output_index: number` - - `type: "program"` + The index of the output item this summary text is associated with. - - `created_by: optional string` + - `sequence_number: number` - The ID of the entity that created this tool call. + The sequence number of this event. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `summary_index: number` - The output of a shell tool call that was emitted. + The index of the summary part within the reasoning summary. - - `id: string` + - `text: string` - The unique ID of the shell call output. Populated when this item is returned via API. + The full text of the completed reasoning summary. - - `call_id: string` + - `type: "response.reasoning_summary_text.done"` - The unique ID of the shell tool call generated by the model. + The type of the event. Always `response.reasoning_summary_text.done`. - - `max_output_length: number` + - `agent: optional object { agent_name }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The agent that owns this multi-agent streaming event. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `agent_name: string` - An array of shell call output contents + The canonical name of the agent that produced this item. - - `outcome: object { type } or object { exit_code, type }` +### Beta Response Reasoning Text Delta Event - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. +- `beta_response_reasoning_text_delta_event: object { content_index, delta, item_id, 4 more }` - - `timeout: object { type }` + Emitted when a delta is added to a reasoning text. - Indicates that the shell call exceeded its configured time limit. + - `content_index: number` - - `exit: object { exit_code, type }` + The index of the reasoning content part this delta is associated with. - Indicates that the shell commands finished and returned an exit code. + - `delta: string` - - `exit_code: number` + The text delta that was added to the reasoning content. - Exit code from the shell process. + - `item_id: string` - - `type: "exit"` + The ID of the item this reasoning text delta is associated with. - The outcome type. Always `exit`. + - `output_index: number` - - `stderr: string` + The index of the output item this reasoning text delta is associated with. - The standard error output that was captured. + - `sequence_number: number` - - `stdout: string` + The sequence number of this event. - The standard output that was captured. + - `type: "response.reasoning_text.delta"` - - `created_by: optional string` + The type of the event. Always `response.reasoning_text.delta`. - The identifier of the actor that created the item. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "completed" or "incomplete"` + The agent that owns this multi-agent streaming event. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` +### Beta Response Reasoning Text Done Event - - `"incomplete"` +- `beta_response_reasoning_text_done_event: object { content_index, item_id, output_index, 4 more }` - - `type: "shell_call_output"` + Emitted when a reasoning text is completed. - The type of the shell call output. Always `shell_call_output`. + - `content_index: number` - - `agent: optional object { agent_name }` + The index of the reasoning content part. - The agent that produced this item. + - `item_id: string` - - `agent_name: string` + The ID of the item this reasoning text is associated with. - The canonical name of the agent that produced this item. + - `output_index: number` - - `caller: optional object { type } or object { caller_id, type }` + The index of the output item this reasoning text is associated with. - The execution context that produced this tool call. + - `sequence_number: number` - - `direct: object { type }` + The sequence number of this event. - - `program: object { caller_id, type }` + - `text: string` - - `caller_id: string` + The full text of the completed reasoning content. - The call ID of the program item that produced this tool call. + - `type: "response.reasoning_text.done"` - - `type: "program"` + The type of the event. Always `response.reasoning_text.done`. - - `created_by: optional string` + - `agent: optional object { agent_name }` - The identifier of the actor that created the item. + The agent that owns this multi-agent streaming event. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `agent_name: string` - A tool call that applies file diffs by creating, deleting, or updating files. + The canonical name of the agent that produced this item. - - `id: string` +### Beta Response Refusal Delta Event - The unique ID of the apply patch tool call. Populated when this item is returned via API. +- `beta_response_refusal_delta_event: object { content_index, delta, item_id, 4 more }` - - `call_id: string` + Emitted when there is a partial refusal text. - The unique ID of the apply patch tool call generated by the model. + - `content_index: number` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The index of the content part that the refusal text is added to. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `delta: string` - - `create_file: object { diff, path, type }` + The refusal text that is added. - Instruction describing how to create a file via the apply_patch tool. + - `item_id: string` - - `diff: string` + The ID of the output item that the refusal text is added to. - Diff to apply. + - `output_index: number` - - `path: string` + The index of the output item that the refusal text is added to. - Path of the file to create. + - `sequence_number: number` - - `type: "create_file"` + The sequence number of this event. - Create a new file with the provided diff. + - `type: "response.refusal.delta"` - - `delete_file: object { path, type }` + The type of the event. Always `response.refusal.delta`. - Instruction describing how to delete a file via the apply_patch tool. + - `agent: optional object { agent_name }` - - `path: string` + The agent that owns this multi-agent streaming event. - Path of the file to delete. + - `agent_name: string` - - `type: "delete_file"` + The canonical name of the agent that produced this item. - Delete the specified file. +### Beta Response Refusal Done Event - - `update_file: object { diff, path, type }` +- `beta_response_refusal_done_event: object { content_index, item_id, output_index, 4 more }` - Instruction describing how to update a file via the apply_patch tool. + Emitted when refusal text is finalized. - - `diff: string` + - `content_index: number` - Diff to apply. + The index of the content part that the refusal text is finalized. - - `path: string` + - `item_id: string` - Path of the file to update. + The ID of the output item that the refusal text is finalized. - - `type: "update_file"` + - `output_index: number` - Update an existing file with the provided diff. + The index of the output item that the refusal text is finalized. - - `status: "in_progress" or "completed"` + - `refusal: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The refusal text that is finalized. - - `"in_progress"` + - `sequence_number: number` - - `"completed"` + The sequence number of this event. - - `type: "apply_patch_call"` + - `type: "response.refusal.done"` - The type of the item. Always `apply_patch_call`. + The type of the event. Always `response.refusal.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. +### Beta Response Status - - `direct: object { type }` +- `beta_response_status: "completed" or "failed" or "in_progress" or 3 more` - - `program: object { caller_id, type }` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `caller_id: string` + - `"completed"` - The call ID of the program item that produced this tool call. + - `"failed"` - - `type: "program"` + - `"in_progress"` - - `created_by: optional string` + - `"cancelled"` - The ID of the entity that created this tool call. + - `"queued"` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `"incomplete"` - The output emitted by an apply patch tool call. +### Beta Response Stream Event - - `id: string` +- `beta_response_stream_event: BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 50 more` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + Emitted when there is a partial audio response. - - `call_id: string` + - `beta_response_audio_delta_event: object { delta, sequence_number, type, agent }` - The unique ID of the apply patch tool call generated by the model. + Emitted when there is a partial audio response. - - `status: "completed" or "failed"` + - `delta: string` - The status of the apply patch tool call output. One of `completed` or `failed`. + A chunk of Base64 encoded response audio bytes. - - `"completed"` + - `sequence_number: number` - - `"failed"` + A sequence number for this chunk of the stream response. - - `type: "apply_patch_call_output"` + - `type: "response.audio.delta"` - The type of the item. Always `apply_patch_call_output`. + The type of the event. Always `response.audio.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. + - `beta_response_audio_done_event: object { sequence_number, type, agent }` - - `direct: object { type }` + Emitted when the audio response is complete. - - `program: object { caller_id, type }` + - `sequence_number: number` - - `caller_id: string` + The sequence number of the delta. - The call ID of the program item that produced this tool call. + - `type: "response.audio.done"` - - `type: "program"` + The type of the event. Always `response.audio.done`. - - `created_by: optional string` + - `agent: optional object { agent_name }` - The ID of the entity that created this tool call output. + The agent that owns this multi-agent streaming event. - - `output: optional string` + - `agent_name: string` - Optional textual output returned by the apply patch tool. + The canonical name of the agent that produced this item. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `beta_response_audio_transcript_delta_event: object { delta, sequence_number, type, agent }` - A list of tools available on an MCP server. + Emitted when there is a partial transcript of audio. - - `id: string` + - `delta: string` - The unique ID of the list. + The partial transcript of the audio response. - - `server_label: string` + - `sequence_number: number` - The label of the MCP server. + The sequence number of this event. - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "response.audio.transcript.delta"` - The tools available on the server. + The type of the event. Always `response.audio.transcript.delta`. - - `input_schema: unknown` + - `agent: optional object { agent_name }` - The JSON schema describing the tool's input. + The agent that owns this multi-agent streaming event. - - `name: string` + - `agent_name: string` - The name of the tool. + The canonical name of the agent that produced this item. - - `annotations: optional unknown` + - `beta_response_audio_transcript_done_event: object { sequence_number, type, agent }` - Additional annotations about the tool. + Emitted when the full audio transcript is completed. - - `description: optional string` + - `sequence_number: number` - The description of the tool. + The sequence number of this event. - - `type: "mcp_list_tools"` + - `type: "response.audio.transcript.done"` - The type of the item. Always `mcp_list_tools`. + The type of the event. Always `response.audio.transcript.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `error: optional string` - - Error message if the server could not list tools. - - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `beta_response_code_interpreter_call_code_delta_event: object { delta, item_id, output_index, 3 more }` - A request for human approval of a tool invocation. + Emitted when a partial code snippet is streamed by the code interpreter. - - `id: string` + - `delta: string` - The unique ID of the approval request. + The partial code snippet being streamed by the code interpreter. - - `arguments: string` + - `item_id: string` - A JSON string of arguments for the tool. + The unique identifier of the code interpreter tool call item. - - `name: string` + - `output_index: number` - The name of the tool to run. + The index of the output item in the response for which the code is being streamed. - - `server_label: string` + - `sequence_number: number` - The label of the MCP server making the request. + The sequence number of this event, used to order streaming events. - - `type: "mcp_approval_request"` + - `type: "response.code_interpreter_call_code.delta"` - The type of the item. Always `mcp_approval_request`. + The type of the event. Always `response.code_interpreter_call_code.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `beta_response_code_interpreter_call_code_done_event: object { code, item_id, output_index, 3 more }` - A response to an MCP approval request. + Emitted when the code snippet is finalized by the code interpreter. - - `id: string` + - `code: string` - The unique ID of the approval response + The final code snippet output by the code interpreter. - - `approval_request_id: string` + - `item_id: string` - The ID of the approval request being answered. + The unique identifier of the code interpreter tool call item. - - `approve: boolean` + - `output_index: number` - Whether the request was approved. + The index of the output item in the response for which the code is finalized. - - `type: "mcp_approval_response"` + - `sequence_number: number` - The type of the item. Always `mcp_approval_response`. + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call_code.done"` + + The type of the event. Always `response.code_interpreter_call_code.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `reason: optional string` - - Optional reason for the decision. - - - `mcp_call: object { id, arguments, name, 7 more }` - - An invocation of a tool on an MCP server. - - - `id: string` + - `beta_response_code_interpreter_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - The unique ID of the tool call. + Emitted when the code interpreter call is completed. - - `arguments: string` + - `item_id: string` - A JSON string of the arguments passed to the tool. + The unique identifier of the code interpreter tool call item. - - `name: string` + - `output_index: number` - The name of the tool that was run. + The index of the output item in the response for which the code interpreter call is completed. - - `server_label: string` + - `sequence_number: number` - The label of the MCP server running the tool. + The sequence number of this event, used to order streaming events. - - `type: "mcp_call"` + - `type: "response.code_interpreter_call.completed"` - The type of the item. Always `mcp_call`. + The type of the event. Always `response.code_interpreter_call.completed`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `beta_response_code_interpreter_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `error: optional string` + Emitted when a code interpreter call is in progress. - The error from the tool call, if any. + - `item_id: string` - - `output: optional string` + The unique identifier of the code interpreter tool call item. - The output from the tool call. + - `output_index: number` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + The index of the output item in the response for which the code interpreter call is in progress. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `sequence_number: number` - - `"in_progress"` + The sequence number of this event, used to order streaming events. - - `"completed"` + - `type: "response.code_interpreter_call.in_progress"` - - `"incomplete"` + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `"calling"` + - `agent: optional object { agent_name }` - - `"failed"` + The agent that owns this multi-agent streaming event. - - `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` + - `agent_name: string` - A call to a custom tool created by the model. + The canonical name of the agent that produced this item. - - `id: string` + - `beta_response_code_interpreter_call_interpreting_event: object { item_id, output_index, sequence_number, 2 more }` - The unique ID of the custom tool call item. + Emitted when the code interpreter is actively interpreting the code snippet. - - `status: "in_progress" or "completed" or "incomplete"` + - `item_id: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique identifier of the code interpreter tool call item. - - `"in_progress"` + - `output_index: number` - - `"completed"` + The index of the output item in the response for which the code interpreter is interpreting code. - - `"incomplete"` + - `sequence_number: number` - - `created_by: optional string` + The sequence number of this event, used to order streaming events. - The identifier of the actor that created the item. + - `type: "response.code_interpreter_call.interpreting"` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The type of the event. Always `response.code_interpreter_call.interpreting`. - The output of a custom tool call from your code, being sent back to the model. + - `agent: optional object { agent_name }` - - `id: string` + The agent that owns this multi-agent streaming event. - The unique ID of the custom tool call output item. + - `agent_name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The canonical name of the agent that produced this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_response_completed_event: object { response, sequence_number, type, agent }` - - `"in_progress"` + Emitted when the model response is complete. - - `"completed"` + - `response: object { id, created_at, error, 31 more }` - - `"incomplete"` + Properties of the completed response. - - `created_by: optional string` + - `id: string` - The identifier of the actor that created the item. + Unique identifier for this Response. -### Beta Response Local Environment + - `created_at: number` -- `beta_response_local_environment: object { type }` + Unix timestamp (in seconds) of when this Response was created. - Represents the use of a local environment to perform shell actions. + - `error: object { code, message }` - - `type: "local"` + An error object returned when the model fails to generate a Response. - The environment type. Always `local`. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` -### Beta Response Mcp Call Arguments Delta Event + The error code for the response. -- `beta_response_mcp_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` + - `"server_error"` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `"rate_limit_exceeded"` - - `delta: string` + - `"invalid_prompt"` - A JSON string containing the partial update to the arguments for the MCP tool call. + - `"bio_policy"` - - `item_id: string` + - `"vector_store_timeout"` - The unique identifier of the MCP tool call item being processed. + - `"invalid_image"` - - `output_index: number` + - `"invalid_image_format"` - The index of the output item in the response's output array. + - `"invalid_base64_image"` - - `sequence_number: number` + - `"invalid_image_url"` - The sequence number of this event. + - `"image_too_large"` - - `type: "response.mcp_call_arguments.delta"` + - `"image_too_small"` - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `"image_parse_error"` - - `agent: optional object { agent_name }` + - `"image_content_policy_violation"` - The agent that owns this multi-agent streaming event. + - `"invalid_image_mode"` - - `agent_name: string` + - `"image_file_too_large"` - The canonical name of the agent that produced this item. + - `"unsupported_image_media_type"` -### Beta Response Mcp Call Arguments Done Event + - `"empty_image_file"` -- `beta_response_mcp_call_arguments_done_event: object { arguments, item_id, output_index, 3 more }` + - `"failed_to_download_image"` - Emitted when the arguments for an MCP tool call are finalized. + - `"image_file_not_found"` - - `arguments: string` + - `message: string` - A JSON string containing the finalized arguments for the MCP tool call. + A human-readable description of the error. - - `item_id: string` + - `incomplete_details: object { reason }` - The unique identifier of the MCP tool call item being processed. + Details about why the response is incomplete. - - `output_index: number` + - `reason: optional "max_output_tokens" or "content_filter"` - The index of the output item in the response's output array. + The reason why the response is incomplete. - - `sequence_number: number` + - `"max_output_tokens"` - The sequence number of this event. + - `"content_filter"` - - `type: "response.mcp_call_arguments.done"` + - `instructions: string or array of BetaResponseInputItem` - The type of the event. Always 'response.mcp_call_arguments.done'. + A system (or developer) message inserted into the model's context. - - `agent: optional object { agent_name }` + When using 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. - The agent that owns this multi-agent streaming event. + - `union_member_0: string` - - `agent_name: string` + A text input to the model, equivalent to a text input with the + `developer` role. - The canonical name of the agent that produced this item. + - `Input item list: array of BetaResponseInputItem` -### Beta Response Mcp Call Completed Event + A list of one or many input items to the model, containing + different content types. -- `beta_response_mcp_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `beta_easy_input_message: object { content, role, phase, type }` - Emitted when an MCP tool call has completed successfully. + 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. - - `item_id: string` + - `content: string or BetaResponseInputMessageContentList` - The ID of the MCP tool call item that completed. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `output_index: number` + - `Text input: string` - The index of the output item that completed. + A text input to the model. - - `sequence_number: number` + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - The sequence number of this event. + A list of one or many input items to the model, containing different content + types. - - `type: "response.mcp_call.completed"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - The type of the event. Always 'response.mcp_call.completed'. + A text input to the model. - - `agent: optional object { agent_name }` + - `text: string` - The agent that owns this multi-agent streaming event. + The text input to the model. - - `agent_name: string` + - `type: "input_text"` - The canonical name of the agent that produced this item. + The type of the input item. Always `input_text`. -### Beta Response Mcp Call Failed Event + - `prompt_cache_breakpoint: optional object { mode }` -- `beta_response_mcp_call_failed_event: object { item_id, output_index, sequence_number, 2 more }` + 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. - Emitted when an MCP tool call has failed. + - `mode: "explicit"` - - `item_id: string` + The breakpoint mode. Always `explicit`. - The ID of the MCP tool call item that failed. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `output_index: number` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The index of the output item that failed. + - `detail: "low" or "high" or "auto" or "original"` - - `sequence_number: number` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The sequence number of this event. + - `"low"` - - `type: "response.mcp_call.failed"` + - `"high"` - The type of the event. Always 'response.mcp_call.failed'. + - `"auto"` - - `agent: optional object { agent_name }` + - `"original"` - The agent that owns this multi-agent streaming event. + - `type: "input_image"` - - `agent_name: string` + The type of the input item. Always `input_image`. - The canonical name of the agent that produced this item. + - `file_id: optional string` -### Beta Response Mcp Call In Progress Event + The ID of the file to be sent to the model. -- `beta_response_mcp_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + - `image_url: optional string` - Emitted when an MCP tool call is in progress. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `item_id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The unique identifier of the MCP tool call item being processed. + 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. - - `output_index: number` + - `mode: "explicit"` - The index of the output item in the response's output array. + The breakpoint mode. Always `explicit`. - - `sequence_number: number` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The sequence number of this event. + A file input to the model. - - `type: "response.mcp_call.in_progress"` + - `type: "input_file"` - The type of the event. Always 'response.mcp_call.in_progress'. + The type of the input item. Always `input_file`. - - `agent: optional object { agent_name }` + - `detail: optional "auto" or "low" or "high"` - The agent that owns this multi-agent streaming event. + 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`. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"low"` -### Beta Response Mcp List Tools Completed Event + - `"high"` -- `beta_response_mcp_list_tools_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `file_data: optional string` - Emitted when the list of available MCP tools has been successfully retrieved. + The content of the file to be sent to the model. - - `item_id: string` + - `file_id: optional string` - The ID of the MCP tool call item that produced this output. + The ID of the file to be sent to the model. - - `output_index: number` + - `file_url: optional string` - The index of the output item that was processed. + The URL of the file to be sent to the model. - - `sequence_number: number` + - `filename: optional string` - The sequence number of this event. + The name of the file to be sent to the model. - - `type: "response.mcp_list_tools.completed"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the event. Always 'response.mcp_list_tools.completed'. + 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. - - `agent: optional object { agent_name }` + - `mode: "explicit"` - The agent that owns this multi-agent streaming event. + The breakpoint mode. Always `explicit`. - - `agent_name: string` + - `role: "user" or "assistant" or "system" or "developer"` - The canonical name of the agent that produced this item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. -### Beta Response Mcp List Tools Failed Event + - `"user"` -- `beta_response_mcp_list_tools_failed_event: object { item_id, output_index, sequence_number, 2 more }` + - `"assistant"` - Emitted when the attempt to list available MCP tools has failed. + - `"system"` - - `item_id: string` + - `"developer"` - The ID of the MCP tool call item that failed. + - `phase: optional "commentary" or "final_answer"` - - `output_index: number` + 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. - The index of the output item that failed. + - `"commentary"` - - `sequence_number: number` + - `"final_answer"` - The sequence number of this event. + - `type: optional "message"` - - `type: "response.mcp_list_tools.failed"` + The type of the message input. Always `message`. - The type of the event. Always 'response.mcp_list_tools.failed'. + - `"message"` - - `agent: optional object { agent_name }` + - `message: object { content, role, agent, 2 more }` - The agent that owns this multi-agent streaming event. + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. - - `agent_name: string` + - `content: array of BetaResponseInputContent` - The canonical name of the agent that produced this item. + A list of one or many input items to the model, containing different content + types. -### Beta Response Mcp List Tools In Progress Event + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` -- `beta_response_mcp_list_tools_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + A text input to the model. - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `item_id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The ID of the MCP tool call item that is being processed. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `output_index: number` + A file input to the model. - The index of the output item that is being processed. + - `role: "user" or "system" or "developer"` - - `sequence_number: number` + The role of the message input. One of `user`, `system`, or `developer`. - The sequence number of this event. + - `"user"` - - `type: "response.mcp_list_tools.in_progress"` + - `"system"` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + - `"developer"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Output Audio - -- `beta_response_output_audio: object { data, transcript, type }` - - An audio output from the model. - - - `data: string` - - Base64-encoded audio data from the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `transcript: string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The transcript of the audio data from the model. + - `"in_progress"` - - `type: "output_audio"` + - `"completed"` - The type of the output audio. Always `output_audio`. + - `"incomplete"` -### Beta Response Output Item + - `type: optional "message"` -- `beta_response_output_item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` + The type of the message input. Always set to `message`. - An output message from the model. + - `"message"` - `beta_response_output_message: object { id, content, role, 4 more }` @@ -95461,7 +106251,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -95469,6 +106259,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -95543,58 +106335,36 @@ openai beta:responses compact \ The text that was retrieved from the file. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + 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. - - `arguments: string` + - `id: string` - A JSON string of the arguments to pass to the function. + The unique ID of the computer call. - `call_id: string` - The unique ID of the function tool call generated by the model. - - - `name: string` - - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `id: optional string` - - The unique ID of the function tool call. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` + An identifier used when responding to the tool call with output. - The execution context that produced this tool call. + - `pending_safety_checks: array of object { id, code, message }` - - `direct: object { type }` + The pending safety checks for the computer call. - - `program: object { caller_id, type }` + - `id: string` - - `caller_id: string` + The ID of the pending safety check. - The call ID of the program item that produced this tool call. + - `code: optional string` - - `type: "program"` + The type of the pending safety check. - - `namespace: optional string` + - `message: optional string` - The namespace of the function to run. + Details about the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -95605,333 +106375,278 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - - `id: string` - - The unique ID of the function call tool output. - - - `call_id: string` + - `type: "computer_call"` - The unique ID of the function tool call generated by the model. + The type of the computer call. Always `computer_call`. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"computer_call"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `string output: string` + A click action. - A string of the output of the function call. + - `click: object { button, type, x, 2 more }` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A click action. - Text, image, or file output of the function call. + - `button: "left" or "right" or "wheel" or 2 more` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - A text input to the model. + - `"left"` - - `text: string` + - `"right"` - The text input to the model. + - `"wheel"` - - `type: "input_text"` + - `"back"` - The type of the input item. Always `input_text`. + - `"forward"` - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "click"` - 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. + Specifies the event type. For a click action, this property is always `click`. - - `mode: "explicit"` + - `x: number` - The breakpoint mode. Always `explicit`. + The x-coordinate where the click occurred. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `y: number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The y-coordinate where the click occurred. - - `detail: "low" or "high" or "auto" or "original"` + - `keys: optional array of string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The keys being held while clicking. - - `"low"` + - `double_click: object { keys, type, x, y }` - - `"high"` + A double click action. - - `"auto"` + - `keys: array of string` - - `"original"` + The keys being held while double-clicking. - - `type: "input_image"` + - `type: "double_click"` - The type of the input item. Always `input_image`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `file_id: optional string` + - `x: number` - The ID of the file to be sent to the model. + The x-coordinate where the double click occurred. - - `image_url: optional string` + - `y: number` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The y-coordinate where the double click occurred. - - `prompt_cache_breakpoint: optional object { mode }` + - `drag: object { path, type, keys }` - 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. + A drag action. - - `mode: "explicit"` + - `path: array of object { x, y }` - The breakpoint mode. Always `explicit`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - A file input to the model. + - `x: number` - - `type: "input_file"` + The x-coordinate. - The type of the input item. Always `input_file`. + - `y: number` - - `detail: optional "auto" or "low" or "high"` + The y-coordinate. - 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`. + - `type: "drag"` - - `"auto"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"low"` + - `keys: optional array of string` - - `"high"` + The keys being held while dragging the mouse. - - `file_data: optional string` + - `keypress: object { keys, type }` - The content of the file to be sent to the model. + A collection of keypresses the model would like to perform. - - `file_id: optional string` + - `keys: array of string` - The ID of the file to be sent to the model. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `file_url: optional string` + - `type: "keypress"` - The URL of the file to be sent to the model. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `filename: optional string` + - `move: object { type, x, y, keys }` - The name of the file to be sent to the model. + A mouse move action. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "move"` - 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. + Specifies the event type. For a move action, this property is always set to `move`. - - `mode: "explicit"` + - `x: number` - The breakpoint mode. Always `explicit`. + The x-coordinate to move to. - - `status: "in_progress" or "completed" or "incomplete"` + - `y: number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The y-coordinate to move to. - - `"in_progress"` + - `keys: optional array of string` - - `"completed"` + The keys being held while moving the mouse. - - `"incomplete"` + - `screenshot: object { type }` - - `type: "function_call_output"` + A screenshot action. - The type of the function tool call output. Always `function_call_output`. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `agent: optional object { agent_name }` + A scroll action. - The agent that produced this item. + - `scroll_x: number` - - `agent_name: string` + The horizontal scroll distance. - The canonical name of the agent that produced this item. + - `scroll_y: number` - - `caller: optional object { type } or object { caller_id, type }` + The vertical scroll distance. - The execution context that produced this tool call. + - `type: "scroll"` - - `direct: object { type }` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `program: object { caller_id, type }` + - `x: number` - - `caller_id: string` + The x-coordinate where the scroll occurred. - The call ID of the program item that produced this tool call. + - `y: number` - - `type: "program"` + The y-coordinate where the scroll occurred. - The caller type. Always `program`. + - `keys: optional array of string` - - `created_by: optional string` + The keys being held while scrolling. - The identifier of the actor that created the item. + - `type: object { text, type }` - - `agent_message: object { id, author, content, 3 more }` + An action to type in text. - - `id: string` + - `text: string` - The unique ID of the agent message. + The text to type. - - `author: string` + - `type: "type"` - The sending agent identity. + Specifies the event type. For a type action, this property is always set to `type`. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `wait: object { type }` - Encrypted content sent between agents. + A wait action. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `actions: optional array of BetaComputerAction` - A text input to the model. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `click: object { button, type, x, 2 more }` - A text output from the model. + A click action. - - `text: object { text, type }` + - `double_click: object { keys, type, x, y }` - A text content. + A double click action. - - `text: string` + - `drag: object { path, type, keys }` - - `type: "text"` + A drag action. - - `summary_text: object { text, type }` + - `keypress: object { keys, type }` - A summary text from the model. + A collection of keypresses the model would like to perform. - - `text: string` + - `move: object { type, x, y, keys }` - A summary of the reasoning output from the model so far. + A mouse move action. - - `type: "summary_text"` + - `screenshot: object { type }` - The type of the object. Always `summary_text`. + A screenshot action. - - `reasoning_text: object { text, type }` + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - Reasoning text from the model. + A scroll action. - - `text: string` + - `type: object { text, type }` - The reasoning text from the model. + An action to type in text. - - `type: "reasoning_text"` + - `wait: object { type }` - The type of the reasoning text. Always `reasoning_text`. + A wait action. - - `beta_response_output_refusal: object { refusal, type }` + - `agent: optional object { agent_name }` - A refusal from the model. + The agent that produced this item. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `agent_name: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The canonical name of the agent that produced this item. - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `computer_call_output: object { call_id, output, type, 4 more }` - A screenshot of a computer. + The output of a computer tool call. - - `detail: "low" or "high" or "auto" or "original"` + - `call_id: string` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The ID of the computer tool call that produced the output. - - `"low"` + - `output: object { type, file_id, image_url }` - - `"high"` + A computer screenshot image used with the computer use tool. - - `"auto"` + - `type: "computer_screenshot"` - - `"original"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `file_id: string` + - `file_id: optional string` The identifier of an uploaded file that contains the screenshot. - - `image_url: string` + - `image_url: optional string` The URL of the screenshot image. - - `type: "computer_screenshot"` - - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `encrypted_content: object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `recipient: string` - - The destination agent identity. - - - `type: "agent_message"` - - The type of the item. Always `agent_message`. + - `type: "computer_call_output"` - - `agent: optional object { agent_name }` + The type of the computer tool call output. Always `computer_call_output`. - The agent that produced this item. + - `id: optional string` - - `agent_name: string` + The ID of the computer tool call output. - The canonical name of the agent that produced this item. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `multi_agent_call: object { id, action, arguments, 3 more }` + The safety checks reported by the API that have been acknowledged by the developer. - `id: string` - The unique ID of the multi-agent call item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action to execute. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `arguments: string` - - The JSON string of arguments generated for the action. + The ID of the pending safety check. - - `call_id: string` + - `code: optional string` - The unique ID linking this call to its output. + The type of the pending safety check. - - `type: "multi_agent_call"` + - `message: optional string` - The type of the multi-agent call. Always `multi_agent_call`. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -95941,61 +106656,15 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: string` - - The unique ID of the multi-agent call. - - - `output: array of BetaResponseOutputText` - - Text output returned by the multi-agent action. - - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - The annotations of the text output. - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - - `type: "multi_agent_call_output"` - - The type of the multi-agent result. Always `multi_agent_call_output`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The agent that produced this item. + - `"in_progress"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` - `beta_response_function_web_search: object { id, action, status, 2 more }` @@ -96091,330 +106760,303 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - 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. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `call_id: string` - An identifier used when responding to the tool call with output. - - - `pending_safety_checks: array of object { id, code, message }` - - The pending safety checks for the computer call. - - - `id: string` - - The ID of the pending safety check. - - - `code: optional string` - - The type of the pending safety check. - - - `message: optional string` + The unique ID of the function tool call generated by the model. - Details about the pending safety check. + - `name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The name of the function to run. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "function_call"` - - `"in_progress"` + The type of the function tool call. Always `function_call`. - - `"completed"` + - `id: optional string` - - `"incomplete"` + The unique ID of the function tool call. - - `type: "computer_call"` + - `agent: optional object { agent_name }` - The type of the computer call. Always `computer_call`. + The agent that produced this item. - - `"computer_call"` + - `agent_name: string` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + The canonical name of the agent that produced this item. - A click action. + - `caller: optional object { type } or object { caller_id, type }` - - `click: object { button, type, x, 2 more }` + The execution context that produced this tool call. - A click action. + - `direct: object { type }` - - `button: "left" or "right" or "wheel" or 2 more` + - `program: object { caller_id, type }` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `caller_id: string` - - `"left"` + The call ID of the program item that produced this tool call. - - `"right"` + - `type: "program"` - - `"wheel"` + - `namespace: optional string` - - `"back"` + The namespace of the function to run. - - `"forward"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "click"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Specifies the event type. For a click action, this property is always `click`. + - `"in_progress"` - - `x: number` + - `"completed"` - The x-coordinate where the click occurred. + - `"incomplete"` - - `y: number` + - `function_call_output: object { call_id, output, type, 4 more }` - The y-coordinate where the click occurred. + The output of a function tool call. - - `keys: optional array of string` + - `call_id: string` - The keys being held while clicking. + The unique ID of the function tool call generated by the model. - - `double_click: object { keys, type, x, y }` + - `output: string or BetaResponseFunctionCallOutputItemList` - A double click action. + Text, image, or file output of the function tool call. - - `keys: array of string` + - `union_member_0: string` - The keys being held while double-clicking. + A JSON string of the output of the function tool call. - - `type: "double_click"` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - Specifies the event type. For a double click action, this property is always set to `double_click`. + An array of content outputs (text, image, file) for the function tool call. - - `x: number` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - The x-coordinate where the double click occurred. + A text input to the model. - - `y: number` + - `text: string` - The y-coordinate where the double click occurred. + The text input to the model. - - `drag: object { path, type, keys }` + - `type: "input_text"` - A drag action. + The type of the input item. Always `input_text`. - - `path: array of object { x, y }` + - `prompt_cache_breakpoint: optional object { mode }` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + 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. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `mode: "explicit"` - - `x: number` + The breakpoint mode. Always `explicit`. - The x-coordinate. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `y: number` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The y-coordinate. + - `type: "input_image"` - - `type: "drag"` + The type of the input item. Always `input_image`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `detail: optional "low" or "high" or "auto" or "original"` - - `keys: optional array of string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The keys being held while dragging the mouse. + - `"low"` - - `keypress: object { keys, type }` + - `"high"` - A collection of keypresses the model would like to perform. + - `"auto"` - - `keys: array of string` + - `"original"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `file_id: optional string` - - `type: "keypress"` + The ID of the file to be sent to the model. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `image_url: optional string` - - `move: object { type, x, y, keys }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - A mouse move action. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "move"` + 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. - Specifies the event type. For a move action, this property is always set to `move`. + - `mode: "explicit"` - - `x: number` + The breakpoint mode. Always `explicit`. - The x-coordinate to move to. + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` - - `y: number` + A file input to the model. - The y-coordinate to move to. + - `type: "input_file"` - - `keys: optional array of string` + The type of the input item. Always `input_file`. - The keys being held while moving the mouse. + - `detail: optional "auto" or "low" or "high"` - - `screenshot: object { type }` + 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`. - A screenshot action. + - `"auto"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"low"` - A scroll action. + - `"high"` - - `scroll_x: number` + - `file_data: optional string` - The horizontal scroll distance. + The base64-encoded data of the file to be sent to the model. - - `scroll_y: number` + - `file_id: optional string` - The vertical scroll distance. + The ID of the file to be sent to the model. - - `type: "scroll"` + - `file_url: optional string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The URL of the file to be sent to the model. - - `x: number` + - `filename: optional string` - The x-coordinate where the scroll occurred. + The name of the file to be sent to the model. - - `y: number` + - `prompt_cache_breakpoint: optional object { mode }` - The y-coordinate where the scroll occurred. + 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. - - `keys: optional array of string` + - `mode: "explicit"` - The keys being held while scrolling. + The breakpoint mode. Always `explicit`. - - `type: object { text, type }` + - `type: "function_call_output"` - An action to type in text. + The type of the function tool call output. Always `function_call_output`. - - `text: string` + - `id: optional string` - The text to type. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `type: "type"` + - `agent: optional object { agent_name }` - Specifies the event type. For a type action, this property is always set to `type`. + The agent that produced this item. - - `wait: object { type }` + - `agent_name: string` - A wait action. + The canonical name of the agent that produced this item. - - `actions: optional array of BetaComputerAction` + - `caller: optional object { type } or object { caller_id, type }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The execution context that produced this tool call. - - `click: object { button, type, x, 2 more }` + - `direct: object { type }` - A click action. + - `program: object { caller_id, type }` - - `double_click: object { keys, type, x, y }` + - `caller_id: string` - A double click action. + The call ID of the program item that produced this tool call. - - `drag: object { path, type, keys }` + - `type: "program"` - A drag action. + The caller type. Always `program`. - - `keypress: object { keys, type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A collection of keypresses the model would like to perform. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `move: object { type, x, y, keys }` + - `"in_progress"` - A mouse move action. + - `"completed"` - - `screenshot: object { type }` + - `"incomplete"` - A screenshot action. + - `agent_message: object { author, content, recipient, 3 more }` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + A message routed between agents. - A scroll action. + - `author: string` - - `type: object { text, type }` + The sending agent identity. - An action to type in text. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `wait: object { type }` + Plaintext, image, or encrypted content sent between agents. - A wait action. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text input to the model. - The canonical name of the agent that produced this item. + - `type: "input_text"` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + The type of the input item. Always `input_text`. - - `id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The unique ID of the computer call tool output. + 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. - - `call_id: string` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - The ID of the computer tool call that produced the output. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `output: object { type, file_id, image_url }` + - `type: "input_image"` - A computer screenshot image used with the computer use tool. + The type of the input item. Always `input_image`. - - `type: "computer_screenshot"` + - `detail: optional "low" or "high" or "auto" or "original"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `file_id: optional string` - The identifier of an uploaded file that contains the screenshot. + The ID of the file to be sent to the model. - `image_url: optional string` - The URL of the screenshot image. - - - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"completed"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"incomplete"` + 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. - - `"failed"` + - `encrypted_content: object { encrypted_content, type }` - - `"in_progress"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `type: "computer_call_output"` + - `encrypted_content: string` - The type of the computer tool call output. Always `computer_call_output`. + Opaque encrypted content. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "encrypted_content"` - The safety checks reported by the API that have been acknowledged by the - developer. + The type of the input item. Always `encrypted_content`. - - `id: string` + - `recipient: string` - The ID of the pending safety check. + The destination agent identity. - - `code: optional string` + - `type: "agent_message"` - The type of the pending safety check. + The item type. Always `agent_message`. - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of this agent message item. - `agent: optional object { agent_name }` @@ -96424,36 +107066,39 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - The identifier of the actor that created the item. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + The multi-agent action that was executed. - 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). + - `"spawn_agent"` - - `id: string` + - `"interrupt_agent"` - The unique identifier of the reasoning content. + - `"list_agents"` - - `summary: array of object { text, type }` + - `"send_message"` - Reasoning summary content. + - `"followup_task"` - - `text: string` + - `"wait_agent"` - A summary of the reasoning output from the model so far. + - `arguments: string` - - `type: "summary_text"` + The action arguments as a JSON string. - The type of the object. Always `summary_text`. + - `call_id: string` - - `type: "reasoning"` + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. + + - `id: optional string` - The type of the object. Always `reasoning`. + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -96463,133 +107108,139 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - Reasoning text content. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `text: string` + The multi-agent action that produced this result. - The reasoning text from the model. + - `"spawn_agent"` - - `type: "reasoning_text"` + - `"interrupt_agent"` - The type of the reasoning text. Always `reasoning_text`. + - `"list_agents"` - - `encrypted_content: optional string` + - `"send_message"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"followup_task"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"wait_agent"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `call_id: string` - - `"in_progress"` + The unique ID of the multi-agent call. - - `"completed"` + - `output: array of object { text, type, annotations }` - - `"incomplete"` + Text output returned by the multi-agent action. - - `program: object { id, call_id, code, 3 more }` + - `text: string` - - `id: string` + The text content. - The unique ID of the program item. + - `type: "output_text"` - - `call_id: string` + The content type. Always `output_text`. - The stable call ID of the program item. + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - `code: string` + Citations associated with the text content. - The JavaScript source executed by programmatic tool calling. + - `union_member_0: array of object { file_id, filename, index, type }` - - `fingerprint: string` + - `file_id: string` - Opaque program replay fingerprint that must be round-tripped. + The ID of the file. - - `type: "program"` + - `filename: string` - The type of the item. Always `program`. + The filename of the file cited. - - `agent: optional object { agent_name }` + - `index: number` - The agent that produced this item. + The index of the file in the list of files. - - `agent_name: string` + - `type: "file_citation"` - The canonical name of the agent that produced this item. + The citation type. Always `file_citation`. - - `program_output: object { id, call_id, result, 3 more }` + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - `id: string` + - `end_index: number` - The unique ID of the program output item. + The index of the last character of the citation in the message. - - `call_id: string` + - `start_index: number` - The call ID of the program item. + The index of the first character of the citation in the message. - - `result: string` + - `title: string` - The result produced by the program item. + The title of the cited resource. - - `status: "completed" or "incomplete"` + - `type: "url_citation"` - The terminal status of the program output item. + The citation type. Always `url_citation`. - - `"completed"` + - `url: string` - - `"incomplete"` + The URL of the cited resource. - - `type: "program_output"` + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - The type of the item. Always `program_output`. + - `container_id: string` - - `agent: optional object { agent_name }` + The ID of the container. - The agent that produced this item. + - `end_index: number` - - `agent_name: string` + The index of the last character of the citation in the message. - The canonical name of the agent that produced this item. + - `file_id: string` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + The ID of the container file. - - `id: string` + - `filename: string` - The unique ID of the tool search call item. + The filename of the container file cited. - - `arguments: unknown` + - `start_index: number` - Arguments used for the tool search call. + The index of the first character of the citation in the message. - - `call_id: string` + - `type: "container_file_citation"` - The unique ID of the tool search call generated by the model. + The citation type. Always `container_file_citation`. - - `execution: "server" or "client"` + - `type: "multi_agent_call_output"` - Whether tool search was executed by the server or by the client. + The item type. Always `multi_agent_call_output`. - - `"server"` + - `id: optional string` - - `"client"` + The unique ID of this multi-agent call output. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` - The status of the tool search call item that was recorded. + The agent that produced this item. - - `"in_progress"` + - `agent_name: string` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `tool_search_call: object { arguments, type, id, 4 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. - `type: "tool_search_call"` - The type of the item. Always `tool_search_call`. + The item type. Always `tool_search_call`. + + - `id: optional string` + + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -96599,21 +107250,11 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - - `id: string` - - The unique ID of the tool search output item. - - - `call_id: string` + - `call_id: optional string` The unique ID of the tool search call generated by the model. - - `execution: "server" or "client"` + - `execution: optional "server" or "client"` Whether tool search was executed by the server or by the client. @@ -96621,9 +107262,9 @@ openai beta:responses compact \ - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output item that was recorded. + The status of the tool search call. - `"in_progress"` @@ -96631,9 +107272,11 @@ openai beta:responses compact \ - `"incomplete"` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + - `tools: array of BetaTool` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -96728,7 +107371,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -96738,7 +107381,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -96785,7 +107432,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -96795,7 +107442,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -97413,261 +108064,1119 @@ openai beta:responses compact \ Use a local computer environment. - - `skills: optional array of BetaLocalSkill` + - `skills: optional array of BetaLocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `beta_container_reference: object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `text: object { type }` + + Unconstrained free-form text. + + - `grammar: object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The namespace name used in tool calls (for example, `crm`). + + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + + The function/custom tools available inside this namespace. + + - `function: object { name, type, allowed_callers, 5 more }` + + - `name: string` + + - `type: "function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: optional unknown` + + - `strict: optional boolean` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `id: optional string` + + The unique ID of this tool search output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `additional_tools: object { role, tools, type, 2 more }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `tools: array of BetaTool` + + A list of additional tools made available at this item. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `id: optional string` + + The unique ID of this additional tools item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `id: optional string` + + The ID of the compaction item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `image_generation_call: object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `logs: object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `image: object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call: object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `local_shell_call_output: object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call: object { action, call_id, type, 5 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `beta_local_environment: object { type, skills }` + + - `beta_container_reference: object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `shell_call_output: object { call_id, output, type, 5 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `timeout: object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `exit: object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `direct: object { type }` + + - `program: object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `apply_patch_call: object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `create_file: object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `delete_file: object { path, type }` - An optional list of skills. + Instruction for deleting an existing file via the apply_patch tool. - - `description: string` + - `path: string` - The description of the skill. + Path of the file to delete relative to the workspace root. - - `name: string` + - `type: "delete_file"` - The name of the skill. + The operation type. Always `delete_file`. - - `path: string` + - `update_file: object { diff, path, type }` - The path to the directory containing the skill. + Instruction for updating an existing file via the apply_patch tool. - - `beta_container_reference: object { container_id, type }` + - `diff: string` - - `container_id: string` + Unified diff content to apply to the existing file. - The ID of the referenced container. + - `path: string` - - `type: "container_reference"` + Path of the file to update relative to the workspace root. - References a container created with the /v1/containers endpoint + - `type: "update_file"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The operation type. Always `update_file`. - 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) + - `status: "in_progress" or "completed"` - - `name: string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The name of the custom tool, used to identify it in tool calls. + - `"in_progress"` - - `type: "custom"` + - `"completed"` - The type of the custom tool. Always `custom`. + - `type: "apply_patch_call"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the item. Always `apply_patch_call`. - The tool invocation context(s). + - `id: optional string` - - `"direct"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"programmatic"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that produced this item. - Whether this tool should be deferred and discovered via tool search. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - Optional description of the custom tool, used to provide more context. + - `caller: optional object { type } or object { caller_id, type }` - - `format: optional object { type } or object { definition, syntax, type }` + The execution context that produced this tool call. - The input format for the custom tool. Default is unconstrained text. + - `direct: object { type }` - - `text: object { type }` + - `program: object { caller_id, type }` - Unconstrained free-form text. + - `caller_id: string` - - `grammar: object { definition, syntax, type }` + The call ID of the program item that produced this tool call. - A grammar defined by the user. + - `type: "program"` - - `definition: string` + The caller type. Always `program`. - The grammar definition. + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - - `syntax: "lark" or "regex"` + The streamed output emitted by an apply patch tool call. - The syntax of the grammar definition. One of `lark` or `regex`. + - `call_id: string` - - `"lark"` + The unique ID of the apply patch tool call generated by the model. - - `"regex"` + - `status: "completed" or "failed"` - - `type: "grammar"` + The status of the apply patch tool call output. One of `completed` or `failed`. - Grammar format. Always `grammar`. + - `"completed"` - - `beta_namespace_tool: object { description, name, tools, type }` + - `"failed"` - Groups function/custom tools under a shared namespace. + - `type: "apply_patch_call_output"` - - `description: string` + The type of the item. Always `apply_patch_call_output`. - A description of the namespace shown to the model. + - `id: optional string` - - `name: string` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The namespace name used in tool calls (for example, `crm`). + - `agent: optional object { agent_name }` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + The agent that produced this item. - The function/custom tools available inside this namespace. + - `agent_name: string` - - `function: object { name, type, allowed_callers, 5 more }` + The canonical name of the agent that produced this item. - - `name: string` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "function"` + The execution context that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `direct: object { type }` - The tool invocation context(s). + - `program: object { caller_id, type }` - - `"direct"` + - `caller_id: string` - - `"programmatic"` + The call ID of the program item that produced this tool call. - - `defer_loading: optional boolean` + - `type: "program"` - Whether this function should be deferred and discovered via tool search. + The caller type. Always `program`. - - `description: optional string` + - `output: optional string` - - `output_schema: optional map[unknown]` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `parameters: optional unknown` + A list of tools available on an MCP server. - - `strict: optional boolean` + - `id: string` - 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. + The unique ID of the list. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `server_label: string` - 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) + The label of the MCP server. - - `name: string` + - `tools: array of object { input_schema, name, annotations, description }` - The name of the custom tool, used to identify it in tool calls. + The tools available on the server. - - `type: "custom"` + - `input_schema: unknown` - The type of the custom tool. Always `custom`. + The JSON schema describing the tool's input. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `name: string` - The tool invocation context(s). + The name of the tool. - - `defer_loading: optional boolean` + - `annotations: optional unknown` - Whether this tool should be deferred and discovered via tool search. + Additional annotations about the tool. - `description: optional string` - Optional description of the custom tool, used to provide more context. + The description of the tool. - - `format: optional object { type } or object { definition, syntax, type }` + - `type: "mcp_list_tools"` - The input format for the custom tool. Default is unconstrained text. + The type of the item. Always `mcp_list_tools`. - - `type: "namespace"` + - `agent: optional object { agent_name }` - The type of the tool. Always `namespace`. + The agent that produced this item. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `agent_name: string` - Hosted or BYOT tool search configuration for deferred tools. + The canonical name of the agent that produced this item. - - `type: "tool_search"` + - `error: optional string` - The type of the tool. Always `tool_search`. + Error message if the server could not list tools. - - `description: optional string` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - Description shown to the model for a client-executed tool search tool. + A request for human approval of a tool invocation. - - `execution: optional "server" or "client"` + - `id: string` - Whether tool search is executed by the server or by the client. + The unique ID of the approval request. - - `"server"` + - `arguments: string` - - `"client"` + A JSON string of arguments for the tool. - - `parameters: optional unknown` + - `name: string` - Parameter schema for a client-executed tool search tool. + The name of the tool to run. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `server_label: string` - 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). + The label of the MCP server making the request. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `type: "mcp_approval_request"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The type of the item. Always `mcp_approval_request`. - - `"web_search_preview"` + - `agent: optional object { agent_name }` - - `"web_search_preview_2025_03_11"` + The agent that produced this item. - - `search_content_types: optional array of "text" or "image"` + - `agent_name: string` - - `"text"` + The canonical name of the agent that produced this item. - - `"image"` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - - `search_context_size: optional "low" or "medium" or "high"` + A response to an MCP approval request. - 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. + - `approval_request_id: string` - - `"low"` + The ID of the approval request being answered. - - `"medium"` + - `approve: boolean` - - `"high"` + Whether the request was approved. - - `user_location: optional object { type, city, country, 2 more }` + - `type: "mcp_approval_response"` - The user's location. + The type of the item. Always `mcp_approval_response`. - - `type: "approximate"` + - `id: optional string` - The type of location approximation. Always `approximate`. + The unique ID of the approval response - - `city: optional string` + - `agent: optional object { agent_name }` - Free text input for the city of the user, e.g. `San Francisco`. + The agent that produced this item. - - `country: optional string` + - `agent_name: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The canonical name of the agent that produced this item. - - `region: optional string` + - `reason: optional string` - Free text input for the region of the user, e.g. `California`. + Optional reason for the decision. - - `timezone: optional string` + - `mcp_call: object { id, arguments, name, 7 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + An invocation of a tool on an MCP server. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `id: string` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the tool call. - - `type: "apply_patch"` + - `arguments: string` - The type of the tool. Always `apply_patch`. + A JSON string of the arguments passed to the tool. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `name: string` - The tool invocation context(s). + The name of the tool that was run. - - `"direct"` + - `server_label: string` - - `"programmatic"` + The label of the MCP server running the tool. - - `type: "tool_search_output"` + - `type: "mcp_call"` - The type of the item. Always `tool_search_output`. + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` @@ -97677,131 +109186,133 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `approval_request_id: optional string` - The identifier of the actor that created the item. + 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. - - `additional_tools: object { id, role, tools, 2 more }` + - `error: optional string` - - `id: string` + The error from the tool call, if any. - The unique ID of the additional tools item. + - `output: optional string` - - `role: "unknown" or "user" or "assistant" or 5 more` + The output from the tool call. - The role that provided the additional tools. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"unknown"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `"calling"` - - `"discriminator"` + - `"failed"` - - `"developer"` + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `"tool"` + The output of a custom tool call from your code, being sent back to the model. - - `tools: array of BetaTool` + - `call_id: string` - The additional tool definitions made available at this item. + The call ID, used to map this custom tool call output to a custom tool call. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - 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). + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `string output: string` - 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). + A string of the output of the custom tool call. - - `beta_computer_tool: object { type }` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Text, image, or file output of the custom tool call. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A text input to the model. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `text: string` - 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). + The text input to the model. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `type: "input_text"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The type of the input item. Always `input_text`. - - `code_interpreter: object { container, type, allowed_callers }` + - `prompt_cache_breakpoint: optional object { mode }` - A tool that runs Python code to help generate a response to a prompt. + 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. - - `programmatic_tool_calling: object { type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `image_generation: object { type, action, background, 9 more }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - A tool that generates images using the GPT image models. + - `detail: "low" or "high" or "auto" or "original"` - - `local_shell: object { type }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A tool that allows the model to execute shell commands in a local environment. + - `type: "input_image"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The type of the input item. Always `input_image`. - A tool that allows the model to execute shell commands. + - `file_id: optional string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The ID of the file to be sent to the model. - 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) + - `image_url: optional string` - - `beta_namespace_tool: object { description, name, tools, type }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Groups function/custom tools under a shared namespace. + - `prompt_cache_breakpoint: optional object { mode }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + 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. - Hosted or BYOT tool search configuration for deferred tools. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + A file input to the model. - 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: "input_file"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The type of the input item. Always `input_file`. - Allows the assistant to create, delete, or update files using unified diffs. + - `detail: optional "auto" or "low" or "high"` - - `type: "additional_tools"` + 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`. - The type of the item. Always `additional_tools`. + - `file_data: optional string` - - `agent: optional object { agent_name }` + The content of the file to be sent to the model. - The agent that produced this item. + - `file_id: optional string` - - `agent_name: string` + The ID of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `file_url: optional string` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + The URL of the file to be sent to the model. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `filename: optional string` - - `id: string` + The name of the file to be sent to the model. - The unique ID of the compaction item. + - `prompt_cache_breakpoint: optional object { mode }` - - `encrypted_content: string` + 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. - The encrypted content that was produced by compaction. + - `type: "custom_tool_call_output"` - - `type: "compaction"` + The type of the custom tool call output. Always `custom_tool_call_output`. - The type of the item. Always `compaction`. + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. - `agent: optional object { agent_name }` @@ -97811,108 +109322,95 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `image_generation_call: object { id, result, status, 2 more }` - - An image generation request made by the model. - - - `id: string` - - The unique ID of the image generation call. - - - `result: string` + - `caller: optional object { type } or object { caller_id, type }` - The generated image encoded in base64. + The execution context that produced this tool call. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `direct: object { type }` - The status of the image generation call. + - `program: object { caller_id, type }` - - `"in_progress"` + - `caller_id: string` - - `"completed"` + The call ID of the program item that produced this tool call. - - `"generating"` + - `type: "program"` - - `"failed"` + The caller type. Always `program`. - - `type: "image_generation_call"` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - The type of the image generation call. Always `image_generation_call`. + A call to a custom tool created by the model. - - `agent: optional object { agent_name }` + - `call_id: string` - The agent that produced this item. + An identifier used to map this custom tool call to a tool call output. - - `agent_name: string` + - `input: string` - The canonical name of the agent that produced this item. + The input for the custom tool call generated by the model. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `name: string` - A tool call to run code. + The name of the custom tool being called. - - `id: string` + - `type: "custom_tool_call"` - The unique ID of the code interpreter tool call. + The type of the custom tool call. Always `custom_tool_call`. - - `code: string` + - `id: optional string` - The code to run, or null if not available. + The unique ID of the custom tool call in the OpenAI platform. - - `container_id: string` + - `agent: optional object { agent_name }` - The ID of the container used to run the code. + The agent that produced this item. - - `outputs: array of object { logs, type } or object { type, url }` + - `agent_name: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The canonical name of the agent that produced this item. - - `logs: object { logs, type }` + - `caller: optional object { type } or object { caller_id, type }` - The logs output from the code interpreter. + The execution context that produced this tool call. - - `logs: string` + - `direct: object { type }` - The logs output from the code interpreter. + - `program: object { caller_id, type }` - - `type: "logs"` + - `caller_id: string` - The type of the output. Always `logs`. + The call ID of the program item that produced this tool call. - - `image: object { type, url }` + - `type: "program"` - The image output from the code interpreter. + - `namespace: optional string` - - `type: "image"` + The namespace of the custom tool being called. - The type of the output. Always `image`. + - `compaction_trigger: object { type, agent }` - - `url: string` + Compacts the current context. Must be the final input item. - The URL of the image output from the code interpreter. + - `type: "compaction_trigger"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The type of the item. Always `compaction_trigger`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `agent: optional object { agent_name }` - - `"in_progress"` + The agent that produced this item. - - `"completed"` + - `agent_name: string` - - `"incomplete"` + The canonical name of the agent that produced this item. - - `"interpreting"` + - `item_reference: object { id, agent, type }` - - `"failed"` + An internal identifier for an item to reference. - - `type: "code_interpreter_call"` + - `id: string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The ID of the item to reference. - `agent: optional object { agent_name }` @@ -97922,59 +109420,67 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `type: optional "item_reference"` - A tool call to run a command on the local shell. + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `program: object { id, call_id, code, 3 more }` - `id: string` - The unique ID of the local shell call. + The unique ID of this program item. - - `action: object { command, env, type, 3 more }` + - `call_id: string` - Execute a shell command on the server. + The stable call ID of the program item. - - `command: array of string` + - `code: string` - The command to run. + The JavaScript source executed by programmatic tool calling. - - `env: map[string]` + - `fingerprint: string` - Environment variables to set for the command. + Opaque program replay fingerprint that must be round-tripped. - - `type: "exec"` + - `type: "program"` - The type of the local shell action. Always `exec`. + The item type. Always `program`. - - `timeout_ms: optional number` + - `agent: optional object { agent_name }` - Optional timeout in milliseconds for the command. + The agent that produced this item. - - `user: optional string` + - `agent_name: string` - Optional user to run the command as. + The canonical name of the agent that produced this item. - - `working_directory: optional string` + - `program_output: object { id, call_id, result, 3 more }` - Optional working directory to run the command in. + - `id: string` + + The unique ID of this program output item. - `call_id: string` - The unique ID of the local shell tool call generated by the model. + The call ID of the program item. - - `status: "in_progress" or "completed" or "incomplete"` + - `result: string` - The status of the local shell call. + The result produced by the program item. - - `"in_progress"` + - `status: "completed" or "incomplete"` + + The terminal status of the program output. - `"completed"` - `"incomplete"` - - `type: "local_shell_call"` + - `type: "program_output"` - The type of the local shell call. Always `local_shell_call`. + The item type. Always `program_output`. - `agent: optional object { agent_name }` @@ -97984,341 +109490,383 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `metadata: map[string]` - The output of a local shell tool call. + 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. - - `id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The unique ID of the local shell tool call generated by the model. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `output: string` + Model ID used to generate the response, like `gpt-4o` 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. - A JSON string of the output of the local shell tool call. + - `"gpt-5.6-sol"` - - `type: "local_shell_call_output"` + - `"gpt-5.6-terra"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"gpt-5.6-luna"` - - `agent: optional object { agent_name }` + - `"gpt-5.4"` - The agent that produced this item. + - `"gpt-5.4-mini"` - - `agent_name: string` + - `"gpt-5.4-nano"` - The canonical name of the agent that produced this item. + - `"gpt-5.4-mini-2026-03-17"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-5.4-nano-2026-03-17"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"gpt-5.3-chat-latest"` - - `"in_progress"` + - `"gpt-5.2"` - - `"completed"` + - `"gpt-5.2-2025-12-11"` - - `"incomplete"` + - `"gpt-5.2-chat-latest"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `"gpt-5.2-pro"` - A tool call that executes one or more shell commands in a managed environment. + - `"gpt-5.2-pro-2025-12-11"` - - `id: string` + - `"gpt-5.1"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"gpt-5.1-2025-11-13"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"gpt-5.1-codex"` - The shell commands and limits that describe how to run the tool call. + - `"gpt-5.1-mini"` - - `commands: array of string` + - `"gpt-5.1-chat-latest"` - - `max_output_length: number` + - `"gpt-5"` - Optional maximum number of characters to return from each command. + - `"gpt-5-mini"` - - `timeout_ms: number` + - `"gpt-5-nano"` - Optional timeout in milliseconds for the commands. + - `"gpt-5-2025-08-07"` - - `call_id: string` + - `"gpt-5-mini-2025-08-07"` - The unique ID of the shell tool call generated by the model. + - `"gpt-5-nano-2025-08-07"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `"gpt-5-chat-latest"` - Represents the use of a local environment to perform shell actions. + - `"gpt-4.1"` - - `beta_response_local_environment: object { type }` + - `"gpt-4.1-mini"` - Represents the use of a local environment to perform shell actions. + - `"gpt-4.1-nano"` - - `type: "local"` + - `"gpt-4.1-2025-04-14"` - The environment type. Always `local`. + - `"gpt-4.1-mini-2025-04-14"` - - `beta_response_container_reference: object { container_id, type }` + - `"gpt-4.1-nano-2025-04-14"` - Represents a container created with /v1/containers. + - `"o4-mini"` - - `container_id: string` + - `"o4-mini-2025-04-16"` - - `type: "container_reference"` + - `"o3"` - The environment type. Always `container_reference`. + - `"o3-2025-04-16"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"o3-mini"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"o3-mini-2025-01-31"` - - `"in_progress"` + - `"o1"` - - `"completed"` + - `"o1-2024-12-17"` - - `"incomplete"` + - `"o1-preview"` - - `type: "shell_call"` + - `"o1-preview-2024-09-12"` - The type of the item. Always `shell_call`. + - `"o1-mini"` - - `agent: optional object { agent_name }` + - `"o1-mini-2024-09-12"` - The agent that produced this item. + - `"gpt-4o"` - - `agent_name: string` + - `"gpt-4o-2024-11-20"` - The canonical name of the agent that produced this item. + - `"gpt-4o-2024-08-06"` - - `caller: optional object { type } or object { caller_id, type }` + - `"gpt-4o-2024-05-13"` - The execution context that produced this tool call. + - `"gpt-4o-audio-preview"` - - `direct: object { type }` + - `"gpt-4o-audio-preview-2024-10-01"` - - `program: object { caller_id, type }` + - `"gpt-4o-audio-preview-2024-12-17"` - - `caller_id: string` + - `"gpt-4o-audio-preview-2025-06-03"` - The call ID of the program item that produced this tool call. + - `"gpt-4o-mini-audio-preview"` - - `type: "program"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `created_by: optional string` + - `"gpt-4o-search-preview"` - The ID of the entity that created this tool call. + - `"gpt-4o-mini-search-preview"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `"gpt-4o-search-preview-2025-03-11"` - The output of a shell tool call that was emitted. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `id: string` + - `"chatgpt-4o-latest"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"codex-mini-latest"` - - `call_id: string` + - `"gpt-4o-mini"` - The unique ID of the shell tool call generated by the model. + - `"gpt-4o-mini-2024-07-18"` - - `max_output_length: number` + - `"gpt-4-turbo"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"gpt-4-turbo-2024-04-09"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `"gpt-4-0125-preview"` - An array of shell call output contents + - `"gpt-4-turbo-preview"` - - `outcome: object { type } or object { exit_code, type }` + - `"gpt-4-1106-preview"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"gpt-4-vision-preview"` - - `timeout: object { type }` + - `"gpt-4"` - Indicates that the shell call exceeded its configured time limit. + - `"gpt-4-0314"` - - `exit: object { exit_code, type }` + - `"gpt-4-0613"` - Indicates that the shell commands finished and returned an exit code. + - `"gpt-4-32k"` - - `exit_code: number` + - `"gpt-4-32k-0314"` - Exit code from the shell process. + - `"gpt-4-32k-0613"` - - `type: "exit"` + - `"gpt-3.5-turbo"` - The outcome type. Always `exit`. + - `"gpt-3.5-turbo-16k"` - - `stderr: string` + - `"gpt-3.5-turbo-0301"` - The standard error output that was captured. + - `"gpt-3.5-turbo-0613"` - - `stdout: string` + - `"gpt-3.5-turbo-1106"` - The standard output that was captured. + - `"gpt-3.5-turbo-0125"` - - `created_by: optional string` + - `"gpt-3.5-turbo-16k-0613"` - The identifier of the actor that created the item. + - `"o1-pro"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"o1-pro-2025-03-19"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `"o3-pro"` - - `"in_progress"` + - `"o3-pro-2025-06-10"` - - `"completed"` + - `"o3-deep-research"` - - `"incomplete"` + - `"o3-deep-research-2025-06-26"` - - `type: "shell_call_output"` + - `"o4-mini-deep-research"` - The type of the shell call output. Always `shell_call_output`. + - `"o4-mini-deep-research-2025-06-26"` - - `agent: optional object { agent_name }` + - `"computer-use-preview"` - The agent that produced this item. + - `"computer-use-preview-2025-03-11"` - - `agent_name: string` + - `"gpt-5-codex"` - The canonical name of the agent that produced this item. + - `"gpt-5-pro"` - - `caller: optional object { type } or object { caller_id, type }` + - `"gpt-5-pro-2025-10-06"` - The execution context that produced this tool call. + - `"gpt-5.1-codex-max"` - - `direct: object { type }` + - `object: "response"` - - `program: object { caller_id, type }` + The object type of this resource - always set to `response`. - - `caller_id: string` + - `output: array of BetaResponseOutputItem` - The call ID of the program item that produced this tool call. + An array of content items generated by the model. - - `type: "program"` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `created_by: optional string` + - `beta_response_output_message: object { id, content, role, 4 more }` - The identifier of the actor that created the item. + An output message from the model. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `id: string` - A tool call that applies file diffs by creating, deleting, or updating files. + The unique ID of the output message. - - `id: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The content of the output message. - - `call_id: string` + - `role: "assistant"` - The unique ID of the apply patch tool call generated by the model. + The role of the output message. Always `assistant`. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `status: "in_progress" or "completed" or "incomplete"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `create_file: object { diff, path, type }` + - `type: "message"` - Instruction describing how to create a file via the apply_patch tool. + The type of the output message. Always `message`. - - `diff: string` + - `agent: optional object { agent_name }` - Diff to apply. + The agent that produced this item. - - `path: string` + - `phase: optional "commentary" or "final_answer"` - Path of the file to create. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `type: "create_file"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - Create a new file with the provided diff. + 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. - - `delete_file: object { path, type }` + - `id: string` - Instruction describing how to delete a file via the apply_patch tool. + The unique ID of the file search tool call. - - `path: string` + - `queries: array of string` - Path of the file to delete. + The queries used to search for files. - - `type: "delete_file"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Delete the specified file. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `update_file: object { diff, path, type }` + - `type: "file_search_call"` - Instruction describing how to update a file via the apply_patch tool. + The type of the file search tool call. Always `file_search_call`. - - `diff: string` + - `agent: optional object { agent_name }` - Diff to apply. + The agent that produced this item. - - `path: string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Path of the file to update. + The results of the file search tool call. - - `type: "update_file"` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - Update an existing file with the provided diff. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `status: "in_progress" or "completed"` + - `arguments: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + A JSON string of the arguments to pass to the function. - - `"in_progress"` + - `call_id: string` - - `"completed"` + The unique ID of the function tool call generated by the model. - - `type: "apply_patch_call"` + - `name: string` - The type of the item. Always `apply_patch_call`. + The name of the function to run. - - `agent: optional object { agent_name }` + - `type: "function_call"` - The agent that produced this item. + The type of the function tool call. Always `function_call`. - - `agent_name: string` + - `id: optional string` - The canonical name of the agent that produced this item. + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. - - `direct: object { type }` + - `namespace: optional string` - - `program: object { caller_id, type }` + The namespace of the function to run. - - `caller_id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The call ID of the program item that produced this tool call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "program"` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `created_by: optional string` + - `id: string` - The ID of the entity that created this tool call. + The unique ID of the function call tool output. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `call_id: string` - The output emitted by an apply patch tool call. + The unique ID of the function tool call generated by the model. - - `id: string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `call_id: string` + - `string output: string` - The unique ID of the apply patch tool call generated by the model. + A string of the output of the function call. - - `status: "completed" or "failed"` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The status of the apply patch tool call output. One of `completed` or `failed`. + Text, image, or file output of the function call. + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: "apply_patch_call_output"` + - `type: "function_call_output"` - The type of the item. Always `apply_patch_call_output`. + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` @@ -98342,108 +109890,133 @@ openai beta:responses compact \ - `type: "program"` + The caller type. Always `program`. + - `created_by: optional string` - The ID of the entity that created this tool call output. + The identifier of the actor that created the item. - - `output: optional string` + - `agent_message: object { id, author, content, 3 more }` - Optional textual output returned by the apply patch tool. + - `id: string` - - `mcp_call: object { id, arguments, name, 7 more }` + The unique ID of the agent message. - An invocation of a tool on an MCP server. + - `author: string` - - `id: string` + The sending agent identity. - The unique ID of the tool call. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `arguments: string` + Encrypted content sent between agents. - A JSON string of the arguments passed to the tool. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `name: string` + A text input to the model. - The name of the tool that was run. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `server_label: string` + A text output from the model. - The label of the MCP server running the tool. + - `text: object { text, type }` - - `type: "mcp_call"` + A text content. - The type of the item. Always `mcp_call`. + - `text: string` - - `agent: optional object { agent_name }` + - `type: "text"` - The agent that produced this item. + - `summary_text: object { text, type }` - - `agent_name: string` + A summary text from the model. - The canonical name of the agent that produced this item. + - `text: string` - - `approval_request_id: optional string` + A summary of the reasoning output from the model so far. - 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. + - `type: "summary_text"` - - `error: optional string` + The type of the object. Always `summary_text`. - The error from the tool call, if any. + - `reasoning_text: object { text, type }` - - `output: optional string` + Reasoning text from the model. - The output from the tool call. + - `text: string` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + The reasoning text from the model. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `type: "reasoning_text"` - - `"in_progress"` + The type of the reasoning text. Always `reasoning_text`. - - `"completed"` + - `beta_response_output_refusal: object { refusal, type }` - - `"incomplete"` + A refusal from the model. - - `"calling"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"failed"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - A list of tools available on an MCP server. + A screenshot of a computer. - - `id: string` + - `detail: "low" or "high" or "auto" or "original"` - The unique ID of the list. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `server_label: string` + - `"low"` - The label of the MCP server. + - `"high"` - - `tools: array of object { input_schema, name, annotations, description }` + - `"auto"` - The tools available on the server. + - `"original"` - - `input_schema: unknown` + - `file_id: string` - The JSON schema describing the tool's input. + The identifier of an uploaded file that contains the screenshot. - - `name: string` + - `image_url: string` + + The URL of the screenshot image. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `encrypted_content: object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` - The name of the tool. + Opaque encrypted content. - - `annotations: optional unknown` + - `type: "encrypted_content"` - Additional annotations about the tool. + The type of the input item. Always `encrypted_content`. - - `description: optional string` + - `recipient: string` - The description of the tool. + The destination agent identity. - - `type: "mcp_list_tools"` + - `type: "agent_message"` - The type of the item. Always `mcp_list_tools`. + The type of the item. Always `agent_message`. - `agent: optional object { agent_name }` @@ -98453,33 +110026,39 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `error: optional string` + - `multi_agent_call: object { id, action, arguments, 3 more }` - Error message if the server could not list tools. + - `id: string` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The unique ID of the multi-agent call item. - A request for human approval of a tool invocation. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `id: string` + The multi-agent action to execute. - The unique ID of the approval request. + - `"spawn_agent"` - - `arguments: string` + - `"interrupt_agent"` - A JSON string of arguments for the tool. + - `"list_agents"` - - `name: string` + - `"send_message"` - The name of the tool to run. + - `"followup_task"` - - `server_label: string` + - `"wait_agent"` - The label of the MCP server making the request. + - `arguments: string` - - `type: "mcp_approval_request"` + The JSON string of arguments generated for the action. - The type of the item. Always `mcp_approval_request`. + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` @@ -98489,61 +110068,53 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - - A response to an MCP approval request. + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - `id: string` - The unique ID of the approval response - - - `approval_request_id: string` - - The ID of the approval request being answered. - - - `approve: boolean` + The unique ID of the multi-agent call output item. - Whether the request was approved. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "mcp_approval_response"` + The multi-agent action that produced this result. - The type of the item. Always `mcp_approval_response`. + - `"spawn_agent"` - - `agent: optional object { agent_name }` + - `"interrupt_agent"` - The agent that produced this item. + - `"list_agents"` - - `agent_name: string` + - `"send_message"` - The canonical name of the agent that produced this item. + - `"followup_task"` - - `reason: optional string` + - `"wait_agent"` - Optional reason for the decision. + - `call_id: string` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + The unique ID of the multi-agent call. - A call to a custom tool created by the model. + - `output: array of BetaResponseOutputText` - - `call_id: string` + Text output returned by the multi-agent action. - An identifier used to map this custom tool call to a tool call output. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `input: string` + The annotations of the text output. - The input for the custom tool call generated by the model. + - `text: string` - - `name: string` + The text output from the model. - The name of the custom tool being called. + - `type: "output_text"` - - `type: "custom_tool_call"` + The type of the output text. Always `output_text`. - The type of the custom tool call. Always `custom_tool_call`. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `id: optional string` + - `type: "multi_agent_call_output"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the multi-agent result. Always `multi_agent_call_output`. - `agent: optional object { agent_name }` @@ -98553,219 +110124,236 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - The execution context that produced this tool call. + 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. - - `direct: object { type }` + - `id: string` - - `program: object { caller_id, type }` + The unique ID of the web search tool call. - - `caller_id: string` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The call ID of the program item that produced this tool call. + 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). - - `type: "program"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `namespace: optional string` + The status of the web search tool call. - The namespace of the custom tool being called. + - `type: "web_search_call"` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The type of the web search tool call. Always `web_search_call`. - The output of a custom tool call from your code, being sent back to the model. + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` - The unique ID of the custom tool call output item. + The unique ID of the computer call. - - `status: "in_progress" or "completed" or "incomplete"` + - `call_id: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + An identifier used when responding to the tool call with output. - - `"in_progress"` + - `pending_safety_checks: array of object { id, code, message }` - - `"completed"` + The pending safety checks for the computer call. - - `"incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - - `created_by: optional string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The identifier of the actor that created the item. + - `type: "computer_call"` -### Beta Response Output Item Added Event + The type of the computer call. Always `computer_call`. -- `beta_response_output_item_added_event: object { item, output_index, sequence_number, 2 more }` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - Emitted when a new output item is added. + A click action. - - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` + - `actions: optional array of BetaComputerAction` - The output item that was added. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `agent: optional object { agent_name }` - An output message from the model. + The agent that produced this item. - - `id: string` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - The unique ID of the output message. + - `id: string` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The unique ID of the computer call tool output. - The content of the output message. + - `call_id: string` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + The ID of the computer tool call that produced the output. - A text output from the model. + - `output: object { type, file_id, image_url }` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + A computer screenshot image used with the computer use tool. - The annotations of the text output. + - `type: "computer_screenshot"` - - `file_citation: object { file_id, filename, index, type }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - A citation to a file. + - `file_id: optional string` - - `file_id: string` + The identifier of an uploaded file that contains the screenshot. - The ID of the file. + - `image_url: optional string` - - `filename: string` + The URL of the screenshot image. - The filename of the file cited. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `index: number` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The index of the file in the list of files. + - `"completed"` - - `type: "file_citation"` + - `"incomplete"` - The type of the file citation. Always `file_citation`. + - `"failed"` - - `url_citation: object { end_index, start_index, title, 2 more }` + - `"in_progress"` - A citation for a web resource used to generate a model response. + - `type: "computer_call_output"` - - `end_index: number` + The type of the computer tool call output. Always `computer_call_output`. - The index of the last character of the URL citation in the message. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `start_index: number` + The safety checks reported by the API that have been acknowledged by the + developer. - The index of the first character of the URL citation in the message. + - `id: string` - - `title: string` + The ID of the pending safety check. - The title of the web resource. + - `code: optional string` - - `type: "url_citation"` + The type of the pending safety check. - The type of the URL citation. Always `url_citation`. + - `message: optional string` - - `url: string` + Details about the pending safety check. - The URL of the web resource. + - `agent: optional object { agent_name }` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + The agent that produced this item. - A citation for a container file used to generate a model response. + - `agent_name: string` - - `container_id: string` + The canonical name of the agent that produced this item. - The ID of the container file. + - `created_by: optional string` - - `end_index: number` + The identifier of the actor that created the item. - The index of the last character of the container file citation in the message. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `file_id: string` + 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). - The ID of the file. + - `id: string` - - `filename: string` + The unique identifier of the reasoning content. - The filename of the container file cited. + - `summary: array of object { text, type }` - - `start_index: number` + Reasoning summary content. - The index of the first character of the container file citation in the message. + - `type: "reasoning"` - - `type: "container_file_citation"` + The type of the object. Always `reasoning`. - The type of the container file citation. Always `container_file_citation`. + - `agent: optional object { agent_name }` - - `file_path: object { file_id, index, type }` + The agent that produced this item. - A path to a file. + - `content: optional array of object { text, type }` - - `file_id: string` + Reasoning text content. - The ID of the file. + - `encrypted_content: optional string` - - `index: number` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The index of the file in the list of files. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "file_path"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the file path. Always `file_path`. + - `program: object { id, call_id, code, 3 more }` - - `text: string` + - `id: string` - The text output from the model. + The unique ID of the program item. - - `type: "output_text"` + - `call_id: string` - The type of the output text. Always `output_text`. + The stable call ID of the program item. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `code: string` - - `token: string` + The JavaScript source executed by programmatic tool calling. - - `bytes: array of number` + - `fingerprint: string` - - `logprob: number` + Opaque program replay fingerprint that must be round-tripped. - - `top_logprobs: array of object { token, bytes, logprob }` + - `type: "program"` - - `token: string` + The type of the item. Always `program`. - - `bytes: array of number` + - `agent: optional object { agent_name }` - - `logprob: number` + The agent that produced this item. - - `beta_response_output_refusal: object { refusal, type }` + - `agent_name: string` - A refusal from the model. + The canonical name of the agent that produced this item. - - `refusal: string` + - `program_output: object { id, call_id, result, 3 more }` - The refusal explanation from the model. + - `id: string` - - `type: "refusal"` + The unique ID of the program output item. - The type of the refusal. Always `refusal`. + - `call_id: string` - - `role: "assistant"` + The call ID of the program item. - The role of the output message. Always `assistant`. + - `result: string` - - `status: "in_progress" or "completed" or "incomplete"` + The result produced by the program item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `status: "completed" or "incomplete"` - - `"in_progress"` + The terminal status of the program output item. - `"completed"` - `"incomplete"` - - `type: "message"` + - `type: "program_output"` - The type of the output message. Always `message`. + The type of the item. Always `program_output`. - `agent: optional object { agent_name }` @@ -98775,45 +110363,41 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - 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. + - `id: string` - - `"commentary"` + The unique ID of the tool search call item. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `arguments: unknown` - 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. + Arguments used for the tool search call. - - `id: string` + - `call_id: string` - The unique ID of the file search tool call. + The unique ID of the tool search call generated by the model. - - `queries: array of string` + - `execution: "server" or "client"` - The queries used to search for files. + Whether tool search was executed by the server or by the client. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"server"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"client"` - - `"in_progress"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"searching"` + The status of the tool search call item that was recorded. + + - `"in_progress"` - `"completed"` - `"incomplete"` - - `"failed"` - - - `type: "file_search_call"` + - `type: "tool_search_call"` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -98823,237 +110407,219 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. - - - `attributes: optional map[string or number or boolean]` - - 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. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `file_id: optional string` + - `created_by: optional string` - The unique ID of the file. + The identifier of the actor that created the item. - - `filename: optional string` + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - The name of the file. + - `id: string` - - `score: optional number` + The unique ID of the tool search output item. - The relevance score of the file - a value between 0 and 1. + - `call_id: string` - - `text: optional string` + The unique ID of the tool search call generated by the model. - The text that was retrieved from the file. + - `execution: "server" or "client"` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + Whether tool search was executed by the server or by the client. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"server"` - - `arguments: string` + - `"client"` - A JSON string of the arguments to pass to the function. + - `status: "in_progress" or "completed" or "incomplete"` - - `call_id: string` + The status of the tool search output item that was recorded. - The unique ID of the function tool call generated by the model. + - `"in_progress"` - - `name: string` + - `"completed"` - The name of the function to run. + - `"incomplete"` - - `type: "function_call"` + - `tools: array of BetaTool` - The type of the function tool call. Always `function_call`. + The loaded tool definitions returned by tool search. - - `id: optional string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The unique ID of the function tool call. + 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). - - `agent: optional object { agent_name }` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The agent that produced this item. + 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). - - `agent_name: string` + - `beta_computer_tool: object { type }` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `caller: optional object { type } or object { caller_id, type }` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The execution context that produced this tool call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `direct: object { type }` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `program: object { caller_id, type }` + 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). - - `caller_id: string` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The call ID of the program item that produced this tool call. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `type: "program"` + - `code_interpreter: object { container, type, allowed_callers }` - - `namespace: optional string` + A tool that runs Python code to help generate a response to a prompt. - The namespace of the function to run. + - `programmatic_tool_calling: object { type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `image_generation: object { type, action, background, 9 more }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool that generates images using the GPT image models. - - `"in_progress"` + - `local_shell: object { type }` - - `"completed"` + A tool that allows the model to execute shell commands in a local environment. - - `"incomplete"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + A tool that allows the model to execute shell commands. - - `id: string` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The unique ID of the function call tool output. + 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) - - `call_id: string` + - `beta_namespace_tool: object { description, name, tools, type }` - The unique ID of the function tool call generated by the model. + Groups function/custom tools under a shared namespace. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The output from the function call generated by your code. - Can be a string or an list of output content. + Hosted or BYOT tool search configuration for deferred tools. - - `string output: string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - A string of the output of the function call. + 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). - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `beta_apply_patch_tool: object { type, allowed_callers }` - Text, image, or file output of the function call. + Allows the assistant to create, delete, or update files using unified diffs. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `type: "tool_search_output"` - A text input to the model. + The type of the item. Always `tool_search_output`. - - `text: string` + - `agent: optional object { agent_name }` - The text input to the model. + The agent that produced this item. - - `type: "input_text"` + - `agent_name: string` - The type of the input item. Always `input_text`. + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `created_by: optional string` - 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. + The identifier of the actor that created the item. - - `mode: "explicit"` + - `additional_tools: object { id, role, tools, 2 more }` - The breakpoint mode. Always `explicit`. + - `id: string` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The unique ID of the additional tools item. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `role: "unknown" or "user" or "assistant" or 5 more` - - `detail: "low" or "high" or "auto" or "original"` + The role that provided the additional tools. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"unknown"` - - `"low"` + - `"user"` - - `"high"` + - `"assistant"` - - `"auto"` + - `"system"` - - `"original"` + - `"critic"` - - `type: "input_image"` + - `"discriminator"` - The type of the input item. Always `input_image`. + - `"developer"` - - `file_id: optional string` + - `"tool"` - The ID of the file to be sent to the model. + - `tools: array of BetaTool` - - `image_url: optional string` + The additional tool definitions made available at this item. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `prompt_cache_breakpoint: optional object { mode }` + 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). - 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. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `mode: "explicit"` + 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). - The breakpoint mode. Always `explicit`. + - `beta_computer_tool: object { type }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A file input to the model. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `type: "input_file"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the input item. Always `input_file`. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `detail: optional "auto" or "low" or "high"` + 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). - 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`. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `"auto"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"low"` + - `code_interpreter: object { container, type, allowed_callers }` - - `"high"` + A tool that runs Python code to help generate a response to a prompt. - - `file_data: optional string` + - `programmatic_tool_calling: object { type }` - The content of the file to be sent to the model. + - `image_generation: object { type, action, background, 9 more }` - - `file_id: optional string` + A tool that generates images using the GPT image models. - The ID of the file to be sent to the model. + - `local_shell: object { type }` - - `file_url: optional string` + A tool that allows the model to execute shell commands in a local environment. - The URL of the file to be sent to the model. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `filename: optional string` + A tool that allows the model to execute shell commands. - The name of the file to be sent to the model. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `prompt_cache_breakpoint: optional object { mode }` + 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) - 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. + - `beta_namespace_tool: object { description, name, tools, type }` - - `mode: "explicit"` + Groups function/custom tools under a shared namespace. - The breakpoint mode. Always `explicit`. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `status: "in_progress" or "completed" or "incomplete"` + Hosted or BYOT tool search configuration for deferred tools. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `"in_progress"` + 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). - - `"completed"` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `"incomplete"` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "function_call_output"` + - `type: "additional_tools"` - The type of the function tool call output. Always `function_call_output`. + The type of the item. Always `additional_tools`. - `agent: optional object { agent_name }` @@ -99063,147 +110629,156 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - The execution context that produced this tool call. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `direct: object { type }` + - `id: string` - - `program: object { caller_id, type }` + The unique ID of the compaction item. - - `caller_id: string` + - `encrypted_content: string` - The call ID of the program item that produced this tool call. + The encrypted content that was produced by compaction. - - `type: "program"` + - `type: "compaction"` - The caller type. Always `program`. + The type of the item. Always `compaction`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `created_by: optional string` The identifier of the actor that created the item. - - `agent_message: object { id, author, content, 3 more }` + - `image_generation_call: object { id, result, status, 2 more }` - - `id: string` + An image generation request made by the model. - The unique ID of the agent message. + - `id: string` - - `author: string` + The unique ID of the image generation call. - The sending agent identity. + - `result: string` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + The generated image encoded in base64. - Encrypted content sent between agents. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The status of the image generation call. - A text input to the model. + - `"in_progress"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"completed"` - A text output from the model. + - `"generating"` - - `text: object { text, type }` + - `"failed"` - A text content. + - `type: "image_generation_call"` - - `text: string` + The type of the image generation call. Always `image_generation_call`. - - `type: "text"` + - `agent: optional object { agent_name }` - - `summary_text: object { text, type }` + The agent that produced this item. - A summary text from the model. + - `agent_name: string` - - `text: string` + The canonical name of the agent that produced this item. - A summary of the reasoning output from the model so far. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `type: "summary_text"` + A tool call to run code. - The type of the object. Always `summary_text`. + - `id: string` - - `reasoning_text: object { text, type }` + The unique ID of the code interpreter tool call. - Reasoning text from the model. + - `code: string` - - `text: string` + The code to run, or null if not available. - The reasoning text from the model. + - `container_id: string` - - `type: "reasoning_text"` + The ID of the container used to run the code. - The type of the reasoning text. Always `reasoning_text`. + - `outputs: array of object { logs, type } or object { type, url }` - - `beta_response_output_refusal: object { refusal, type }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - A refusal from the model. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: "code_interpreter_call"` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A screenshot of a computer. + - `agent: optional object { agent_name }` - - `detail: "low" or "high" or "auto" or "original"` + The agent that produced this item. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `"low"` + A tool call to run a command on the local shell. - - `"high"` + - `id: string` - - `"auto"` + The unique ID of the local shell call. - - `"original"` + - `action: object { command, env, type, 3 more }` - - `file_id: string` + Execute a shell command on the server. - The identifier of an uploaded file that contains the screenshot. + - `command: array of string` - - `image_url: string` + The command to run. - The URL of the screenshot image. + - `env: map[string]` - - `type: "computer_screenshot"` + Environment variables to set for the command. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `type: "exec"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of the local shell action. Always `exec`. - 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. + - `timeout_ms: optional number` - - `mode: "explicit"` + Optional timeout in milliseconds for the command. - The breakpoint mode. Always `explicit`. + - `user: optional string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Optional user to run the command as. - A file input to the model. + - `working_directory: optional string` - - `encrypted_content: object { encrypted_content, type }` + Optional working directory to run the command in. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `call_id: string` - - `encrypted_content: string` + The unique ID of the local shell tool call generated by the model. - Opaque encrypted content. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "encrypted_content"` + The status of the local shell call. - The type of the input item. Always `encrypted_content`. + - `"in_progress"` - - `recipient: string` + - `"completed"` - The destination agent identity. + - `"incomplete"` - - `type: "agent_message"` + - `type: "local_shell_call"` - The type of the item. Always `agent_message`. + The type of the local shell call. Always `local_shell_call`. - `agent: optional object { agent_name }` @@ -99213,39 +110788,21 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { id, action, arguments, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action to execute. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` + - `local_shell_call_output: object { id, output, type, 2 more }` - - `"wait_agent"` + The output of a local shell tool call. - - `arguments: string` + - `id: string` - The JSON string of arguments generated for the action. + The unique ID of the local shell tool call generated by the model. - - `call_id: string` + - `output: string` - The unique ID linking this call to its output. + A JSON string of the output of the local shell tool call. - - `type: "multi_agent_call"` + - `type: "local_shell_call_output"` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the local shell tool call output. Always `local_shell_call_output`. - `agent: optional object { agent_name }` @@ -99255,189 +110812,159 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: string` - - The unique ID of the multi-agent call. - - - `output: array of BetaResponseOutputText` + - `status: optional "in_progress" or "completed" or "incomplete"` - Text output returned by the multi-agent action. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"in_progress"` - The annotations of the text output. + - `"completed"` - - `text: string` + - `"incomplete"` - The text output from the model. + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - `type: "output_text"` + A tool call that executes one or more shell commands in a managed environment. - The type of the output text. Always `output_text`. + - `id: string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: "multi_agent_call_output"` + - `action: object { commands, max_output_length, timeout_ms }` - The type of the multi-agent result. Always `multi_agent_call_output`. + The shell commands and limits that describe how to run the tool call. - - `agent: optional object { agent_name }` + - `commands: array of string` - The agent that produced this item. + - `max_output_length: number` - - `agent_name: string` + Optional maximum number of characters to return from each command. - The canonical name of the agent that produced this item. + - `timeout_ms: number` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + Optional timeout in milliseconds for the commands. - 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. + - `call_id: string` - - `id: string` + The unique ID of the shell tool call generated by the model. - The unique ID of the web search tool call. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Represents the use of a local environment to perform shell actions. - 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). + - `beta_response_local_environment: object { type }` - - `search: object { type, queries, query, sources }` + Represents the use of a local environment to perform shell actions. - Action type "search" - Performs a web search query. + - `type: "local"` - - `type: "search"` + The environment type. Always `local`. - The action type. + - `beta_response_container_reference: object { container_id, type }` - - `queries: optional array of string` + Represents a container created with /v1/containers. - The search queries. + - `container_id: string` - - `query: optional string` + - `type: "container_reference"` - The search query. + The environment type. Always `container_reference`. - - `sources: optional array of object { type, url }` + - `status: "in_progress" or "completed" or "incomplete"` - The sources used in the search. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `type: "url"` + - `"in_progress"` - The type of source. Always `url`. + - `"completed"` - - `url: string` + - `"incomplete"` - The URL of the source. + - `type: "shell_call"` - - `open_page: object { type, url }` + The type of the item. Always `shell_call`. - Action type "open_page" - Opens a specific URL from search results. + - `agent: optional object { agent_name }` - - `type: "open_page"` + The agent that produced this item. - The action type. + - `agent_name: string` - - `url: optional string` + The canonical name of the agent that produced this item. - The URL opened by the model. + - `caller: optional object { type } or object { caller_id, type }` - - `find_in_page: object { pattern, type, url }` + The execution context that produced this tool call. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `direct: object { type }` - - `pattern: string` + - `program: object { caller_id, type }` - The pattern or text to search for within the page. + - `caller_id: string` - - `type: "find_in_page"` + The call ID of the program item that produced this tool call. - The action type. + - `type: "program"` - - `url: string` + - `created_by: optional string` - The URL of the page searched for the pattern. + The ID of the entity that created this tool call. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - The status of the web search tool call. + The output of a shell tool call that was emitted. - - `"in_progress"` + - `id: string` - - `"searching"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"completed"` + - `call_id: string` - - `"failed"` + The unique ID of the shell tool call generated by the model. - - `type: "web_search_call"` + - `max_output_length: number` - The type of the web search tool call. Always `web_search_call`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `agent: optional object { agent_name }` + - `output: array of object { outcome, stderr, stdout, created_by }` - The agent that produced this item. + An array of shell call output contents - - `agent_name: string` + - `outcome: object { type } or object { exit_code, type }` - The canonical name of the agent that produced this item. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `timeout: object { type }` - 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. + Indicates that the shell call exceeded its configured time limit. - - `id: string` + - `exit: object { exit_code, type }` - The unique ID of the computer call. + Indicates that the shell commands finished and returned an exit code. - - `call_id: string` + - `exit_code: number` - An identifier used when responding to the tool call with output. + Exit code from the shell process. - - `pending_safety_checks: array of object { id, code, message }` + - `type: "exit"` - The pending safety checks for the computer call. + The outcome type. Always `exit`. - - `id: string` + - `stderr: string` - The ID of the pending safety check. + The standard error output that was captured. - - `code: optional string` + - `stdout: string` - The type of the pending safety check. + The standard output that was captured. - - `message: optional string` + - `created_by: optional string` - Details about the pending safety check. + The identifier of the actor that created the item. - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -99445,221 +110972,211 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "computer_call"` - - The type of the computer call. Always `computer_call`. - - - `"computer_call"` + - `type: "shell_call_output"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + The type of the shell call output. Always `shell_call_output`. - A click action. + - `agent: optional object { agent_name }` - - `click: object { button, type, x, 2 more }` + The agent that produced this item. - A click action. + - `agent_name: string` - - `button: "left" or "right" or "wheel" or 2 more` + The canonical name of the agent that produced this item. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `caller: optional object { type } or object { caller_id, type }` - - `"left"` + The execution context that produced this tool call. - - `"right"` + - `direct: object { type }` - - `"wheel"` + - `program: object { caller_id, type }` - - `"back"` + - `caller_id: string` - - `"forward"` + The call ID of the program item that produced this tool call. - - `type: "click"` + - `type: "program"` - Specifies the event type. For a click action, this property is always `click`. + - `created_by: optional string` - - `x: number` + The identifier of the actor that created the item. - The x-coordinate where the click occurred. + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `y: number` + A tool call that applies file diffs by creating, deleting, or updating files. - The y-coordinate where the click occurred. + - `id: string` - - `keys: optional array of string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The keys being held while clicking. + - `call_id: string` - - `double_click: object { keys, type, x, y }` + The unique ID of the apply patch tool call generated by the model. - A double click action. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `keys: array of string` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The keys being held while double-clicking. + - `create_file: object { diff, path, type }` - - `type: "double_click"` + Instruction describing how to create a file via the apply_patch tool. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `diff: string` - - `x: number` + Diff to apply. - The x-coordinate where the double click occurred. + - `path: string` - - `y: number` + Path of the file to create. - The y-coordinate where the double click occurred. + - `type: "create_file"` - - `drag: object { path, type, keys }` + Create a new file with the provided diff. - A drag action. + - `delete_file: object { path, type }` - - `path: array of object { x, y }` + Instruction describing how to delete a file via the apply_patch tool. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `path: string` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + Path of the file to delete. - - `x: number` + - `type: "delete_file"` - The x-coordinate. + Delete the specified file. - - `y: number` + - `update_file: object { diff, path, type }` - The y-coordinate. + Instruction describing how to update a file via the apply_patch tool. - - `type: "drag"` + - `diff: string` - Specifies the event type. For a drag action, this property is always set to `drag`. + Diff to apply. - - `keys: optional array of string` + - `path: string` - The keys being held while dragging the mouse. + Path of the file to update. - - `keypress: object { keys, type }` + - `type: "update_file"` - A collection of keypresses the model would like to perform. + Update an existing file with the provided diff. - - `keys: array of string` + - `status: "in_progress" or "completed"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `type: "keypress"` + - `"in_progress"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"completed"` - - `move: object { type, x, y, keys }` + - `type: "apply_patch_call"` - A mouse move action. + The type of the item. Always `apply_patch_call`. - - `type: "move"` + - `agent: optional object { agent_name }` - Specifies the event type. For a move action, this property is always set to `move`. + The agent that produced this item. - - `x: number` + - `agent_name: string` - The x-coordinate to move to. + The canonical name of the agent that produced this item. - - `y: number` + - `caller: optional object { type } or object { caller_id, type }` - The y-coordinate to move to. + The execution context that produced this tool call. - - `keys: optional array of string` + - `direct: object { type }` - The keys being held while moving the mouse. + - `program: object { caller_id, type }` - - `screenshot: object { type }` + - `caller_id: string` - A screenshot action. + The call ID of the program item that produced this tool call. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `type: "program"` - A scroll action. + - `created_by: optional string` - - `scroll_x: number` + The ID of the entity that created this tool call. - The horizontal scroll distance. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `scroll_y: number` + The output emitted by an apply patch tool call. - The vertical scroll distance. + - `id: string` - - `type: "scroll"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `call_id: string` - - `x: number` + The unique ID of the apply patch tool call generated by the model. - The x-coordinate where the scroll occurred. + - `status: "completed" or "failed"` - - `y: number` + The status of the apply patch tool call output. One of `completed` or `failed`. - The y-coordinate where the scroll occurred. + - `"completed"` - - `keys: optional array of string` + - `"failed"` - The keys being held while scrolling. + - `type: "apply_patch_call_output"` - - `type: object { text, type }` + The type of the item. Always `apply_patch_call_output`. - An action to type in text. + - `agent: optional object { agent_name }` - - `text: string` + The agent that produced this item. - The text to type. + - `agent_name: string` - - `type: "type"` + The canonical name of the agent that produced this item. - Specifies the event type. For a type action, this property is always set to `type`. + - `caller: optional object { type } or object { caller_id, type }` - - `wait: object { type }` + The execution context that produced this tool call. - A wait action. + - `direct: object { type }` - - `actions: optional array of BetaComputerAction` + - `program: object { caller_id, type }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `caller_id: string` - - `click: object { button, type, x, 2 more }` + The call ID of the program item that produced this tool call. - A click action. + - `type: "program"` - - `double_click: object { keys, type, x, y }` + - `created_by: optional string` - A double click action. + The ID of the entity that created this tool call output. - - `drag: object { path, type, keys }` + - `output: optional string` - A drag action. + Optional textual output returned by the apply patch tool. - - `keypress: object { keys, type }` + - `mcp_call: object { id, arguments, name, 7 more }` - A collection of keypresses the model would like to perform. + An invocation of a tool on an MCP server. - - `move: object { type, x, y, keys }` + - `id: string` - A mouse move action. + The unique ID of the tool call. - - `screenshot: object { type }` + - `arguments: string` - A screenshot action. + A JSON string of the arguments passed to the tool. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `name: string` - A scroll action. + The name of the tool that was run. - - `type: object { text, type }` + - `server_label: string` - An action to type in text. + The label of the MCP server running the tool. - - `wait: object { type }` + - `type: "mcp_call"` - A wait action. + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` @@ -99669,66 +111186,68 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `approval_request_id: optional string` - - `id: string` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - The unique ID of the computer call tool output. + - `error: optional string` - - `call_id: string` + The error from the tool call, if any. - The ID of the computer tool call that produced the output. + - `output: optional string` - - `output: object { type, file_id, image_url }` + The output from the tool call. - A computer screenshot image used with the computer use tool. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "computer_screenshot"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"in_progress"` - - `file_id: optional string` + - `"completed"` - The identifier of an uploaded file that contains the screenshot. + - `"incomplete"` - - `image_url: optional string` + - `"calling"` - The URL of the screenshot image. + - `"failed"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + A list of tools available on an MCP server. - - `"completed"` + - `id: string` - - `"incomplete"` + The unique ID of the list. - - `"failed"` + - `server_label: string` - - `"in_progress"` + The label of the MCP server. - - `type: "computer_call_output"` + - `tools: array of object { input_schema, name, annotations, description }` - The type of the computer tool call output. Always `computer_call_output`. + The tools available on the server. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `input_schema: unknown` - The safety checks reported by the API that have been acknowledged by the - developer. + The JSON schema describing the tool's input. - - `id: string` + - `name: string` - The ID of the pending safety check. + The name of the tool. - - `code: optional string` + - `annotations: optional unknown` - The type of the pending safety check. + Additional annotations about the tool. - - `message: optional string` + - `description: optional string` - Details about the pending safety check. + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. - `agent: optional object { agent_name }` @@ -99738,36 +111257,33 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `error: optional string` - The identifier of the actor that created the item. + Error message if the server could not list tools. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + A request for human approval of a tool invocation. - `id: string` - The unique identifier of the reasoning content. + The unique ID of the approval request. - - `summary: array of object { text, type }` + - `arguments: string` - Reasoning summary content. + A JSON string of arguments for the tool. - - `text: string` + - `name: string` - A summary of the reasoning output from the model so far. + The name of the tool to run. - - `type: "summary_text"` + - `server_label: string` - The type of the object. Always `summary_text`. + The label of the MCP server making the request. - - `type: "reasoning"` + - `type: "mcp_approval_request"` - The type of the object. Always `reasoning`. + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` @@ -99777,2148 +111293,2488 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - Reasoning text content. + A response to an MCP approval request. - - `text: string` + - `id: string` - The reasoning text from the model. + The unique ID of the approval response - - `type: "reasoning_text"` + - `approval_request_id: string` - The type of the reasoning text. Always `reasoning_text`. + The ID of the approval request being answered. - - `encrypted_content: optional string` + - `approve: boolean` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Whether the request was approved. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "mcp_approval_response"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the item. Always `mcp_approval_response`. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `"incomplete"` + - `agent_name: string` - - `program: object { id, call_id, code, 3 more }` + The canonical name of the agent that produced this item. - - `id: string` + - `reason: optional string` - The unique ID of the program item. + Optional reason for the decision. + + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. - `call_id: string` - The stable call ID of the program item. + An identifier used to map this custom tool call to a tool call output. - - `code: string` + - `input: string` - The JavaScript source executed by programmatic tool calling. + The input for the custom tool call generated by the model. - - `fingerprint: string` + - `name: string` - Opaque program replay fingerprint that must be round-tripped. + The name of the custom tool being called. - - `type: "program"` + - `type: "custom_tool_call"` - The type of the item. Always `program`. + The type of the custom tool call. Always `custom_tool_call`. + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` The agent that produced this item. - - `agent_name: string` + - `caller: optional object { type } or object { caller_id, type }` - The canonical name of the agent that produced this item. + The execution context that produced this tool call. - - `program_output: object { id, call_id, result, 3 more }` + - `namespace: optional string` - - `id: string` + The namespace of the custom tool being called. - The unique ID of the program output item. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `call_id: string` + The output of a custom tool call from your code, being sent back to the model. - The call ID of the program item. + - `id: string` - - `result: string` + The unique ID of the custom tool call output item. - The result produced by the program item. + - `status: "in_progress" or "completed" or "incomplete"` - - `status: "completed" or "incomplete"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The terminal status of the program output item. + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` + - `created_by: optional string` - The type of the item. Always `program_output`. + The identifier of the actor that created the item. - - `agent: optional object { agent_name }` + - `parallel_tool_calls: boolean` - The agent that produced this item. + Whether to allow the model to run tool calls in parallel. - - `agent_name: string` + - `temperature: number` - The canonical name of the agent that produced this item. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `id: string` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The unique ID of the tool search call item. + - `beta_tool_choice_options: "none" or "auto" or "required"` - - `arguments: unknown` + Controls which (if any) tool is called by the model. - Arguments used for the tool search call. + `none` means the model will not call any tool and instead generates a message. - - `call_id: string` + `auto` means the model can pick between generating a message or calling one or + more tools. - The unique ID of the tool search call generated by the model. + `required` means the model must call one or more tools. - - `execution: "server" or "client"` + - `"none"` - Whether tool search was executed by the server or by the client. + - `"auto"` - - `"server"` + - `"required"` - - `"client"` + - `beta_tool_choice_allowed: object { mode, tools, type }` - - `status: "in_progress" or "completed" or "incomplete"` + Constrains the tools available to the model to a pre-defined set. - The status of the tool search call item that was recorded. + - `mode: "auto" or "required"` - - `"in_progress"` + Constrains the tools available to the model to a pre-defined set. - - `"completed"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"incomplete"` + `required` requires the model to call one or more of the allowed tools. - - `type: "tool_search_call"` + - `"auto"` - The type of the item. Always `tool_search_call`. + - `"required"` - - `agent: optional object { agent_name }` + - `tools: array of map[unknown]` - The agent that produced this item. + A list of tool definitions that the model should be allowed to call. - - `agent_name: string` + For the Responses API, the list of tool definitions might look like: - The canonical name of the agent that produced this item. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `created_by: optional string` + - `type: "allowed_tools"` - The identifier of the actor that created the item. + Allowed tool configuration type. Always `allowed_tools`. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `beta_tool_choice_types: object { type }` - - `id: string` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - The unique ID of the tool search output item. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `call_id: string` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The unique ID of the tool search call generated by the model. + Allowed values are: - - `execution: "server" or "client"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - Whether tool search was executed by the server or by the client. + - `"file_search"` - - `"server"` + - `"web_search_preview"` - - `"client"` + - `"computer"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"computer_use_preview"` - The status of the tool search output item that was recorded. + - `"computer_use"` - - `"in_progress"` + - `"web_search_preview_2025_03_11"` - - `"completed"` + - `"image_generation"` - - `"incomplete"` + - `"code_interpreter"` - - `tools: array of BetaTool` + - `beta_tool_choice_function: object { name, type }` - The loaded tool definitions returned by tool search. + Use this option to force the model to call a specific function. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `name: string` - 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). + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `beta_tool_choice_mcp: object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `name: optional string` + + The name of the tool to call on the server. + + - `beta_tool_choice_custom: object { name, type }` + + Use this option to force the model to call a specific custom tool. - `name: string` - The name of the function to call. + The name of the custom tool to call. - - `parameters: map[unknown]` + - `type: "custom"` - A JSON schema object describing the parameters of the function. + For custom tool calling, the type is always `custom`. - - `strict: boolean` + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - Whether strict parameter validation is enforced for this function tool. + - `beta_tool_choice_apply_patch: object { type }` - - `type: "function"` + Forces the model to call the apply_patch tool when executing a tool call. - The type of the function tool. Always `function`. + - `type: "apply_patch"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The tool to call. Always `apply_patch`. - The tool invocation context(s). + - `beta_tool_choice_shell: object { type }` - - `"direct"` + Forces the model to call the shell tool when a tool call is required. - - `"programmatic"` + - `type: "shell"` - - `defer_loading: optional boolean` + The tool to call. Always `shell`. - Whether this function is deferred and loaded via tool search. + - `tools: array of BetaTool` - - `description: optional string` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - A description of the function. Used by the model to determine whether or not to call the function. + We support the following categories of tools: - - `output_schema: optional map[unknown]` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "file_search"` + - `beta_computer_tool: object { type }` - The type of the file search tool. Always `file_search`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `vector_store_ids: array of string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The IDs of the vector stores to search. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `filters: optional object { key, type, value } or object { filters, type }` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - A filter to apply. + 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). - - `Comparison Filter: object { key, type, value }` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `key: string` + - `code_interpreter: object { container, type, allowed_callers }` - The key to compare against the value. + A tool that runs Python code to help generate a response to a prompt. - - `type: "eq" or "ne" or "gt" or 5 more` + - `programmatic_tool_calling: object { type }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `image_generation: object { type, action, background, 9 more }` - - `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 + A tool that generates images using the GPT image models. - - `"eq"` + - `local_shell: object { type }` - - `"ne"` + A tool that allows the model to execute shell commands in a local environment. - - `"gt"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `"gte"` + A tool that allows the model to execute shell commands. - - `"lt"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"lte"` + 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) - - `"in"` + - `beta_namespace_tool: object { description, name, tools, type }` - - `"nin"` + Groups function/custom tools under a shared namespace. - - `value: string or number or boolean or array of unknown` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - The value to compare against the attribute key; supports string, number, or boolean types. + Hosted or BYOT tool search configuration for deferred tools. - - `union_member_0: string` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `union_member_1: number` + 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). - - `union_member_2: boolean` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `union_member_3: array of unknown` + Allows the assistant to create, delete, or update files using unified diffs. - - `Compound Filter: object { filters, type }` + - `top_p: number` - Combine multiple filters using `and` or `or`. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `filters: array of object { key, type, value } or unknown` + We generally recommend altering this or `temperature` but not both. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `background: optional boolean` - - `Comparison Filter: object { key, type, value }` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `completed_at: optional number` - - `key: string` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The key to compare against the value. + - `conversation: optional object { id }` - - `type: "eq" or "ne" or "gt" or 5 more` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `id: string` - - `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 + The unique ID of the conversation that this response was associated with. - - `"eq"` + - `max_output_tokens: optional number` - - `"ne"` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `"gt"` + - `max_tool_calls: optional number` - - `"gte"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `"lt"` + - `moderation: optional object { input, output }` - - `"lte"` + Moderation results for the response input and output, if moderated completions were requested. - - `"in"` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"nin"` + Moderation for the response input. - - `value: string or number or boolean or array of unknown` + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + A moderation result produced for the response input or output. - - `union_member_0: string` + - `categories: map[boolean]` - - `union_member_1: number` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `union_member_2: boolean` + - `category_applied_input_types: map[array of "text" or "image"]` - - `union_member_3: array of unknown` + Which modalities of input are reflected by the score for each category. - - `union_member_1: unknown` + - `"text"` - - `type: "and" or "or"` + - `"image"` - Type of operation: `and` or `or`. + - `category_scores: map[number]` - - `"and"` + A dictionary of moderation categories to scores. - - `"or"` + - `flagged: boolean` - - `max_num_results: optional number` + A boolean indicating whether the content was flagged by any category. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `model: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The moderation model that produced this result. - Ranking options for search. + - `type: "moderation_result"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The object type, which was always `moderation_result` for successful moderation results. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `error: object { code, message, type }` - - `embedding_weight: number` + An error produced while attempting moderation for the response input or output. - The weight of the embedding in the reciprocal ranking fusion. + - `code: string` - - `text_weight: number` + The error code. - The weight of the text in the reciprocal ranking fusion. + - `message: string` - - `ranker: optional "auto" or "default-2024-11-15"` + The error message. - The ranker to use for the file search. + - `type: "error"` - - `"auto"` + The object type, which was always `error` for moderation failures. - - `"default-2024-11-15"` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `score_threshold: optional number` + Moderation for the response output. - 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. + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` - - `beta_computer_tool: object { type }` + A moderation result produced for the response input or output. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `categories: map[boolean]` - - `type: "computer"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The type of the computer tool. Always `computer`. + - `category_applied_input_types: map[array of "text" or "image"]` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + Which modalities of input are reflected by the score for each category. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"text"` - - `display_height: number` + - `"image"` - The height of the computer display. + - `category_scores: map[number]` - - `display_width: number` + A dictionary of moderation categories to scores. - The width of the computer display. + - `flagged: boolean` - - `environment: "windows" or "mac" or "linux" or 2 more` + A boolean indicating whether the content was flagged by any category. - The type of computer environment to control. + - `model: string` - - `"windows"` + The moderation model that produced this result. - - `"mac"` + - `type: "moderation_result"` - - `"linux"` + The object type, which was always `moderation_result` for successful moderation results. - - `"ubuntu"` + - `error: object { code, message, type }` - - `"browser"` + An error produced while attempting moderation for the response input or output. - - `type: "computer_use_preview"` + - `code: string` - The type of the computer use tool. Always `computer_use_preview`. + The error code. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `message: string` - 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). + The error message. - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "error"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The object type, which was always `error` for moderation failures. - - `"web_search"` + - `previous_response_id: optional string` - - `"web_search_2025_08_26"` + 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`. - - `filters: optional object { allowed_domains }` + - `prompt: optional object { id, variables, version }` - Filters for the search. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `allowed_domains: optional array of string` + - `id: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The unique identifier of the prompt template to use. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `search_context_size: optional "low" or "medium" or "high"` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - 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. + - `union_member_0: string` - - `"low"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"medium"` + A text input to the model. - - `"high"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `user_location: optional object { city, country, region, 2 more }` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The approximate location of the user. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `city: optional string` + A file input to the model. - Free text input for the city of the user, e.g. `San Francisco`. + - `version: optional string` - - `country: optional string` + Optional version of the prompt template. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `prompt_cache_key: optional string` - - `region: optional string` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - Free text input for the region of the user, e.g. `California`. + - `prompt_cache_options: optional object { mode, ttl }` - - `timezone: optional string` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `mode: "implicit" or "explicit"` - - `type: optional "approximate"` + Whether implicit prompt-cache breakpoints were enabled. - The type of location approximation. Always `approximate`. + - `"implicit"` - - `"approximate"` + - `"explicit"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `ttl: "30m"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The minimum lifetime applied to each cache breakpoint. - - `server_label: string` + - `"30m"` - A label for this MCP server, used to identify it in tool calls. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `type: "mcp"` + Deprecated. Use `prompt_cache_options.ttl` instead. - The type of the MCP tool. Always `mcp`. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `allowed_callers: optional array of "direct" or "programmatic"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The tool invocation context(s). + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `"direct"` + - `"in_memory"` - - `"programmatic"` + - `"24h"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - List of allowed tool names or a filter object. + **gpt-5 and o-series models only** - - `MCP allowed tools: array of string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - A string array of allowed tool names + - `context: optional "auto" or "current_turn" or "all_turns"` - - `MCP tool filter: object { read_only, tool_names }` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - A filter object to specify which tools are allowed. + - `"auto"` - - `read_only: optional boolean` + - `"current_turn"` - 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. + - `"all_turns"` - - `tool_names: optional array of string` + - `effort: optional "none" or "minimal" or "low" or 4 more` - List of allowed tool names. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `authorization: optional string` + - `"none"` - 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. + - `"minimal"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"low"` - 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). + - `"medium"` - Currently supported `connector_id` values are: + - `"high"` - - 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` + - `"xhigh"` - - `"connector_dropbox"` + - `"max"` - - `"connector_gmail"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `"connector_googlecalendar"` + **Deprecated:** use `summary` instead. - - `"connector_googledrive"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"connector_microsoftteams"` + - `"auto"` - - `"connector_outlookcalendar"` + - `"concise"` - - `"connector_outlookemail"` + - `"detailed"` - - `"connector_sharepoint"` + - `mode: optional string or "standard" or "pro"` - - `defer_loading: optional boolean` + Controls the reasoning execution mode for the request. - Whether this MCP tool is deferred and discovered via tool search. + When returned on a response, this is the effective execution mode. - - `headers: optional map[string]` + - `"standard"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"pro"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `summary: optional "auto" or "concise" or "detailed"` - Specify which of the MCP server's tools require approval. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `MCP tool approval filter: object { always, never }` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"auto"` - - `always: optional object { read_only, tool_names }` + - `"concise"` - A filter object to specify which tools are allowed. + - `"detailed"` - - `read_only: optional boolean` + - `safety_identifier: optional string` - 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. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `tool_names: optional array of string` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - List of allowed tool names. + Specifies the processing type used for serving the request. - - `never: optional object { read_only, tool_names }` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - A filter object to specify which tools are allowed. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `read_only: optional boolean` + - `"auto"` - 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. + - `"default"` - - `tool_names: optional array of string` + - `"flex"` - List of allowed tool names. + - `"scale"` - - `MCP tool approval setting: "always" or "never"` + - `"priority"` - 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. + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `"always"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"never"` + - `"completed"` - - `server_description: optional string` + - `"failed"` - Optional description of the MCP server, used to provide more context. + - `"in_progress"` - - `server_url: optional string` + - `"cancelled"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"queued"` - - `tunnel_id: optional string` + - `"incomplete"` - 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. + - `text: optional object { format, verbosity }` - - `code_interpreter: object { container, type, allowed_callers }` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - A tool that runs Python code to help generate a response to a prompt. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - 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. + An object specifying the format that the model must output. - - `union_member_0: string` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The container ID. + The default format is `{ "type": "text" }` with no additional options. - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + **Not recommended for gpt-4o and newer models:** - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `type: "auto"` + - `text: object { type }` - Always `auto`. + Default response format. Used to generate text responses. - - `file_ids: optional array of string` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - An optional list of uploaded files to make available to your code. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `name: string` - The memory limit for the code interpreter container. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `"1g"` + - `schema: map[unknown]` - - `"4g"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"16g"` + - `type: "json_schema"` - - `"64g"` + The type of response format being defined. Always `json_schema`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `description: optional string` - Network access policy for the container. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `beta_container_network_policy_disabled: object { type }` + - `strict: optional boolean` - - `type: "disabled"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - Disable outbound network access. Always `disabled`. + - `json_object: object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `verbosity: optional "low" or "medium" or "high"` - - `allowed_domains: array of string` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - A list of allowed domains when type is `allowlist`. + - `"low"` - - `type: "allowlist"` + - `"medium"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `"high"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `top_logprobs: optional number` - Optional domain-scoped secrets for allowlisted domains. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `domain: string` + - `truncation: optional "auto" or "disabled"` - The domain associated with the secret. + The truncation strategy to use for the model response. - - `name: string` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The name of the secret to inject for the domain. + - `"auto"` - - `value: string` + - `"disabled"` - The secret value to inject for the domain. + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `type: "code_interpreter"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The type of the code interpreter tool. Always `code_interpreter`. + - `input_tokens: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The number of input tokens. - The tool invocation context(s). + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `"direct"` + A detailed breakdown of the input tokens. - - `"programmatic"` + - `cache_write_tokens: number` - - `programmatic_tool_calling: object { type }` + The number of input tokens that were written to the cache. - - `image_generation: object { type, action, background, 9 more }` + - `cached_tokens: number` - A tool that generates images using the GPT image models. + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - - `type: "image_generation"` + - `output_tokens: number` - The type of the image generation tool. Always `image_generation`. + The number of output tokens. - - `action: optional "generate" or "edit" or "auto"` + - `output_tokens_details: object { reasoning_tokens }` - Whether to generate a new image or edit an existing image. Default: `auto`. + A detailed breakdown of the output tokens. - - `"generate"` + - `reasoning_tokens: number` - - `"edit"` + The number of reasoning tokens. - - `"auto"` + - `total_tokens: number` - - `background: optional "transparent" or "opaque" or "auto"` + The total number of tokens used. - 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. + - `user: optional string` - `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. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `sequence_number: number` - - `"transparent"` + The sequence number for this event. - - `"opaque"` + - `type: "response.completed"` - - `"auto"` + The type of the event. Always `response.completed`. - - `input_fidelity: optional "high" or "low"` + - `agent: optional object { agent_name }` - 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`. + The agent that owns this multi-agent streaming event. - - `"high"` + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `input_image_mask: optional object { file_id, image_url }` + - `beta_response_content_part_added_event: object { content_index, item_id, output_index, 4 more }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Emitted when a new content part is added. - - `file_id: optional string` + - `content_index: number` - File ID for the mask image. + The index of the content part that was added. - - `image_url: optional string` + - `item_id: string` - Base64-encoded mask image. + The ID of the output item that the content part was added to. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `output_index: number` - The image generation model to use. Default: `gpt-image-1`. + The index of the output item that the content part was added to. - - `"gpt-image-1"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `"gpt-image-1-mini"` + The content part that was added. - - `"gpt-image-2"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `"gpt-image-2-2026-04-21"` + A text output from the model. - - `"gpt-image-1.5"` + - `beta_response_output_refusal: object { refusal, type }` - - `"chatgpt-image-latest"` + A refusal from the model. - - `moderation: optional "auto" or "low"` + - `reasoning_text: object { text, type }` - Moderation level for the generated image. Default: `auto`. + Reasoning text from the model. - - `"auto"` + - `text: string` - - `"low"` + The reasoning text from the model. - - `output_compression: optional number` + - `type: "reasoning_text"` - Compression level for the output image. Default: 100. + The type of the reasoning text. Always `reasoning_text`. - - `output_format: optional "png" or "webp" or "jpeg"` + - `sequence_number: number` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The sequence number of this event. - - `"png"` + - `type: "response.content_part.added"` - - `"webp"` + The type of the event. Always `response.content_part.added`. - - `"jpeg"` + - `agent: optional object { agent_name }` - - `partial_images: optional number` + The agent that owns this multi-agent streaming event. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `agent_name: string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The canonical name of the agent that produced this item. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `beta_response_content_part_done_event: object { content_index, item_id, output_index, 4 more }` - - `"low"` + Emitted when a content part is done. - - `"medium"` + - `content_index: number` - - `"high"` + The index of the content part that is done. - - `"auto"` + - `item_id: string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The ID of the output item that the content part was added to. - 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`. + - `output_index: number` - - `"1024x1024"` + The index of the output item that the content part was added to. - - `"1024x1536"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `"1536x1024"` + The content part that is done. - - `"auto"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `local_shell: object { type }` + A text output from the model. - A tool that allows the model to execute shell commands in a local environment. + - `beta_response_output_refusal: object { refusal, type }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + A refusal from the model. - A tool that allows the model to execute shell commands. + - `reasoning_text: object { text, type }` - - `type: "shell"` + Reasoning text from the model. - The type of the shell tool. Always `shell`. + - `text: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The reasoning text from the model. - The tool invocation context(s). + - `type: "reasoning_text"` - - `"direct"` + The type of the reasoning text. Always `reasoning_text`. - - `"programmatic"` + - `sequence_number: number` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The sequence number of this event. - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `type: "response.content_part.done"` - - `type: "container_auto"` + The type of the event. Always `response.content_part.done`. - Automatically creates a container for this request + - `agent: optional object { agent_name }` - - `file_ids: optional array of string` + The agent that owns this multi-agent streaming event. - An optional list of uploaded files to make available to your code. + - `agent_name: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The canonical name of the agent that produced this item. - The memory limit for the container. + - `beta_response_created_event: object { response, sequence_number, type, agent }` - - `"1g"` + An event that is emitted when a response is created. - - `"4g"` + - `response: object { id, created_at, error, 31 more }` - - `"16g"` + The response that was created. - - `"64g"` + - `id: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + Unique identifier for this Response. - Network access policy for the container. + - `created_at: number` - - `beta_container_network_policy_disabled: object { type }` + Unix timestamp (in seconds) of when this Response was created. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `error: object { code, message }` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + An error object returned when the model fails to generate a Response. - An optional list of skills referenced by id or inline data. + - `incomplete_details: object { reason }` - - `beta_skill_reference: object { skill_id, type, version }` + Details about why the response is incomplete. - - `skill_id: string` + - `instructions: string or array of BetaResponseInputItem` - The ID of the referenced skill. + A system (or developer) message inserted into the model's context. - - `type: "skill_reference"` + When using 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. - References a skill created with the /v1/skills endpoint. + - `metadata: map[string]` - - `version: optional string` + 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. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `beta_inline_skill: object { description, name, source, type }` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `description: string` + Model ID used to generate the response, like `gpt-4o` 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. - The description of the skill. + - `object: "response"` - - `name: string` + The object type of this resource - always set to `response`. - The name of the skill. + - `output: array of BetaResponseOutputItem` - - `source: object { data, media_type, type }` + An array of content items generated by the model. - Inline skill payload + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `data: string` + - `parallel_tool_calls: boolean` - Base64-encoded skill zip bundle. + Whether to allow the model to run tool calls in parallel. - - `media_type: "application/zip"` + - `temperature: number` - The media type of the inline skill payload. Must be `application/zip`. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `type: "base64"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The type of the inline skill source. Must be `base64`. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `type: "inline"` + - `tools: array of BetaTool` - Defines an inline skill for this request. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `beta_local_environment: object { type, skills }` + We support the following categories of tools: - - `type: "local"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - Use a local computer environment. + - `top_p: number` - - `skills: optional array of BetaLocalSkill` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - An optional list of skills. + We generally recommend altering this or `temperature` but not both. - - `description: string` + - `background: optional boolean` - The description of the skill. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `name: string` + - `completed_at: optional number` - The name of the skill. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `path: string` + - `conversation: optional object { id }` - The path to the directory containing the skill. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `beta_container_reference: object { container_id, type }` + - `max_output_tokens: optional number` - - `container_id: string` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The ID of the referenced container. + - `max_tool_calls: optional number` - - `type: "container_reference"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - References a container created with the /v1/containers endpoint + - `moderation: optional object { input, output }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Moderation results for the response input and output, if moderated completions were requested. - 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) + - `previous_response_id: optional string` - - `name: string` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The name of the custom tool, used to identify it in tool calls. + - `prompt: optional object { id, variables, version }` - - `type: "custom"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The type of the custom tool. Always `custom`. + - `prompt_cache_key: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The tool invocation context(s). + - `prompt_cache_options: optional object { mode, ttl }` - - `"direct"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `"programmatic"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `defer_loading: optional boolean` + Deprecated. Use `prompt_cache_options.ttl` instead. - Whether this tool should be deferred and discovered via tool search. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `description: optional string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - Optional description of the custom tool, used to provide more context. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `format: optional object { type } or object { definition, syntax, type }` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The input format for the custom tool. Default is unconstrained text. + **gpt-5 and o-series models only** - - `text: object { type }` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Unconstrained free-form text. + - `safety_identifier: optional string` - - `grammar: object { definition, syntax, type }` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - A grammar defined by the user. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `definition: string` + Specifies the processing type used for serving the request. - The grammar definition. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `syntax: "lark" or "regex"` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The syntax of the grammar definition. One of `lark` or `regex`. + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `"lark"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"regex"` + - `text: optional object { format, verbosity }` - - `type: "grammar"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - Grammar format. Always `grammar`. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `beta_namespace_tool: object { description, name, tools, type }` + - `top_logprobs: optional number` - Groups function/custom tools under a shared namespace. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `description: string` + - `truncation: optional "auto" or "disabled"` - A description of the namespace shown to the model. + The truncation strategy to use for the model response. - - `name: string` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The namespace name used in tool calls (for example, `crm`). + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The function/custom tools available inside this namespace. + - `user: optional string` - - `function: object { name, type, allowed_callers, 5 more }` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `name: string` + - `sequence_number: number` - - `type: "function"` + The sequence number for this event. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "response.created"` - The tool invocation context(s). + The type of the event. Always `response.created`. - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that owns this multi-agent streaming event. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this function should be deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `beta_response_error_event: object { code, message, param, 3 more }` - - `output_schema: optional map[unknown]` + Emitted when an error occurs. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `code: string` - - `parameters: optional unknown` + The error code. - - `strict: optional boolean` + - `message: string` - 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. + The error message. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `param: string` - 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) + The error parameter. - - `name: string` + - `sequence_number: number` - The name of the custom tool, used to identify it in tool calls. + The sequence number of this event. - - `type: "custom"` + - `type: "error"` - The type of the custom tool. Always `custom`. + The type of the event. Always `error`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that owns this multi-agent streaming event. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this tool should be deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `beta_response_file_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - Optional description of the custom tool, used to provide more context. + Emitted when a file search call is completed (results found). - - `format: optional object { type } or object { definition, syntax, type }` + - `item_id: string` - The input format for the custom tool. Default is unconstrained text. + The ID of the output item that the file search call is initiated. - - `type: "namespace"` + - `output_index: number` - The type of the tool. Always `namespace`. + The index of the output item that the file search call is initiated. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `sequence_number: number` - Hosted or BYOT tool search configuration for deferred tools. + The sequence number of this event. - - `type: "tool_search"` + - `type: "response.file_search_call.completed"` - The type of the tool. Always `tool_search`. + The type of the event. Always `response.file_search_call.completed`. - - `description: optional string` + - `agent: optional object { agent_name }` - Description shown to the model for a client-executed tool search tool. + The agent that owns this multi-agent streaming event. - - `execution: optional "server" or "client"` + - `agent_name: string` - Whether tool search is executed by the server or by the client. + The canonical name of the agent that produced this item. - - `"server"` + - `beta_response_file_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `"client"` + Emitted when a file search call is initiated. - - `parameters: optional unknown` + - `item_id: string` - Parameter schema for a client-executed tool search tool. + The ID of the output item that the file search call is initiated. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `output_index: number` - 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). + The index of the output item that the file search call is initiated. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `sequence_number: number` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The sequence number of this event. - - `"web_search_preview"` + - `type: "response.file_search_call.in_progress"` - - `"web_search_preview_2025_03_11"` + The type of the event. Always `response.file_search_call.in_progress`. - - `search_content_types: optional array of "text" or "image"` + - `agent: optional object { agent_name }` - - `"text"` + The agent that owns this multi-agent streaming event. - - `"image"` + - `agent_name: string` - - `search_context_size: optional "low" or "medium" or "high"` + The canonical name of the agent that produced this item. - 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. + - `beta_response_file_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` - - `"low"` + Emitted when a file search is currently searching. - - `"medium"` + - `item_id: string` - - `"high"` + The ID of the output item that the file search call is initiated. - - `user_location: optional object { type, city, country, 2 more }` + - `output_index: number` - The user's location. + The index of the output item that the file search call is searching. - - `type: "approximate"` + - `sequence_number: number` - The type of location approximation. Always `approximate`. + The sequence number of this event. - - `city: optional string` + - `type: "response.file_search_call.searching"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the event. Always `response.file_search_call.searching`. - - `country: optional string` + - `agent: optional object { agent_name }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The agent that owns this multi-agent streaming event. - - `region: optional string` + - `agent_name: string` - Free text input for the region of the user, e.g. `California`. + The canonical name of the agent that produced this item. - - `timezone: optional string` + - `beta_response_function_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Emitted when there is a partial function-call arguments delta. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `delta: string` - Allows the assistant to create, delete, or update files using unified diffs. + The function-call arguments delta that is added. - - `type: "apply_patch"` + - `item_id: string` - The type of the tool. Always `apply_patch`. + The ID of the output item that the function-call arguments delta is added to. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output_index: number` - The tool invocation context(s). + The index of the output item that the function-call arguments delta is added to. - - `"direct"` + - `sequence_number: number` - - `"programmatic"` + The sequence number of this event. - - `type: "tool_search_output"` + - `type: "response.function_call_arguments.delta"` - The type of the item. Always `tool_search_output`. + The type of the event. Always `response.function_call_arguments.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `created_by: optional string` + - `beta_response_function_call_arguments_done_event: object { arguments, item_id, name, 4 more }` - The identifier of the actor that created the item. + Emitted when function-call arguments are finalized. - - `additional_tools: object { id, role, tools, 2 more }` + - `arguments: string` - - `id: string` + The function-call arguments. - The unique ID of the additional tools item. + - `item_id: string` - - `role: "unknown" or "user" or "assistant" or 5 more` + The ID of the item. - The role that provided the additional tools. + - `name: string` - - `"unknown"` + The name of the function that was called. - - `"user"` + - `output_index: number` - - `"assistant"` + The index of the output item. - - `"system"` + - `sequence_number: number` - - `"critic"` + The sequence number of this event. - - `"discriminator"` + - `type: "response.function_call_arguments.done"` - - `"developer"` + - `agent: optional object { agent_name }` - - `"tool"` + The agent that owns this multi-agent streaming event. - - `tools: array of BetaTool` + - `agent_name: string` - The additional tool definitions made available at this item. + The canonical name of the agent that produced this item. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `beta_response_in_progress_event: object { response, sequence_number, type, agent }` - 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). + Emitted when the response is in progress. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `response: object { id, created_at, error, 31 more }` - 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). + The response that is in progress. - - `beta_computer_tool: object { type }` + - `id: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Unique identifier for this Response. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `created_at: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Unix timestamp (in seconds) of when this Response was created. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `error: object { code, message }` - 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). + An error object returned when the model fails to generate a Response. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `incomplete_details: object { reason }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + Details about why the response is incomplete. - - `code_interpreter: object { container, type, allowed_callers }` + - `instructions: string or array of BetaResponseInputItem` - A tool that runs Python code to help generate a response to a prompt. + A system (or developer) message inserted into the model's context. - - `programmatic_tool_calling: object { type }` + When using 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. - - `image_generation: object { type, action, background, 9 more }` + - `metadata: map[string]` - A tool that generates images using the GPT image models. + 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. - - `local_shell: object { type }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A tool that allows the model to execute shell commands in a local environment. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + Model ID used to generate the response, like `gpt-4o` 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. - A tool that allows the model to execute shell commands. + - `object: "response"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The object type of this resource - always set to `response`. - 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) + - `output: array of BetaResponseOutputItem` - - `beta_namespace_tool: object { description, name, tools, type }` + An array of content items generated by the model. - Groups function/custom tools under a shared namespace. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `parallel_tool_calls: boolean` - Hosted or BYOT tool search configuration for deferred tools. + Whether to allow the model to run tool calls in parallel. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `temperature: number` - 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). + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - Allows the assistant to create, delete, or update files using unified diffs. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `type: "additional_tools"` + - `tools: array of BetaTool` - The type of the item. Always `additional_tools`. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `agent: optional object { agent_name }` + We support the following categories of tools: - The agent that produced this item. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `agent_name: string` + - `top_p: number` - The canonical name of the agent that produced this item. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + We generally recommend altering this or `temperature` but not both. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `background: optional boolean` - - `id: string` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The unique ID of the compaction item. + - `completed_at: optional number` - - `encrypted_content: string` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The encrypted content that was produced by compaction. + - `conversation: optional object { id }` - - `type: "compaction"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The type of the item. Always `compaction`. + - `max_output_tokens: optional number` - - `agent: optional object { agent_name }` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The agent that produced this item. + - `max_tool_calls: optional number` - - `agent_name: string` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The canonical name of the agent that produced this item. + - `moderation: optional object { input, output }` - - `created_by: optional string` + Moderation results for the response input and output, if moderated completions were requested. - The identifier of the actor that created the item. + - `previous_response_id: optional string` - - `image_generation_call: object { id, result, status, 2 more }` + 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`. - An image generation request made by the model. + - `prompt: optional object { id, variables, version }` - - `id: string` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The unique ID of the image generation call. + - `prompt_cache_key: optional string` - - `result: string` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The generated image encoded in base64. + - `prompt_cache_options: optional object { mode, ttl }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - The status of the image generation call. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `"in_progress"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `"completed"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"generating"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"failed"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `type: "image_generation_call"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The type of the image generation call. Always `image_generation_call`. + **gpt-5 and o-series models only** - - `agent: optional object { agent_name }` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The agent that produced this item. + - `safety_identifier: optional string` - - `agent_name: string` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The canonical name of the agent that produced this item. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + Specifies the processing type used for serving the request. - A tool call to run code. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `id: string` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The unique ID of the code interpreter tool call. + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `code: string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The code to run, or null if not available. + - `text: optional object { format, verbosity }` - - `container_id: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The ID of the container used to run the code. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `outputs: array of object { logs, type } or object { type, url }` + - `top_logprobs: optional number` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `logs: object { logs, type }` + - `truncation: optional "auto" or "disabled"` - The logs output from the code interpreter. + The truncation strategy to use for the model response. - - `logs: string` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The logs output from the code interpreter. + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `type: "logs"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The type of the output. Always `logs`. + - `user: optional string` - - `image: object { type, url }` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The image output from the code interpreter. + - `sequence_number: number` - - `type: "image"` + The sequence number of this event. - The type of the output. Always `image`. + - `type: "response.in_progress"` - - `url: string` + The type of the event. Always `response.in_progress`. - The URL of the image output from the code interpreter. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The agent that owns this multi-agent streaming event. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `beta_response_failed_event: object { response, sequence_number, type, agent }` - - `"incomplete"` + An event that is emitted when a response fails. - - `"interpreting"` + - `response: object { id, created_at, error, 31 more }` - - `"failed"` + The response that failed. - - `type: "code_interpreter_call"` + - `id: string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Unique identifier for this Response. - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that produced this item. + Unix timestamp (in seconds) of when this Response was created. - - `agent_name: string` + - `error: object { code, message }` - The canonical name of the agent that produced this item. + An error object returned when the model fails to generate a Response. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `incomplete_details: object { reason }` - A tool call to run a command on the local shell. + Details about why the response is incomplete. - - `id: string` + - `instructions: string or array of BetaResponseInputItem` - The unique ID of the local shell call. + A system (or developer) message inserted into the model's context. - - `action: object { command, env, type, 3 more }` + When using 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. - Execute a shell command on the server. + - `metadata: map[string]` - - `command: array of string` + 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. - The command to run. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `env: map[string]` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - Environment variables to set for the command. + Model ID used to generate the response, like `gpt-4o` 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. - - `type: "exec"` + - `object: "response"` - The type of the local shell action. Always `exec`. + The object type of this resource - always set to `response`. - - `timeout_ms: optional number` + - `output: array of BetaResponseOutputItem` - Optional timeout in milliseconds for the command. + An array of content items generated by the model. - - `user: optional string` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - Optional user to run the command as. + - `parallel_tool_calls: boolean` - - `working_directory: optional string` + Whether to allow the model to run tool calls in parallel. - Optional working directory to run the command in. + - `temperature: number` - - `call_id: string` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The unique ID of the local shell tool call generated by the model. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `status: "in_progress" or "completed" or "incomplete"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The status of the local shell call. + - `tools: array of BetaTool` - - `"in_progress"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"completed"` + We support the following categories of tools: - - `"incomplete"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `type: "local_shell_call"` + - `top_p: number` - The type of the local shell call. Always `local_shell_call`. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `agent: optional object { agent_name }` + We generally recommend altering this or `temperature` but not both. - The agent that produced this item. + - `background: optional boolean` - - `agent_name: string` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The canonical name of the agent that produced this item. + - `completed_at: optional number` - - `local_shell_call_output: object { id, output, type, 2 more }` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The output of a local shell tool call. + - `conversation: optional object { id }` - - `id: string` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The unique ID of the local shell tool call generated by the model. + - `max_output_tokens: optional number` - - `output: string` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - A JSON string of the output of the local shell tool call. + - `max_tool_calls: optional number` - - `type: "local_shell_call_output"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: optional object { input, output }` - The type of the local shell tool call output. Always `local_shell_call_output`. + Moderation results for the response input and output, if moderated completions were requested. - - `agent: optional object { agent_name }` + - `previous_response_id: optional string` - The agent that produced this item. + 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`. - - `agent_name: string` + - `prompt: optional object { id, variables, version }` - The canonical name of the agent that produced this item. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `status: optional "in_progress" or "completed" or "incomplete"` + - `prompt_cache_key: optional string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"in_progress"` + - `prompt_cache_options: optional object { mode, ttl }` - - `"completed"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `"incomplete"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + Deprecated. Use `prompt_cache_options.ttl` instead. - A tool call that executes one or more shell commands in a managed environment. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `id: string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The unique ID of the shell tool call. Populated when this item is returned via API. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `action: object { commands, max_output_length, timeout_ms }` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The shell commands and limits that describe how to run the tool call. + **gpt-5 and o-series models only** - - `commands: array of string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `max_output_length: number` + - `safety_identifier: optional string` - Optional maximum number of characters to return from each command. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `timeout_ms: number` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - Optional timeout in milliseconds for the commands. + Specifies the processing type used for serving the request. - - `call_id: string` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The unique ID of the shell tool call generated by the model. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - Represents the use of a local environment to perform shell actions. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `beta_response_local_environment: object { type }` + - `text: optional object { format, verbosity }` - Represents the use of a local environment to perform shell actions. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `type: "local"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The environment type. Always `local`. + - `top_logprobs: optional number` - - `beta_response_container_reference: object { container_id, type }` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - Represents a container created with /v1/containers. + - `truncation: optional "auto" or "disabled"` - - `container_id: string` + The truncation strategy to use for the model response. - - `type: "container_reference"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The environment type. Always `container_reference`. + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `status: "in_progress" or "completed" or "incomplete"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `user: optional string` - - `"in_progress"` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number of this event. - - `type: "shell_call"` + - `type: "response.failed"` - The type of the item. Always `shell_call`. + The type of the event. Always `response.failed`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. + - `beta_response_incomplete_event: object { response, sequence_number, type, agent }` - - `direct: object { type }` + An event that is emitted when a response finishes as incomplete. - - `program: object { caller_id, type }` + - `response: object { id, created_at, error, 31 more }` - - `caller_id: string` + The response that was incomplete. - The call ID of the program item that produced this tool call. + - `id: string` - - `type: "program"` + Unique identifier for this Response. - - `created_by: optional string` + - `created_at: number` - The ID of the entity that created this tool call. + Unix timestamp (in seconds) of when this Response was created. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `error: object { code, message }` - The output of a shell tool call that was emitted. + An error object returned when the model fails to generate a Response. - - `id: string` + - `incomplete_details: object { reason }` - The unique ID of the shell call output. Populated when this item is returned via API. + Details about why the response is incomplete. - - `call_id: string` + - `instructions: string or array of BetaResponseInputItem` - The unique ID of the shell tool call generated by the model. + A system (or developer) message inserted into the model's context. - - `max_output_length: number` + When using 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. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `metadata: map[string]` - - `output: array of object { outcome, stderr, stdout, created_by }` + 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. - An array of shell call output contents + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `outcome: object { type } or object { exit_code, type }` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + Model ID used to generate the response, like `gpt-4o` 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. - - `timeout: object { type }` + - `object: "response"` - Indicates that the shell call exceeded its configured time limit. + The object type of this resource - always set to `response`. - - `exit: object { exit_code, type }` + - `output: array of BetaResponseOutputItem` - Indicates that the shell commands finished and returned an exit code. + An array of content items generated by the model. - - `exit_code: number` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - Exit code from the shell process. + - `parallel_tool_calls: boolean` - - `type: "exit"` + Whether to allow the model to run tool calls in parallel. - The outcome type. Always `exit`. + - `temperature: number` - - `stderr: string` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The standard error output that was captured. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `stdout: string` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - The standard output that was captured. + - `tools: array of BetaTool` - - `created_by: optional string` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - The identifier of the actor that created the item. + We support the following categories of tools: - - `status: "in_progress" or "completed" or "incomplete"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `top_p: number` - - `"in_progress"` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `"completed"` + We generally recommend altering this or `temperature` but not both. - - `"incomplete"` + - `background: optional boolean` - - `type: "shell_call_output"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The type of the shell call output. Always `shell_call_output`. + - `completed_at: optional number` - - `agent: optional object { agent_name }` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The agent that produced this item. + - `conversation: optional object { id }` - - `agent_name: string` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The canonical name of the agent that produced this item. + - `max_output_tokens: optional number` - - `caller: optional object { type } or object { caller_id, type }` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The execution context that produced this tool call. + - `max_tool_calls: optional number` - - `direct: object { type }` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `program: object { caller_id, type }` + - `moderation: optional object { input, output }` - - `caller_id: string` + Moderation results for the response input and output, if moderated completions were requested. - The call ID of the program item that produced this tool call. + - `previous_response_id: optional string` - - `type: "program"` + 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`. - - `created_by: optional string` + - `prompt: optional object { id, variables, version }` - The identifier of the actor that created the item. + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `prompt_cache_key: optional string` - A tool call that applies file diffs by creating, deleting, or updating files. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `id: string` + - `prompt_cache_options: optional object { mode, ttl }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `call_id: string` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The unique ID of the apply patch tool call generated by the model. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `create_file: object { diff, path, type }` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - Instruction describing how to create a file via the apply_patch tool. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `diff: string` + **gpt-5 and o-series models only** - Diff to apply. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `path: string` + - `safety_identifier: optional string` - Path of the file to create. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: "create_file"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - Create a new file with the provided diff. + Specifies the processing type used for serving the request. - - `delete_file: object { path, type }` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - Instruction describing how to delete a file via the apply_patch tool. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `path: string` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - Path of the file to delete. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `type: "delete_file"` + - `text: optional object { format, verbosity }` - Delete the specified file. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `update_file: object { diff, path, type }` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - Instruction describing how to update a file via the apply_patch tool. + - `top_logprobs: optional number` - - `diff: string` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - Diff to apply. + - `truncation: optional "auto" or "disabled"` - - `path: string` + The truncation strategy to use for the model response. - Path of the file to update. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `type: "update_file"` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - Update an existing file with the provided diff. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `status: "in_progress" or "completed"` + - `user: optional string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"in_progress"` + - `sequence_number: number` - - `"completed"` + The sequence number of this event. - - `type: "apply_patch_call"` + - `type: "response.incomplete"` - The type of the item. Always `apply_patch_call`. + The type of the event. Always `response.incomplete`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` + - `beta_response_output_item_added_event: object { item, output_index, sequence_number, 2 more }` - - `caller_id: string` + Emitted when a new output item is added. - The call ID of the program item that produced this tool call. + - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` - - `type: "program"` + The output item that was added. - - `created_by: optional string` + - `beta_response_output_message: object { id, content, role, 4 more }` - The ID of the entity that created this tool call. + An output message from the model. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The output emitted by an apply patch tool call. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `id: string` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `call_id: string` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - The unique ID of the apply patch tool call generated by the model. + - `agent_message: object { id, author, content, 3 more }` - - `status: "completed" or "failed"` + - `multi_agent_call: object { id, action, arguments, 3 more }` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - - `"completed"` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `"failed"` + 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. - - `type: "apply_patch_call_output"` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - The type of the item. Always `apply_patch_call_output`. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `agent: optional object { agent_name }` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - The agent that produced this item. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `program: object { id, call_id, code, 3 more }` - - `caller: optional object { type } or object { caller_id, type }` + - `program_output: object { id, call_id, result, 3 more }` - The execution context that produced this tool call. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `direct: object { type }` + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `program: object { caller_id, type }` + - `additional_tools: object { id, role, tools, 2 more }` - - `caller_id: string` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - The call ID of the program item that produced this tool call. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `type: "program"` + - `image_generation_call: object { id, result, status, 2 more }` - - `created_by: optional string` + An image generation request made by the model. - The ID of the entity that created this tool call output. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `output: optional string` + A tool call to run code. - Optional textual output returned by the apply patch tool. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `mcp_call: object { id, arguments, name, 7 more }` + A tool call to run a command on the local shell. - An invocation of a tool on an MCP server. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `id: string` + The output of a local shell tool call. - The unique ID of the tool call. + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - `arguments: string` + A tool call that executes one or more shell commands in a managed environment. - A JSON string of the arguments passed to the tool. + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `name: string` + The output of a shell tool call that was emitted. - The name of the tool that was run. + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `server_label: string` + A tool call that applies file diffs by creating, deleting, or updating files. - The label of the MCP server running the tool. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `type: "mcp_call"` + The output emitted by an apply patch tool call. - The type of the item. Always `mcp_call`. + - `mcp_call: object { id, arguments, name, 7 more }` - - `agent: optional object { agent_name }` + An invocation of a tool on an MCP server. - The agent that produced this item. + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `agent_name: string` + A list of tools available on an MCP server. - The canonical name of the agent that produced this item. + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `approval_request_id: optional string` + A request for human approval of a tool invocation. - 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. + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - - `error: optional string` + A response to an MCP approval request. - The error from the tool call, if any. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `output: optional string` + A call to a custom tool created by the model. - The output from the tool call. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + The output of a custom tool call from your code, being sent back to the model. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `output_index: number` - - `"in_progress"` + The index of the output item that was added. - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number of this event. - - `"calling"` + - `type: "response.output_item.added"` - - `"failed"` + The type of the event. Always `response.output_item.added`. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `agent: optional object { agent_name }` - A list of tools available on an MCP server. + The agent that owns this multi-agent streaming event. - - `id: string` + - `agent_name: string` - The unique ID of the list. + The canonical name of the agent that produced this item. - - `server_label: string` + - `beta_response_output_item_done_event: object { item, output_index, sequence_number, 2 more }` - The label of the MCP server. + Emitted when an output item is marked done. - - `tools: array of object { input_schema, name, annotations, description }` + - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` - The tools available on the server. + The output item that was marked done. - - `input_schema: unknown` + - `beta_response_output_message: object { id, content, role, 4 more }` - The JSON schema describing the tool's input. + An output message from the model. - - `name: string` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The name of the tool. + 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. - - `annotations: optional unknown` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - Additional annotations about the tool. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `description: optional string` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - The description of the tool. + - `agent_message: object { id, author, content, 3 more }` - - `type: "mcp_list_tools"` + - `multi_agent_call: object { id, action, arguments, 3 more }` - The type of the item. Always `mcp_list_tools`. + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - - `agent: optional object { agent_name }` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - The agent that produced this item. + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `agent_name: string` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - The canonical name of the agent that produced this item. + 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. - - `error: optional string` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - Error message if the server could not list tools. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - A request for human approval of a tool invocation. + - `program: object { id, call_id, code, 3 more }` - - `id: string` + - `program_output: object { id, call_id, result, 3 more }` - The unique ID of the approval request. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `arguments: string` + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - A JSON string of arguments for the tool. + - `additional_tools: object { id, role, tools, 2 more }` - - `name: string` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - The name of the tool to run. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `server_label: string` + - `image_generation_call: object { id, result, status, 2 more }` - The label of the MCP server making the request. + An image generation request made by the model. - - `type: "mcp_approval_request"` + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - The type of the item. Always `mcp_approval_request`. + A tool call to run code. - - `agent: optional object { agent_name }` + - `local_shell_call: object { id, action, call_id, 3 more }` - The agent that produced this item. + A tool call to run a command on the local shell. - - `agent_name: string` + - `local_shell_call_output: object { id, output, type, 2 more }` - The canonical name of the agent that produced this item. + The output of a local shell tool call. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - A response to an MCP approval request. + A tool call that executes one or more shell commands in a managed environment. - - `id: string` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - The unique ID of the approval response + The output of a shell tool call that was emitted. - - `approval_request_id: string` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - The ID of the approval request being answered. + A tool call that applies file diffs by creating, deleting, or updating files. - - `approve: boolean` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - Whether the request was approved. + The output emitted by an apply patch tool call. - - `type: "mcp_approval_response"` + - `mcp_call: object { id, arguments, name, 7 more }` - The type of the item. Always `mcp_approval_response`. + An invocation of a tool on an MCP server. - - `agent: optional object { agent_name }` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The agent that produced this item. + A list of tools available on an MCP server. - - `agent_name: string` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - The canonical name of the agent that produced this item. + A request for human approval of a tool invocation. - - `reason: optional string` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - Optional reason for the decision. + A response to an MCP approval request. - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` A call to a custom tool created by the model. - - `call_id: string` - - An identifier used to map this custom tool call to a tool call output. - - - `input: string` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - The input for the custom tool call generated by the model. + The output of a custom tool call from your code, being sent back to the model. - - `name: string` + - `output_index: number` - The name of the custom tool being called. + The index of the output item that was marked done. - - `type: "custom_tool_call"` + - `sequence_number: number` - The type of the custom tool call. Always `custom_tool_call`. + The sequence number of this event. - - `id: optional string` + - `type: "response.output_item.done"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the event. Always `response.output_item.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_reasoning_summary_part_added_event: object { item_id, output_index, part, 4 more }` - The execution context that produced this tool call. + Emitted when a new reasoning summary part is added. - - `direct: object { type }` + - `item_id: string` - - `program: object { caller_id, type }` + The ID of the item this summary part is associated with. - - `caller_id: string` + - `output_index: number` - The call ID of the program item that produced this tool call. + The index of the output item this summary part is associated with. - - `type: "program"` + - `part: object { text, type }` - - `namespace: optional string` + The summary part that was added. - The namespace of the custom tool being called. + - `text: string` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The text of the summary part. - The output of a custom tool call from your code, being sent back to the model. + - `type: "summary_text"` - - `id: string` + The type of the summary part. Always `summary_text`. - The unique ID of the custom tool call output item. + - `sequence_number: number` - - `status: "in_progress" or "completed" or "incomplete"` + The sequence number of this event. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `summary_index: number` - - `"in_progress"` + The index of the summary part within the reasoning summary. - - `"completed"` + - `type: "response.reasoning_summary_part.added"` - - `"incomplete"` + The type of the event. Always `response.reasoning_summary_part.added`. - - `created_by: optional string` + - `agent: optional object { agent_name }` - The identifier of the actor that created the item. + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_reasoning_summary_part_done_event: object { item_id, output_index, part, 5 more }` + + Emitted when a reasoning summary part is completed. + + - `item_id: string` + + The ID of the item this summary part is associated with. - `output_index: number` - The index of the output item that was added. + The index of the output item this summary part is associated with. + + - `part: object { text, type }` + + The completed summary part. + + - `text: string` + + The text of the summary part. + + - `type: "summary_text"` + + The type of the summary part. Always `summary_text`. - `sequence_number: number` The sequence number of this event. - - `type: "response.output_item.added"` + - `summary_index: number` - The type of the event. Always `response.output_item.added`. + The index of the summary part within the reasoning summary. + + - `type: "response.reasoning_summary_part.done"` + + The type of the event. Always `response.reasoning_summary_part.done`. - `agent: optional object { agent_name }` @@ -101928,1282 +113784,1344 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. -### Beta Response Output Item Done Event - -- `beta_response_output_item_done_event: object { item, output_index, sequence_number, 2 more }` + - `status: optional "incomplete"` - Emitted when an output item is marked done. + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` + - `"incomplete"` - The output item that was marked done. + - `beta_response_reasoning_summary_text_delta_event: object { delta, item_id, output_index, 4 more }` - - `beta_response_output_message: object { id, content, role, 4 more }` + Emitted when a delta is added to a reasoning summary text. - An output message from the model. + - `delta: string` - - `id: string` + The text delta that was added to the summary. - The unique ID of the output message. + - `item_id: string` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The ID of the item this summary text delta is associated with. - The content of the output message. + - `output_index: number` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + The index of the output item this summary text delta is associated with. - A text output from the model. + - `sequence_number: number` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The sequence number of this event. - The annotations of the text output. + - `summary_index: number` - - `file_citation: object { file_id, filename, index, type }` + The index of the summary part within the reasoning summary. - A citation to a file. + - `type: "response.reasoning_summary_text.delta"` - - `file_id: string` + The type of the event. Always `response.reasoning_summary_text.delta`. - The ID of the file. + - `agent: optional object { agent_name }` - - `filename: string` + The agent that owns this multi-agent streaming event. - The filename of the file cited. + - `agent_name: string` - - `index: number` + The canonical name of the agent that produced this item. - The index of the file in the list of files. + - `beta_response_reasoning_summary_text_done_event: object { item_id, output_index, sequence_number, 4 more }` - - `type: "file_citation"` + Emitted when a reasoning summary text is completed. - The type of the file citation. Always `file_citation`. + - `item_id: string` - - `url_citation: object { end_index, start_index, title, 2 more }` + The ID of the item this summary text is associated with. - A citation for a web resource used to generate a model response. + - `output_index: number` - - `end_index: number` + The index of the output item this summary text is associated with. - The index of the last character of the URL citation in the message. + - `sequence_number: number` - - `start_index: number` + The sequence number of this event. - The index of the first character of the URL citation in the message. + - `summary_index: number` - - `title: string` + The index of the summary part within the reasoning summary. - The title of the web resource. + - `text: string` - - `type: "url_citation"` + The full text of the completed reasoning summary. - The type of the URL citation. Always `url_citation`. + - `type: "response.reasoning_summary_text.done"` - - `url: string` + The type of the event. Always `response.reasoning_summary_text.done`. - The URL of the web resource. + - `agent: optional object { agent_name }` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + The agent that owns this multi-agent streaming event. - A citation for a container file used to generate a model response. + - `agent_name: string` - - `container_id: string` + The canonical name of the agent that produced this item. - The ID of the container file. + - `beta_response_reasoning_text_delta_event: object { content_index, delta, item_id, 4 more }` - - `end_index: number` + Emitted when a delta is added to a reasoning text. - The index of the last character of the container file citation in the message. + - `content_index: number` - - `file_id: string` + The index of the reasoning content part this delta is associated with. - The ID of the file. + - `delta: string` - - `filename: string` + The text delta that was added to the reasoning content. - The filename of the container file cited. + - `item_id: string` - - `start_index: number` + The ID of the item this reasoning text delta is associated with. - The index of the first character of the container file citation in the message. + - `output_index: number` - - `type: "container_file_citation"` + The index of the output item this reasoning text delta is associated with. - The type of the container file citation. Always `container_file_citation`. + - `sequence_number: number` - - `file_path: object { file_id, index, type }` + The sequence number of this event. - A path to a file. + - `type: "response.reasoning_text.delta"` - - `file_id: string` + The type of the event. Always `response.reasoning_text.delta`. - The ID of the file. + - `agent: optional object { agent_name }` - - `index: number` + The agent that owns this multi-agent streaming event. - The index of the file in the list of files. + - `agent_name: string` - - `type: "file_path"` + The canonical name of the agent that produced this item. - The type of the file path. Always `file_path`. + - `beta_response_reasoning_text_done_event: object { content_index, item_id, output_index, 4 more }` - - `text: string` + Emitted when a reasoning text is completed. - The text output from the model. + - `content_index: number` - - `type: "output_text"` + The index of the reasoning content part. - The type of the output text. Always `output_text`. + - `item_id: string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The ID of the item this reasoning text is associated with. - - `token: string` + - `output_index: number` - - `bytes: array of number` + The index of the output item this reasoning text is associated with. - - `logprob: number` + - `sequence_number: number` - - `top_logprobs: array of object { token, bytes, logprob }` + The sequence number of this event. - - `token: string` + - `text: string` - - `bytes: array of number` + The full text of the completed reasoning content. - - `logprob: number` + - `type: "response.reasoning_text.done"` - - `beta_response_output_refusal: object { refusal, type }` + The type of the event. Always `response.reasoning_text.done`. - A refusal from the model. + - `agent: optional object { agent_name }` - - `refusal: string` + The agent that owns this multi-agent streaming event. - The refusal explanation from the model. + - `agent_name: string` - - `type: "refusal"` + The canonical name of the agent that produced this item. - The type of the refusal. Always `refusal`. + - `beta_response_refusal_delta_event: object { content_index, delta, item_id, 4 more }` - - `role: "assistant"` + Emitted when there is a partial refusal text. - The role of the output message. Always `assistant`. + - `content_index: number` - - `status: "in_progress" or "completed" or "incomplete"` + The index of the content part that the refusal text is added to. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `delta: string` - - `"in_progress"` + The refusal text that is added. - - `"completed"` + - `item_id: string` - - `"incomplete"` + The ID of the output item that the refusal text is added to. - - `type: "message"` + - `output_index: number` - The type of the output message. Always `message`. + The index of the output item that the refusal text is added to. - - `agent: optional object { agent_name }` + - `sequence_number: number` - The agent that produced this item. + The sequence number of this event. - - `agent_name: string` + - `type: "response.refusal.delta"` - The canonical name of the agent that produced this item. + The type of the event. Always `response.refusal.delta`. - - `phase: optional "commentary"` + - `agent: optional object { agent_name }` - 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. + The agent that owns this multi-agent streaming event. - - `"commentary"` + - `agent_name: string` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + The canonical name of the agent that produced this item. - 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. + - `beta_response_refusal_done_event: object { content_index, item_id, output_index, 4 more }` - - `id: string` + Emitted when refusal text is finalized. - The unique ID of the file search tool call. + - `content_index: number` - - `queries: array of string` + The index of the content part that the refusal text is finalized. - The queries used to search for files. + - `item_id: string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The ID of the output item that the refusal text is finalized. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `output_index: number` - - `"in_progress"` + The index of the output item that the refusal text is finalized. - - `"searching"` + - `refusal: string` - - `"completed"` + The refusal text that is finalized. - - `"incomplete"` + - `sequence_number: number` - - `"failed"` + The sequence number of this event. - - `type: "file_search_call"` + - `type: "response.refusal.done"` - The type of the file search tool call. Always `file_search_call`. + The type of the event. Always `response.refusal.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. + - `beta_response_text_delta_event: object { content_index, delta, item_id, 5 more }` - - `attributes: optional map[string or number or boolean]` + Emitted when there is an additional text delta. - 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. + - `content_index: number` - - `union_member_0: string` + The index of the content part that the text delta was added to. - - `union_member_1: number` + - `delta: string` - - `union_member_2: boolean` + The text delta that was added. - - `file_id: optional string` + - `item_id: string` - The unique ID of the file. + The ID of the output item that the text delta was added to. - - `filename: optional string` + - `logprobs: array of object { token, logprob, top_logprobs }` - The name of the file. + The log probabilities of the tokens in the delta. - - `score: optional number` + - `token: string` - The relevance score of the file - a value between 0 and 1. + A possible text token. - - `text: optional string` + - `logprob: number` - The text that was retrieved from the file. + The log probability of this token. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `top_logprobs: optional array of object { token, logprob }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The log probabilities of up to 20 of the most likely tokens. - - `arguments: string` + - `token: optional string` - A JSON string of the arguments to pass to the function. + A possible text token. - - `call_id: string` + - `logprob: optional number` - The unique ID of the function tool call generated by the model. + The log probability of this token. - - `name: string` + - `output_index: number` - The name of the function to run. + The index of the output item that the text delta was added to. - - `type: "function_call"` + - `sequence_number: number` - The type of the function tool call. Always `function_call`. + The sequence number for this event. - - `id: optional string` + - `type: "response.output_text.delta"` - The unique ID of the function tool call. + The type of the event. Always `response.output_text.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_text_done_event: object { content_index, item_id, logprobs, 5 more }` - The execution context that produced this tool call. + Emitted when text content is finalized. - - `direct: object { type }` + - `content_index: number` - - `program: object { caller_id, type }` + The index of the content part that the text content is finalized. - - `caller_id: string` + - `item_id: string` - The call ID of the program item that produced this tool call. + The ID of the output item that the text content is finalized. - - `type: "program"` + - `logprobs: array of object { token, logprob, top_logprobs }` - - `namespace: optional string` + The log probabilities of the tokens in the delta. - The namespace of the function to run. + - `token: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + A possible text token. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `logprob: number` - - `"in_progress"` + The log probability of this token. - - `"completed"` + - `top_logprobs: optional array of object { token, logprob }` - - `"incomplete"` + The log probabilities of up to 20 of the most likely tokens. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `token: optional string` + + A possible text token. - - `id: string` + - `logprob: optional number` - The unique ID of the function call tool output. + The log probability of this token. - - `call_id: string` + - `output_index: number` - The unique ID of the function tool call generated by the model. + The index of the output item that the text content is finalized. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `sequence_number: number` - The output from the function call generated by your code. - Can be a string or an list of output content. + The sequence number for this event. - - `string output: string` + - `text: string` - A string of the output of the function call. + The text content that is finalized. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `type: "response.output_text.done"` - Text, image, or file output of the function call. + The type of the event. Always `response.output_text.done`. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `agent: optional object { agent_name }` - A text input to the model. + The agent that owns this multi-agent streaming event. - - `text: string` + - `agent_name: string` - The text input to the model. + The canonical name of the agent that produced this item. - - `type: "input_text"` + - `beta_response_web_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - The type of the input item. Always `input_text`. + Emitted when a web search call is completed. - - `prompt_cache_breakpoint: optional object { mode }` + - `item_id: string` - 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. + Unique ID for the output item associated with the web search call. - - `mode: "explicit"` + - `output_index: number` - The breakpoint mode. Always `explicit`. + The index of the output item that the web search call is associated with. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `sequence_number: number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The sequence number of the web search call being processed. - - `detail: "low" or "high" or "auto" or "original"` + - `type: "response.web_search_call.completed"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The type of the event. Always `response.web_search_call.completed`. - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that owns this multi-agent streaming event. - - `"auto"` + - `agent_name: string` - - `"original"` + The canonical name of the agent that produced this item. - - `type: "input_image"` + - `beta_response_web_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - The type of the input item. Always `input_image`. + Emitted when a web search call is initiated. - - `file_id: optional string` + - `item_id: string` - The ID of the file to be sent to the model. + Unique ID for the output item associated with the web search call. - - `image_url: optional string` + - `output_index: number` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The index of the output item that the web search call is associated with. - - `prompt_cache_breakpoint: optional object { mode }` + - `sequence_number: number` - 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. + The sequence number of the web search call being processed. - - `mode: "explicit"` + - `type: "response.web_search_call.in_progress"` - The breakpoint mode. Always `explicit`. + The type of the event. Always `response.web_search_call.in_progress`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `agent: optional object { agent_name }` - A file input to the model. + The agent that owns this multi-agent streaming event. - - `type: "input_file"` + - `agent_name: string` - The type of the input item. Always `input_file`. + The canonical name of the agent that produced this item. - - `detail: optional "auto" or "low" or "high"` + - `beta_response_web_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` - 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`. + Emitted when a web search call is executing. - - `"auto"` + - `item_id: string` - - `"low"` + Unique ID for the output item associated with the web search call. - - `"high"` + - `output_index: number` - - `file_data: optional string` + The index of the output item that the web search call is associated with. - The content of the file to be sent to the model. + - `sequence_number: number` - - `file_id: optional string` + The sequence number of the web search call being processed. - The ID of the file to be sent to the model. + - `type: "response.web_search_call.searching"` - - `file_url: optional string` + The type of the event. Always `response.web_search_call.searching`. - The URL of the file to be sent to the model. + - `agent: optional object { agent_name }` - - `filename: optional string` + The agent that owns this multi-agent streaming event. - The name of the file to be sent to the model. + - `agent_name: string` - - `prompt_cache_breakpoint: optional object { mode }` + The canonical name of the agent that produced this item. - 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. + - `beta_response_image_gen_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `mode: "explicit"` + Emitted when an image generation tool call has completed and the final image is available. - The breakpoint mode. Always `explicit`. + - `item_id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The unique identifier of the image generation item being processed. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `output_index: number` - - `"in_progress"` + The index of the output item in the response's output array. - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number of this event. - - `type: "function_call_output"` + - `type: "response.image_generation_call.completed"` - The type of the function tool call output. Always `function_call_output`. + The type of the event. Always 'response.image_generation_call.completed'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_image_gen_call_generating_event: object { item_id, output_index, sequence_number, 2 more }` - The execution context that produced this tool call. + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `direct: object { type }` + - `item_id: string` - - `program: object { caller_id, type }` + The unique identifier of the image generation item being processed. - - `caller_id: string` + - `output_index: number` - The call ID of the program item that produced this tool call. + The index of the output item in the response's output array. - - `type: "program"` + - `sequence_number: number` - The caller type. Always `program`. + The sequence number of the image generation item being processed. - - `created_by: optional string` + - `type: "response.image_generation_call.generating"` - The identifier of the actor that created the item. + The type of the event. Always 'response.image_generation_call.generating'. - - `agent_message: object { id, author, content, 3 more }` + - `agent: optional object { agent_name }` - - `id: string` + The agent that owns this multi-agent streaming event. - The unique ID of the agent message. + - `agent_name: string` - - `author: string` + The canonical name of the agent that produced this item. - The sending agent identity. + - `beta_response_image_gen_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + Emitted when an image generation tool call is in progress. - Encrypted content sent between agents. + - `item_id: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The unique identifier of the image generation item being processed. - A text input to the model. + - `output_index: number` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + The index of the output item in the response's output array. - A text output from the model. + - `sequence_number: number` - - `text: object { text, type }` + The sequence number of the image generation item being processed. - A text content. + - `type: "response.image_generation_call.in_progress"` - - `text: string` + The type of the event. Always 'response.image_generation_call.in_progress'. - - `type: "text"` + - `agent: optional object { agent_name }` - - `summary_text: object { text, type }` + The agent that owns this multi-agent streaming event. - A summary text from the model. + - `agent_name: string` - - `text: string` + The canonical name of the agent that produced this item. - A summary of the reasoning output from the model so far. + - `beta_response_image_gen_call_partial_image_event: object { item_id, output_index, partial_image_b64, 4 more }` - - `type: "summary_text"` + Emitted when a partial image is available during image generation streaming. - The type of the object. Always `summary_text`. + - `item_id: string` - - `reasoning_text: object { text, type }` + The unique identifier of the image generation item being processed. - Reasoning text from the model. + - `output_index: number` - - `text: string` + The index of the output item in the response's output array. - The reasoning text from the model. + - `partial_image_b64: string` - - `type: "reasoning_text"` + Base64-encoded partial image data, suitable for rendering as an image. - The type of the reasoning text. Always `reasoning_text`. + - `partial_image_index: number` - - `beta_response_output_refusal: object { refusal, type }` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - A refusal from the model. + - `sequence_number: number` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The sequence number of the image generation item being processed. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: "response.image_generation_call.partial_image"` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + The type of the event. Always 'response.image_generation_call.partial_image'. - A screenshot of a computer. + - `agent: optional object { agent_name }` - - `detail: "low" or "high" or "auto" or "original"` + The agent that owns this multi-agent streaming event. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `"high"` + - `beta_response_mcp_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` - - `"auto"` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `"original"` + - `delta: string` - - `file_id: string` + A JSON string containing the partial update to the arguments for the MCP tool call. - The identifier of an uploaded file that contains the screenshot. + - `item_id: string` - - `image_url: string` + The unique identifier of the MCP tool call item being processed. - The URL of the screenshot image. + - `output_index: number` - - `type: "computer_screenshot"` + The index of the output item in the response's output array. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `sequence_number: number` - - `prompt_cache_breakpoint: optional object { mode }` + The sequence number of this event. - 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. + - `type: "response.mcp_call_arguments.delta"` - - `mode: "explicit"` + The type of the event. Always 'response.mcp_call_arguments.delta'. - The breakpoint mode. Always `explicit`. + - `agent: optional object { agent_name }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The agent that owns this multi-agent streaming event. - A file input to the model. + - `agent_name: string` - - `encrypted_content: object { encrypted_content, type }` + The canonical name of the agent that produced this item. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `beta_response_mcp_call_arguments_done_event: object { arguments, item_id, output_index, 3 more }` - - `encrypted_content: string` + Emitted when the arguments for an MCP tool call are finalized. - Opaque encrypted content. + - `arguments: string` - - `type: "encrypted_content"` + A JSON string containing the finalized arguments for the MCP tool call. - The type of the input item. Always `encrypted_content`. + - `item_id: string` - - `recipient: string` + The unique identifier of the MCP tool call item being processed. - The destination agent identity. + - `output_index: number` - - `type: "agent_message"` + The index of the output item in the response's output array. - The type of the item. Always `agent_message`. + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.mcp_call_arguments.done"` + + The type of the event. Always 'response.mcp_call_arguments.done'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `beta_response_mcp_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `id: string` + Emitted when an MCP tool call has completed successfully. - The unique ID of the multi-agent call item. + - `item_id: string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The ID of the MCP tool call item that completed. - The multi-agent action to execute. + - `output_index: number` - - `"spawn_agent"` + The index of the output item that completed. - - `"interrupt_agent"` + - `sequence_number: number` - - `"list_agents"` + The sequence number of this event. - - `"send_message"` + - `type: "response.mcp_call.completed"` - - `"followup_task"` + The type of the event. Always 'response.mcp_call.completed'. - - `"wait_agent"` + - `agent: optional object { agent_name }` - - `arguments: string` + The agent that owns this multi-agent streaming event. - The JSON string of arguments generated for the action. + - `agent_name: string` - - `call_id: string` + The canonical name of the agent that produced this item. - The unique ID linking this call to its output. + - `beta_response_mcp_call_failed_event: object { item_id, output_index, sequence_number, 2 more }` - - `type: "multi_agent_call"` + Emitted when an MCP tool call has failed. - The type of the multi-agent call. Always `multi_agent_call`. + - `item_id: string` + + The ID of the MCP tool call item that failed. + + - `output_index: number` + + The index of the output item that failed. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.mcp_call.failed"` + + The type of the event. Always 'response.mcp_call.failed'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `beta_response_mcp_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `id: string` + Emitted when an MCP tool call is in progress. - The unique ID of the multi-agent call output item. + - `item_id: string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The unique identifier of the MCP tool call item being processed. - The multi-agent action that produced this result. + - `output_index: number` - - `"spawn_agent"` + The index of the output item in the response's output array. - - `"interrupt_agent"` + - `sequence_number: number` - - `"list_agents"` + The sequence number of this event. - - `"send_message"` + - `type: "response.mcp_call.in_progress"` - - `"followup_task"` + The type of the event. Always 'response.mcp_call.in_progress'. - - `"wait_agent"` + - `agent: optional object { agent_name }` - - `call_id: string` + The agent that owns this multi-agent streaming event. - The unique ID of the multi-agent call. + - `agent_name: string` - - `output: array of BetaResponseOutputText` + The canonical name of the agent that produced this item. - Text output returned by the multi-agent action. + - `beta_response_mcp_list_tools_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + Emitted when the list of available MCP tools has been successfully retrieved. - The annotations of the text output. + - `item_id: string` - - `text: string` + The ID of the MCP tool call item that produced this output. - The text output from the model. + - `output_index: number` - - `type: "output_text"` + The index of the output item that was processed. - The type of the output text. Always `output_text`. + - `sequence_number: number` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The sequence number of this event. - - `type: "multi_agent_call_output"` + - `type: "response.mcp_list_tools.completed"` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of the event. Always 'response.mcp_list_tools.completed'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `beta_response_mcp_list_tools_failed_event: object { item_id, output_index, sequence_number, 2 more }` - 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. + Emitted when the attempt to list available MCP tools has failed. - - `id: string` + - `item_id: string` - The unique ID of the web search tool call. + The ID of the MCP tool call item that failed. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `output_index: number` - 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). + The index of the output item that failed. - - `search: object { type, queries, query, sources }` + - `sequence_number: number` - Action type "search" - Performs a web search query. + The sequence number of this event. - - `type: "search"` + - `type: "response.mcp_list_tools.failed"` - The action type. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `queries: optional array of string` + - `agent: optional object { agent_name }` - The search queries. + The agent that owns this multi-agent streaming event. - - `query: optional string` + - `agent_name: string` - The search query. + The canonical name of the agent that produced this item. - - `sources: optional array of object { type, url }` + - `beta_response_mcp_list_tools_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - The sources used in the search. + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `type: "url"` + - `item_id: string` - The type of source. Always `url`. + The ID of the MCP tool call item that is being processed. - - `url: string` + - `output_index: number` - The URL of the source. + The index of the output item that is being processed. - - `open_page: object { type, url }` + - `sequence_number: number` - Action type "open_page" - Opens a specific URL from search results. + The sequence number of this event. - - `type: "open_page"` + - `type: "response.mcp_list_tools.in_progress"` - The action type. + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `url: optional string` + - `agent: optional object { agent_name }` - The URL opened by the model. + The agent that owns this multi-agent streaming event. - - `find_in_page: object { pattern, type, url }` + - `agent_name: string` - Action type "find_in_page": Searches for a pattern within a loaded page. + The canonical name of the agent that produced this item. - - `pattern: string` + - `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` - The pattern or text to search for within the page. + Emitted when an annotation is added to output text content. - - `type: "find_in_page"` + - `annotation: unknown` - The action type. + The annotation object being added. (See annotation schema for details.) - - `url: string` + - `annotation_index: number` - The URL of the page searched for the pattern. + The index of the annotation within the content part. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `content_index: number` - The status of the web search tool call. + The index of the content part within the output item. - - `"in_progress"` + - `item_id: string` - - `"searching"` + The unique identifier of the item to which the annotation is being added. - - `"completed"` + - `output_index: number` - - `"failed"` + The index of the output item in the response's output array. - - `type: "web_search_call"` + - `sequence_number: number` - The type of the web search tool call. Always `web_search_call`. + The sequence number of this event. + + - `type: "response.output_text.annotation.added"` + + The type of the event. Always 'response.output_text.annotation.added'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - A tool call to a computer use tool. See the - [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - - `id: string` + - `beta_response_queued_event: object { response, sequence_number, type, agent }` - The unique ID of the computer call. + Emitted when a response is queued and waiting to be processed. - - `call_id: string` + - `response: object { id, created_at, error, 31 more }` - An identifier used when responding to the tool call with output. + The full response object that is queued. - - `pending_safety_checks: array of object { id, code, message }` + - `id: string` - The pending safety checks for the computer call. + Unique identifier for this Response. - - `id: string` + - `created_at: number` - The ID of the pending safety check. + Unix timestamp (in seconds) of when this Response was created. - - `code: optional string` + - `error: object { code, message }` - The type of the pending safety check. + An error object returned when the model fails to generate a Response. - - `message: optional string` + - `incomplete_details: object { reason }` - Details about the pending safety check. + Details about why the response is incomplete. - - `status: "in_progress" or "completed" or "incomplete"` + - `instructions: string or array of BetaResponseInputItem` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A system (or developer) message inserted into the model's context. - - `"in_progress"` + When using 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. - - `"completed"` + - `metadata: map[string]` - - `"incomplete"` + 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. - - `type: "computer_call"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the computer call. Always `computer_call`. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `"computer_call"` + Model ID used to generate the response, like `gpt-4o` 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. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `object: "response"` - A click action. + The object type of this resource - always set to `response`. - - `click: object { button, type, x, 2 more }` + - `output: array of BetaResponseOutputItem` - A click action. + An array of content items generated by the model. - - `button: "left" or "right" or "wheel" or 2 more` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `parallel_tool_calls: boolean` - - `"left"` + Whether to allow the model to run tool calls in parallel. - - `"right"` + - `temperature: number` - - `"wheel"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `"back"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `"forward"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `type: "click"` + - `tools: array of BetaTool` - Specifies the event type. For a click action, this property is always `click`. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `x: number` + We support the following categories of tools: - The x-coordinate where the click occurred. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `y: number` + - `top_p: number` - The y-coordinate where the click occurred. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `keys: optional array of string` + We generally recommend altering this or `temperature` but not both. - The keys being held while clicking. + - `background: optional boolean` - - `double_click: object { keys, type, x, y }` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - A double click action. + - `completed_at: optional number` - - `keys: array of string` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The keys being held while double-clicking. + - `conversation: optional object { id }` - - `type: "double_click"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `max_output_tokens: optional number` - - `x: number` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The x-coordinate where the double click occurred. + - `max_tool_calls: optional number` - - `y: number` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The y-coordinate where the double click occurred. + - `moderation: optional object { input, output }` - - `drag: object { path, type, keys }` + Moderation results for the response input and output, if moderated completions were requested. - A drag action. + - `previous_response_id: optional string` - - `path: array of object { x, y }` + 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`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `prompt: optional object { id, variables, version }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `x: number` + - `prompt_cache_key: optional string` - The x-coordinate. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `y: number` + - `prompt_cache_options: optional object { mode, ttl }` - The y-coordinate. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `type: "drag"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - Specifies the event type. For a drag action, this property is always set to `drag`. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `keys: optional array of string` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - The keys being held while dragging the mouse. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `keypress: object { keys, type }` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - A collection of keypresses the model would like to perform. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `keys: array of string` + **gpt-5 and o-series models only** - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `type: "keypress"` + - `safety_identifier: optional string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `move: object { type, x, y, keys }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - A mouse move action. + Specifies the processing type used for serving the request. - - `type: "move"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - Specifies the event type. For a move action, this property is always set to `move`. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `x: number` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - The x-coordinate to move to. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `y: number` + - `text: optional object { format, verbosity }` - The y-coordinate to move to. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `keys: optional array of string` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The keys being held while moving the mouse. + - `top_logprobs: optional number` - - `screenshot: object { type }` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - A screenshot action. + - `truncation: optional "auto" or "disabled"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + The truncation strategy to use for the model response. - A scroll action. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `scroll_x: number` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - The horizontal scroll distance. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `scroll_y: number` + - `user: optional string` - The vertical scroll distance. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: "scroll"` + - `sequence_number: number` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The sequence number for this event. - - `x: number` + - `type: "response.queued"` - The x-coordinate where the scroll occurred. + The type of the event. Always 'response.queued'. - - `y: number` + - `agent: optional object { agent_name }` - The y-coordinate where the scroll occurred. + The agent that owns this multi-agent streaming event. - - `keys: optional array of string` + - `agent_name: string` - The keys being held while scrolling. + The canonical name of the agent that produced this item. - - `type: object { text, type }` + - `beta_response_custom_tool_call_input_delta_event: object { delta, item_id, output_index, 3 more }` - An action to type in text. + Event representing a delta (partial update) to the input of a custom tool call. - - `text: string` + - `delta: string` - The text to type. + The incremental input data (delta) for the custom tool call. - - `type: "type"` + - `item_id: string` - Specifies the event type. For a type action, this property is always set to `type`. + Unique identifier for the API item associated with this event. - - `wait: object { type }` + - `output_index: number` - A wait action. + The index of the output this delta applies to. - - `actions: optional array of BetaComputerAction` + - `sequence_number: number` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The sequence number of this event. - - `click: object { button, type, x, 2 more }` + - `type: "response.custom_tool_call_input.delta"` - A click action. + The event type identifier. - - `double_click: object { keys, type, x, y }` + - `agent: optional object { agent_name }` - A double click action. + The agent that owns this multi-agent streaming event. - - `drag: object { path, type, keys }` + - `agent_name: string` - A drag action. + The canonical name of the agent that produced this item. - - `keypress: object { keys, type }` + - `beta_response_custom_tool_call_input_done_event: object { input, item_id, output_index, 3 more }` - A collection of keypresses the model would like to perform. + Event indicating that input for a custom tool call is complete. - - `move: object { type, x, y, keys }` + - `input: string` - A mouse move action. + The complete input data for the custom tool call. - - `screenshot: object { type }` + - `item_id: string` - A screenshot action. + Unique identifier for the API item associated with this event. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `output_index: number` - A scroll action. + The index of the output this event applies to. - - `type: object { text, type }` + - `sequence_number: number` - An action to type in text. + The sequence number of this event. - - `wait: object { type }` + - `type: "response.custom_tool_call_input.done"` - A wait action. + The event type identifier. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - - `id: string` - - The unique ID of the computer call tool output. - - - `call_id: string` +### Beta Response Text Config - The ID of the computer tool call that produced the output. +- `beta_response_text_config: object { format, verbosity }` - - `output: object { type, file_id, image_url }` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - A computer screenshot image used with the computer use tool. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `type: "computer_screenshot"` + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + An object specifying the format that the model must output. - - `file_id: optional string` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The identifier of an uploaded file that contains the screenshot. + The default format is `{ "type": "text" }` with no additional options. - - `image_url: optional string` + **Not recommended for gpt-4o and newer models:** - The URL of the screenshot image. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `text: object { type }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Default response format. Used to generate text responses. - - `"completed"` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - - `"incomplete"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"failed"` + - `name: string` - - `"in_progress"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `type: "computer_call_output"` + - `schema: map[unknown]` - The type of the computer tool call output. Always `computer_call_output`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "json_schema"` - The safety checks reported by the API that have been acknowledged by the - developer. + The type of response format being defined. Always `json_schema`. - - `id: string` + - `description: optional string` - The ID of the pending safety check. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `code: optional string` + - `strict: optional boolean` - The type of the pending safety check. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `message: optional string` + - `json_object: object { type }` - Details about the pending safety check. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `agent: optional object { agent_name }` + - `verbosity: optional "low" or "medium" or "high"` - The agent that produced this item. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `created_by: optional string` + - `"high"` - The identifier of the actor that created the item. +### Beta Response Text Delta Event - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` +- `beta_response_text_delta_event: object { content_index, delta, item_id, 5 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + Emitted when there is an additional text delta. - - `id: string` + - `content_index: number` - The unique identifier of the reasoning content. + The index of the content part that the text delta was added to. - - `summary: array of object { text, type }` + - `delta: string` - Reasoning summary content. + The text delta that was added. - - `text: string` + - `item_id: string` - A summary of the reasoning output from the model so far. + The ID of the output item that the text delta was added to. - - `type: "summary_text"` + - `logprobs: array of object { token, logprob, top_logprobs }` - The type of the object. Always `summary_text`. + The log probabilities of the tokens in the delta. - - `type: "reasoning"` + - `token: string` - The type of the object. Always `reasoning`. + A possible text token. - - `agent: optional object { agent_name }` + - `logprob: number` - The agent that produced this item. + The log probability of this token. - - `agent_name: string` + - `top_logprobs: optional array of object { token, logprob }` - The canonical name of the agent that produced this item. + The log probabilities of up to 20 of the most likely tokens. - - `content: optional array of object { text, type }` + - `token: optional string` - Reasoning text content. + A possible text token. - - `text: string` + - `logprob: optional number` - The reasoning text from the model. + The log probability of this token. - - `type: "reasoning_text"` + - `output_index: number` - The type of the reasoning text. Always `reasoning_text`. + The index of the output item that the text delta was added to. - - `encrypted_content: optional string` + - `sequence_number: number` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The sequence number for this event. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "response.output_text.delta"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the event. Always `response.output_text.delta`. - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that owns this multi-agent streaming event. - - `"incomplete"` + - `agent_name: string` - - `program: object { id, call_id, code, 3 more }` + The canonical name of the agent that produced this item. - - `id: string` +### Beta Response Text Done Event - The unique ID of the program item. +- `beta_response_text_done_event: object { content_index, item_id, logprobs, 5 more }` - - `call_id: string` + Emitted when text content is finalized. - The stable call ID of the program item. + - `content_index: number` - - `code: string` + The index of the content part that the text content is finalized. - The JavaScript source executed by programmatic tool calling. + - `item_id: string` - - `fingerprint: string` + The ID of the output item that the text content is finalized. - Opaque program replay fingerprint that must be round-tripped. + - `logprobs: array of object { token, logprob, top_logprobs }` - - `type: "program"` + The log probabilities of the tokens in the delta. - The type of the item. Always `program`. + - `token: string` - - `agent: optional object { agent_name }` + A possible text token. - The agent that produced this item. + - `logprob: number` - - `agent_name: string` + The log probability of this token. - The canonical name of the agent that produced this item. + - `top_logprobs: optional array of object { token, logprob }` - - `program_output: object { id, call_id, result, 3 more }` + The log probabilities of up to 20 of the most likely tokens. - - `id: string` + - `token: optional string` - The unique ID of the program output item. + A possible text token. - - `call_id: string` + - `logprob: optional number` - The call ID of the program item. + The log probability of this token. - - `result: string` + - `output_index: number` - The result produced by the program item. + The index of the output item that the text content is finalized. - - `status: "completed" or "incomplete"` + - `sequence_number: number` - The terminal status of the program output item. + The sequence number for this event. - - `"completed"` + - `text: string` - - `"incomplete"` + The text content that is finalized. - - `type: "program_output"` + - `type: "response.output_text.done"` - The type of the item. Always `program_output`. + The type of the event. Always `response.output_text.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` +### Beta Response Tool Search Call + +- `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - `id: string` @@ -103251,7 +115169,9 @@ openai beta:responses compact \ The identifier of the actor that created the item. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` +### Beta Response Tool Search Output Item + +- `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - `id: string` @@ -103376,7 +115296,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -103386,7 +115306,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -103433,7 +115357,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -103443,7 +115367,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -104329,1513 +116257,1320 @@ openai beta:responses compact \ The identifier of the actor that created the item. - - `additional_tools: object { id, role, tools, 2 more }` - - - `id: string` - - The unique ID of the additional tools item. - - - `role: "unknown" or "user" or "assistant" or 5 more` - - The role that provided the additional tools. - - - `"unknown"` - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"critic"` - - - `"discriminator"` - - - `"developer"` +### Beta Response Tool Search Output Item Param - - `"tool"` +- `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - `tools: array of BetaTool` - The additional tool definitions made available at this item. + The loaded tool definitions returned by the tool search output. - `beta_function_tool: object { name, parameters, strict, 5 more }` 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). - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - 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). - - - `beta_computer_tool: object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - 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: object { server_label, type, allowed_callers, 9 more }` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - - `code_interpreter: object { container, type, allowed_callers }` - - A tool that runs Python code to help generate a response to a prompt. - - - `programmatic_tool_calling: object { type }` - - - `image_generation: object { type, action, background, 9 more }` - - A tool that generates images using the GPT image models. - - - `local_shell: object { type }` - - A tool that allows the model to execute shell commands in a local environment. - - - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - A tool that allows the model to execute shell commands. - - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - 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) - - - `beta_namespace_tool: object { description, name, tools, type }` - - Groups function/custom tools under a shared namespace. - - - `beta_tool_search_tool: object { type, description, execution, parameters }` - - Hosted or BYOT tool search configuration for deferred tools. - - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `beta_apply_patch_tool: object { type, allowed_callers }` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: "additional_tools"` - - The type of the item. Always `additional_tools`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - - `id: string` - - The unique ID of the compaction item. - - - `encrypted_content: string` - - The encrypted content that was produced by compaction. - - - `type: "compaction"` - - The type of the item. Always `compaction`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `image_generation_call: object { id, result, status, 2 more }` - - An image generation request made by the model. - - - `id: string` - - The unique ID of the image generation call. - - - `result: string` - - The generated image encoded in base64. - - - `status: "in_progress" or "completed" or "generating" or "failed"` - - The status of the image generation call. - - - `"in_progress"` - - - `"completed"` - - - `"generating"` - - - `"failed"` - - - `type: "image_generation_call"` - - The type of the image generation call. Always `image_generation_call`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - A tool call to run code. - - - `id: string` - - The unique ID of the code interpreter tool call. - - - `code: string` - - The code to run, or null if not available. - - - `container_id: string` - - The ID of the container used to run the code. - - - `outputs: array of object { logs, type } or object { type, url }` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `logs: object { logs, type }` - - The logs output from the code interpreter. - - - `logs: string` - - The logs output from the code interpreter. - - - `type: "logs"` - - The type of the output. Always `logs`. - - - `image: object { type, url }` - - The image output from the code interpreter. - - - `type: "image"` - - The type of the output. Always `image`. - - - `url: string` - - The URL of the image output from the code interpreter. - - - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"interpreting"` - - - `"failed"` - - - `type: "code_interpreter_call"` - - The type of the code interpreter tool call. Always `code_interpreter_call`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `local_shell_call: object { id, action, call_id, 3 more }` - - A tool call to run a command on the local shell. - - - `id: string` - - The unique ID of the local shell call. - - - `action: object { command, env, type, 3 more }` - - Execute a shell command on the server. - - - `command: array of string` - - The command to run. - - - `env: map[string]` - - Environment variables to set for the command. - - - `type: "exec"` - - The type of the local shell action. Always `exec`. - - - `timeout_ms: optional number` + - `name: string` - Optional timeout in milliseconds for the command. + The name of the function to call. - - `user: optional string` + - `parameters: map[unknown]` - Optional user to run the command as. + A JSON schema object describing the parameters of the function. - - `working_directory: optional string` + - `strict: boolean` - Optional working directory to run the command in. + Whether strict parameter validation is enforced for this function tool. - - `call_id: string` + - `type: "function"` - The unique ID of the local shell tool call generated by the model. + The type of the function tool. Always `function`. - - `status: "in_progress" or "completed" or "incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The status of the local shell call. + The tool invocation context(s). - - `"in_progress"` + - `"direct"` - - `"completed"` + - `"programmatic"` - - `"incomplete"` + - `defer_loading: optional boolean` - - `type: "local_shell_call"` + Whether this function is deferred and loaded via tool search. - The type of the local shell call. Always `local_shell_call`. + - `description: optional string` - - `agent: optional object { agent_name }` + A description of the function. Used by the model to determine whether or not to call the function. - The agent that produced this item. + - `output_schema: optional map[unknown]` - - `agent_name: string` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The canonical name of the agent that produced this item. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `local_shell_call_output: object { id, output, type, 2 more }` + 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). - The output of a local shell tool call. + - `type: "file_search"` - - `id: string` + The type of the file search tool. Always `file_search`. - The unique ID of the local shell tool call generated by the model. + - `vector_store_ids: array of string` - - `output: string` + The IDs of the vector stores to search. - A JSON string of the output of the local shell tool call. + - `filters: optional object { key, type, value } or object { filters, type }` - - `type: "local_shell_call_output"` + A filter to apply. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `Comparison Filter: object { key, type, value }` - - `agent: optional object { agent_name }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The agent that produced this item. + - `key: string` - - `agent_name: string` + The key to compare against the value. - The canonical name of the agent that produced this item. + - `type: "eq" or "ne" or "gt" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `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 - - `"in_progress"` + - `"eq"` - - `"completed"` + - `"ne"` - - `"incomplete"` + - `"gt"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `"gte"` - A tool call that executes one or more shell commands in a managed environment. + - `"lt"` - - `id: string` + - `"lte"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"in"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"nin"` - The shell commands and limits that describe how to run the tool call. + - `value: string or number or boolean or array of string or number` - - `commands: array of string` + The value to compare against the attribute key; supports string, number, or boolean types. - - `max_output_length: number` + - `union_member_0: string` - Optional maximum number of characters to return from each command. + - `union_member_1: number` - - `timeout_ms: number` + - `union_member_2: boolean` - Optional timeout in milliseconds for the commands. + - `union_member_3: array of string or number` - - `call_id: string` + - `union_member_0: string` - The unique ID of the shell tool call generated by the model. + - `union_member_1: number` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `Compound Filter: object { filters, type }` - Represents the use of a local environment to perform shell actions. + Combine multiple filters using `and` or `or`. - - `beta_response_local_environment: object { type }` + - `filters: array of object { key, type, value } or unknown` - Represents the use of a local environment to perform shell actions. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: "local"` + - `Comparison Filter: object { key, type, value }` - The environment type. Always `local`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `beta_response_container_reference: object { container_id, type }` + - `key: string` - Represents a container created with /v1/containers. + The key to compare against the value. - - `container_id: string` + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "container_reference"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The environment type. Always `container_reference`. + - `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 - - `status: "in_progress" or "completed" or "incomplete"` + - `"eq"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"ne"` - - `"in_progress"` + - `"gt"` - - `"completed"` + - `"gte"` - - `"incomplete"` + - `"lt"` - - `type: "shell_call"` + - `"lte"` - The type of the item. Always `shell_call`. + - `"in"` - - `agent: optional object { agent_name }` + - `"nin"` - The agent that produced this item. + - `value: string or number or boolean or array of string or number` - - `agent_name: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The canonical name of the agent that produced this item. + - `union_member_0: string` - - `caller: optional object { type } or object { caller_id, type }` + - `union_member_1: number` - The execution context that produced this tool call. + - `union_member_2: boolean` - - `direct: object { type }` + - `union_member_3: array of string or number` - - `program: object { caller_id, type }` + - `union_member_0: string` - - `caller_id: string` + - `union_member_1: number` - The call ID of the program item that produced this tool call. + - `union_member_1: unknown` - - `type: "program"` + - `type: "and" or "or"` - - `created_by: optional string` + Type of operation: `and` or `or`. - The ID of the entity that created this tool call. + - `"and"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `"or"` - The output of a shell tool call that was emitted. + - `max_num_results: optional number` - - `id: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The unique ID of the shell call output. Populated when this item is returned via API. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `call_id: string` + Ranking options for search. - The unique ID of the shell tool call generated by the model. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `max_output_length: number` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `embedding_weight: number` - - `output: array of object { outcome, stderr, stdout, created_by }` + The weight of the embedding in the reciprocal ranking fusion. - An array of shell call output contents + - `text_weight: number` - - `outcome: object { type } or object { exit_code, type }` + The weight of the text in the reciprocal ranking fusion. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `ranker: optional "auto" or "default-2024-11-15"` - - `timeout: object { type }` + The ranker to use for the file search. - Indicates that the shell call exceeded its configured time limit. + - `"auto"` - - `exit: object { exit_code, type }` + - `"default-2024-11-15"` - Indicates that the shell commands finished and returned an exit code. + - `score_threshold: optional number` - - `exit_code: number` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Exit code from the shell process. + - `beta_computer_tool: object { type }` - - `type: "exit"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The outcome type. Always `exit`. + - `type: "computer"` - - `stderr: string` + The type of the computer tool. Always `computer`. - The standard error output that was captured. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `stdout: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The standard output that was captured. + - `display_height: number` - - `created_by: optional string` + The height of the computer display. - The identifier of the actor that created the item. + - `display_width: number` - - `status: "in_progress" or "completed" or "incomplete"` + The width of the computer display. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"in_progress"` + The type of computer environment to control. - - `"completed"` + - `"windows"` - - `"incomplete"` + - `"mac"` - - `type: "shell_call_output"` + - `"linux"` - The type of the shell call output. Always `shell_call_output`. + - `"ubuntu"` - - `agent: optional object { agent_name }` + - `"browser"` - The agent that produced this item. + - `type: "computer_use_preview"` - - `agent_name: string` + The type of the computer use tool. Always `computer_use_preview`. - The canonical name of the agent that produced this item. + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `caller: optional object { type } or object { caller_id, type }` + 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). - The execution context that produced this tool call. + - `type: "web_search" or "web_search_2025_08_26"` - - `direct: object { type }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `program: object { caller_id, type }` + - `"web_search"` - - `caller_id: string` + - `"web_search_2025_08_26"` - The call ID of the program item that produced this tool call. + - `filters: optional object { allowed_domains }` - - `type: "program"` + Filters for the search. - - `created_by: optional string` + - `allowed_domains: optional array of string` - The identifier of the actor that created the item. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - A tool call that applies file diffs by creating, deleting, or updating files. + - `search_context_size: optional "low" or "medium" or "high"` - - `id: string` + 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. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"low"` - - `call_id: string` + - `"medium"` - The unique ID of the apply patch tool call generated by the model. + - `"high"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `user_location: optional object { city, country, region, 2 more }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The approximate location of the user. - - `create_file: object { diff, path, type }` + - `city: optional string` - Instruction describing how to create a file via the apply_patch tool. + Free text input for the city of the user, e.g. `San Francisco`. - - `diff: string` + - `country: optional string` - Diff to apply. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `path: string` + - `region: optional string` - Path of the file to create. + Free text input for the region of the user, e.g. `California`. - - `type: "create_file"` + - `timezone: optional string` - Create a new file with the provided diff. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `delete_file: object { path, type }` + - `type: optional "approximate"` - Instruction describing how to delete a file via the apply_patch tool. + The type of location approximation. Always `approximate`. - - `path: string` + - `"approximate"` - Path of the file to delete. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `type: "delete_file"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - Delete the specified file. + - `server_label: string` - - `update_file: object { diff, path, type }` + A label for this MCP server, used to identify it in tool calls. - Instruction describing how to update a file via the apply_patch tool. + - `type: "mcp"` - - `diff: string` + The type of the MCP tool. Always `mcp`. - Diff to apply. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `path: string` + The tool invocation context(s). - Path of the file to update. + - `"direct"` - - `type: "update_file"` + - `"programmatic"` - Update an existing file with the provided diff. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `status: "in_progress" or "completed"` + List of allowed tool names or a filter object. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `MCP allowed tools: array of string` - - `"in_progress"` + A string array of allowed tool names - - `"completed"` + - `MCP tool filter: object { read_only, tool_names }` - - `type: "apply_patch_call"` + A filter object to specify which tools are allowed. - The type of the item. Always `apply_patch_call`. + - `read_only: optional boolean` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + - `tool_names: optional array of string` - - `agent_name: string` + List of allowed tool names. - The canonical name of the agent that produced this item. + - `authorization: optional string` - - `caller: optional object { type } or object { caller_id, type }` + 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. - The execution context that produced this tool call. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `direct: object { type }` + 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). - - `program: object { caller_id, type }` + Currently supported `connector_id` values are: - - `caller_id: string` + - 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` - The call ID of the program item that produced this tool call. + - `"connector_dropbox"` - - `type: "program"` + - `"connector_gmail"` - - `created_by: optional string` + - `"connector_googlecalendar"` - The ID of the entity that created this tool call. + - `"connector_googledrive"` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `"connector_microsoftteams"` - The output emitted by an apply patch tool call. + - `"connector_outlookcalendar"` - - `id: string` + - `"connector_outlookemail"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"connector_sharepoint"` - - `call_id: string` + - `defer_loading: optional boolean` - The unique ID of the apply patch tool call generated by the model. + Whether this MCP tool is deferred and discovered via tool search. - - `status: "completed" or "failed"` + - `headers: optional map[string]` - The status of the apply patch tool call output. One of `completed` or `failed`. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"completed"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"failed"` + Specify which of the MCP server's tools require approval. - - `type: "apply_patch_call_output"` + - `MCP tool approval filter: object { always, never }` - The type of the item. Always `apply_patch_call_output`. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `agent: optional object { agent_name }` + - `always: optional object { read_only, tool_names }` - The agent that produced this item. + A filter object to specify which tools are allowed. - - `agent_name: string` + - `read_only: optional boolean` - The canonical name of the agent that produced this item. + 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. - - `caller: optional object { type } or object { caller_id, type }` + - `tool_names: optional array of string` - The execution context that produced this tool call. + List of allowed tool names. - - `direct: object { type }` + - `never: optional object { read_only, tool_names }` - - `program: object { caller_id, type }` + A filter object to specify which tools are allowed. - - `caller_id: string` + - `read_only: optional boolean` - The call ID of the program item that produced this tool call. + 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. - - `type: "program"` + - `tool_names: optional array of string` - - `created_by: optional string` + List of allowed tool names. - The ID of the entity that created this tool call output. + - `MCP tool approval setting: "always" or "never"` - - `output: optional string` + 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. - Optional textual output returned by the apply patch tool. + - `"always"` - - `mcp_call: object { id, arguments, name, 7 more }` + - `"never"` - An invocation of a tool on an MCP server. + - `server_description: optional string` - - `id: string` + Optional description of the MCP server, used to provide more context. - The unique ID of the tool call. + - `server_url: optional string` - - `arguments: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - A JSON string of the arguments passed to the tool. + - `tunnel_id: optional string` - - `name: string` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The name of the tool that was run. + - `code_interpreter: object { container, type, allowed_callers }` - - `server_label: string` + A tool that runs Python code to help generate a response to a prompt. - The label of the MCP server running the tool. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "mcp_call"` + 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. - The type of the item. Always `mcp_call`. + - `union_member_0: string` - - `agent: optional object { agent_name }` + The container ID. - The agent that produced this item. + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - - `agent_name: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The canonical name of the agent that produced this item. + - `type: "auto"` - - `approval_request_id: optional string` + Always `auto`. - 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. + - `file_ids: optional array of string` - - `error: optional string` + An optional list of uploaded files to make available to your code. - The error from the tool call, if any. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `output: optional string` + The memory limit for the code interpreter container. - The output from the tool call. + - `"1g"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"4g"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"16g"` - - `"in_progress"` + - `"64g"` - - `"completed"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"incomplete"` + Network access policy for the container. - - `"calling"` + - `beta_container_network_policy_disabled: object { type }` - - `"failed"` + - `type: "disabled"` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + Disable outbound network access. Always `disabled`. - A list of tools available on an MCP server. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `id: string` + - `allowed_domains: array of string` - The unique ID of the list. + A list of allowed domains when type is `allowlist`. - - `server_label: string` + - `type: "allowlist"` - The label of the MCP server. + Allow outbound network access only to specified domains. Always `allowlist`. - - `tools: array of object { input_schema, name, annotations, description }` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The tools available on the server. + Optional domain-scoped secrets for allowlisted domains. - - `input_schema: unknown` + - `domain: string` - The JSON schema describing the tool's input. + The domain associated with the secret. - `name: string` - The name of the tool. + The name of the secret to inject for the domain. - - `annotations: optional unknown` + - `value: string` - Additional annotations about the tool. + The secret value to inject for the domain. - - `description: optional string` + - `type: "code_interpreter"` - The description of the tool. + The type of the code interpreter tool. Always `code_interpreter`. - - `type: "mcp_list_tools"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the item. Always `mcp_list_tools`. + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: string` + - `programmatic_tool_calling: object { type }` - The canonical name of the agent that produced this item. + - `image_generation: object { type, action, background, 9 more }` - - `error: optional string` + A tool that generates images using the GPT image models. - Error message if the server could not list tools. + - `type: "image_generation"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The type of the image generation tool. Always `image_generation`. - A request for human approval of a tool invocation. + - `action: optional "generate" or "edit" or "auto"` - - `id: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The unique ID of the approval request. + - `"generate"` - - `arguments: string` + - `"edit"` - A JSON string of arguments for the tool. + - `"auto"` - - `name: string` + - `background: optional "transparent" or "opaque" or "auto"` - The name of the tool to run. + 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. - - `server_label: string` + `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. - The label of the MCP server making the request. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `type: "mcp_approval_request"` + - `"transparent"` - The type of the item. Always `mcp_approval_request`. + - `"opaque"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `input_fidelity: optional "high" or "low"` - - `agent_name: string` + 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`. - The canonical name of the agent that produced this item. + - `"high"` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `"low"` - A response to an MCP approval request. + - `input_image_mask: optional object { file_id, image_url }` - - `id: string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The unique ID of the approval response + - `file_id: optional string` - - `approval_request_id: string` + File ID for the mask image. - The ID of the approval request being answered. + - `image_url: optional string` - - `approve: boolean` + Base64-encoded mask image. - Whether the request was approved. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `type: "mcp_approval_response"` + The image generation model to use. Default: `gpt-image-1`. - The type of the item. Always `mcp_approval_response`. + - `"gpt-image-1"` - - `agent: optional object { agent_name }` + - `"gpt-image-1-mini"` - The agent that produced this item. + - `"gpt-image-2"` - - `agent_name: string` + - `"gpt-image-2-2026-04-21"` - The canonical name of the agent that produced this item. + - `"gpt-image-1.5"` - - `reason: optional string` + - `"chatgpt-image-latest"` - Optional reason for the decision. + - `moderation: optional "auto" or "low"` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + Moderation level for the generated image. Default: `auto`. - A call to a custom tool created by the model. + - `"auto"` - - `call_id: string` + - `"low"` - An identifier used to map this custom tool call to a tool call output. + - `output_compression: optional number` - - `input: string` + Compression level for the output image. Default: 100. - The input for the custom tool call generated by the model. + - `output_format: optional "png" or "webp" or "jpeg"` - - `name: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The name of the custom tool being called. + - `"png"` - - `type: "custom_tool_call"` + - `"webp"` - The type of the custom tool call. Always `custom_tool_call`. + - `"jpeg"` - - `id: optional string` + - `partial_images: optional number` - The unique ID of the custom tool call in the OpenAI platform. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `agent: optional object { agent_name }` + - `quality: optional "low" or "medium" or "high" or "auto"` - The agent that produced this item. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `caller: optional object { type } or object { caller_id, type }` + - `"high"` - The execution context that produced this tool call. + - `"auto"` - - `direct: object { type }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `program: object { caller_id, type }` + 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`. - - `caller_id: string` + - `"1024x1024"` - The call ID of the program item that produced this tool call. + - `"1024x1536"` - - `type: "program"` + - `"1536x1024"` - - `namespace: optional string` + - `"auto"` - The namespace of the custom tool being called. + - `local_shell: object { type }` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + A tool that allows the model to execute shell commands in a local environment. - The output of a custom tool call from your code, being sent back to the model. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `id: string` + A tool that allows the model to execute shell commands. - The unique ID of the custom tool call output item. + - `type: "shell"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the shell tool. Always `shell`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `created_by: optional string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The identifier of the actor that created the item. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `output_index: number` + - `type: "container_auto"` - The index of the output item that was marked done. + Automatically creates a container for this request - - `sequence_number: number` + - `file_ids: optional array of string` - The sequence number of this event. + An optional list of uploaded files to make available to your code. - - `type: "response.output_item.done"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The type of the event. Always `response.output_item.done`. + The memory limit for the container. - - `agent: optional object { agent_name }` + - `"1g"` - The agent that owns this multi-agent streaming event. + - `"4g"` - - `agent_name: string` + - `"16g"` - The canonical name of the agent that produced this item. + - `"64g"` -### Beta Response Output Message + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` -- `beta_response_output_message: object { id, content, role, 4 more }` + Network access policy for the container. - An output message from the model. + - `beta_container_network_policy_disabled: object { type }` - - `id: string` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - The unique ID of the output message. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + An optional list of skills referenced by id or inline data. - The content of the output message. + - `beta_skill_reference: object { skill_id, type, version }` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `skill_id: string` - A text output from the model. + The ID of the referenced skill. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `type: "skill_reference"` - The annotations of the text output. + References a skill created with the /v1/skills endpoint. - - `file_citation: object { file_id, filename, index, type }` + - `version: optional string` - A citation to a file. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `file_id: string` + - `beta_inline_skill: object { description, name, source, type }` - The ID of the file. + - `description: string` - - `filename: string` + The description of the skill. - The filename of the file cited. + - `name: string` - - `index: number` + The name of the skill. - The index of the file in the list of files. + - `source: object { data, media_type, type }` - - `type: "file_citation"` + Inline skill payload - The type of the file citation. Always `file_citation`. + - `data: string` - - `url_citation: object { end_index, start_index, title, 2 more }` + Base64-encoded skill zip bundle. - A citation for a web resource used to generate a model response. + - `media_type: "application/zip"` - - `end_index: number` + The media type of the inline skill payload. Must be `application/zip`. - The index of the last character of the URL citation in the message. + - `type: "base64"` - - `start_index: number` + The type of the inline skill source. Must be `base64`. - The index of the first character of the URL citation in the message. + - `type: "inline"` - - `title: string` + Defines an inline skill for this request. - The title of the web resource. + - `beta_local_environment: object { type, skills }` - - `type: "url_citation"` + - `type: "local"` - The type of the URL citation. Always `url_citation`. + Use a local computer environment. - - `url: string` + - `skills: optional array of BetaLocalSkill` - The URL of the web resource. + An optional list of skills. - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `description: string` - A citation for a container file used to generate a model response. + The description of the skill. - - `container_id: string` + - `name: string` - The ID of the container file. + The name of the skill. - - `end_index: number` + - `path: string` - The index of the last character of the container file citation in the message. + The path to the directory containing the skill. - - `file_id: string` + - `beta_container_reference: object { container_id, type }` - The ID of the file. + - `container_id: string` - - `filename: string` + The ID of the referenced container. - The filename of the container file cited. + - `type: "container_reference"` - - `start_index: number` + References a container created with the /v1/containers endpoint - The index of the first character of the container file citation in the message. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `type: "container_file_citation"` + 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) - The type of the container file citation. Always `container_file_citation`. + - `name: string` - - `file_path: object { file_id, index, type }` + The name of the custom tool, used to identify it in tool calls. - A path to a file. + - `type: "custom"` - - `file_id: string` + The type of the custom tool. Always `custom`. - The ID of the file. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `index: number` + The tool invocation context(s). - The index of the file in the list of files. + - `"direct"` - - `type: "file_path"` + - `"programmatic"` - The type of the file path. Always `file_path`. + - `defer_loading: optional boolean` - - `text: string` + Whether this tool should be deferred and discovered via tool search. - The text output from the model. + - `description: optional string` - - `type: "output_text"` + Optional description of the custom tool, used to provide more context. - The type of the output text. Always `output_text`. + - `format: optional object { type } or object { definition, syntax, type }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The input format for the custom tool. Default is unconstrained text. - - `token: string` + - `text: object { type }` - - `bytes: array of number` + Unconstrained free-form text. - - `logprob: number` + - `grammar: object { definition, syntax, type }` - - `top_logprobs: array of object { token, bytes, logprob }` + A grammar defined by the user. - - `token: string` + - `definition: string` - - `bytes: array of number` + The grammar definition. - - `logprob: number` + - `syntax: "lark" or "regex"` - - `beta_response_output_refusal: object { refusal, type }` + The syntax of the grammar definition. One of `lark` or `regex`. - A refusal from the model. + - `"lark"` - - `refusal: string` + - `"regex"` - The refusal explanation from the model. + - `type: "grammar"` - - `type: "refusal"` + Grammar format. Always `grammar`. - The type of the refusal. Always `refusal`. + - `beta_namespace_tool: object { description, name, tools, type }` - - `role: "assistant"` + Groups function/custom tools under a shared namespace. - The role of the output message. Always `assistant`. + - `description: string` - - `status: "in_progress" or "completed" or "incomplete"` + A description of the namespace shown to the model. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `name: string` - - `"in_progress"` + The namespace name used in tool calls (for example, `crm`). - - `"completed"` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `"incomplete"` + The function/custom tools available inside this namespace. - - `type: "message"` + - `function: object { name, type, allowed_callers, 5 more }` - The type of the output message. Always `message`. + - `name: string` - - `agent: optional object { agent_name }` + - `type: "function"` - The agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent_name: string` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `"direct"` - - `phase: optional "commentary"` + - `"programmatic"` - 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. + - `defer_loading: optional boolean` - - `"commentary"` + Whether this function should be deferred and discovered via tool search. -### Beta Response Output Refusal + - `description: optional string` -- `beta_response_output_refusal: object { refusal, type }` + - `output_schema: optional map[unknown]` - A refusal from the model. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `refusal: string` + - `parameters: optional unknown` - The refusal explanation from the model. + - `strict: optional boolean` - - `type: "refusal"` + 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. - The type of the refusal. Always `refusal`. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` -### Beta Response Output Text + 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) -- `beta_response_output_text: object { annotations, text, type, logprobs }` + - `name: string` - A text output from the model. + The name of the custom tool, used to identify it in tool calls. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `type: "custom"` - The annotations of the text output. + The type of the custom tool. Always `custom`. - - `file_citation: object { file_id, filename, index, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A citation to a file. + The tool invocation context(s). - - `file_id: string` + - `defer_loading: optional boolean` - The ID of the file. + Whether this tool should be deferred and discovered via tool search. - - `filename: string` + - `description: optional string` - The filename of the file cited. + Optional description of the custom tool, used to provide more context. - - `index: number` + - `format: optional object { type } or object { definition, syntax, type }` - The index of the file in the list of files. + The input format for the custom tool. Default is unconstrained text. - - `type: "file_citation"` + - `type: "namespace"` - The type of the file citation. Always `file_citation`. + The type of the tool. Always `namespace`. - - `url_citation: object { end_index, start_index, title, 2 more }` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - A citation for a web resource used to generate a model response. + Hosted or BYOT tool search configuration for deferred tools. - - `end_index: number` + - `type: "tool_search"` - The index of the last character of the URL citation in the message. + The type of the tool. Always `tool_search`. - - `start_index: number` + - `description: optional string` - The index of the first character of the URL citation in the message. + Description shown to the model for a client-executed tool search tool. - - `title: string` + - `execution: optional "server" or "client"` - The title of the web resource. + Whether tool search is executed by the server or by the client. - - `type: "url_citation"` + - `"server"` - The type of the URL citation. Always `url_citation`. + - `"client"` - - `url: string` + - `parameters: optional unknown` - The URL of the web resource. + Parameter schema for a client-executed tool search tool. - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - A citation for a container file used to generate a model response. + 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). - - `container_id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The ID of the container file. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `end_index: number` + - `"web_search_preview"` - The index of the last character of the container file citation in the message. + - `"web_search_preview_2025_03_11"` - - `file_id: string` + - `search_content_types: optional array of "text" or "image"` - The ID of the file. + - `"text"` - - `filename: string` + - `"image"` - The filename of the container file cited. + - `search_context_size: optional "low" or "medium" or "high"` - - `start_index: number` + 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. - The index of the first character of the container file citation in the message. + - `"low"` - - `type: "container_file_citation"` + - `"medium"` - The type of the container file citation. Always `container_file_citation`. + - `"high"` - - `file_path: object { file_id, index, type }` + - `user_location: optional object { type, city, country, 2 more }` - A path to a file. + The user's location. - - `file_id: string` + - `type: "approximate"` - The ID of the file. + The type of location approximation. Always `approximate`. - - `index: number` + - `city: optional string` - The index of the file in the list of files. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "file_path"` + - `country: optional string` - The type of the file path. Always `file_path`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `text: string` + - `region: optional string` - The text output from the model. + Free text input for the region of the user, e.g. `California`. - - `type: "output_text"` + - `timezone: optional string` - The type of the output text. Always `output_text`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `token: string` + Allows the assistant to create, delete, or update files using unified diffs. - - `bytes: array of number` + - `type: "apply_patch"` - - `logprob: number` + The type of the tool. Always `apply_patch`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `token: string` + The tool invocation context(s). - - `bytes: array of number` + - `"direct"` - - `logprob: number` + - `"programmatic"` -### Beta Response Output Text Annotation Added Event + - `type: "tool_search_output"` -- `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` + The item type. Always `tool_search_output`. - Emitted when an annotation is added to output text content. + - `id: optional string` - - `annotation: unknown` + The unique ID of this tool search output. - The annotation object being added. (See annotation schema for details.) + - `agent: optional object { agent_name }` - - `annotation_index: number` + The agent that produced this item. - The index of the annotation within the content part. + - `agent_name: string` - - `content_index: number` + The canonical name of the agent that produced this item. - The index of the content part within the output item. + - `call_id: optional string` - - `item_id: string` + The unique ID of the tool search call generated by the model. - The unique identifier of the item to which the annotation is being added. + - `execution: optional "server" or "client"` - - `output_index: number` + Whether tool search was executed by the server or by the client. - The index of the output item in the response's output array. + - `"server"` - - `sequence_number: number` + - `"client"` - The sequence number of this event. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "response.output_text.annotation.added"` + The status of the tool search output. - The type of the event. Always 'response.output_text.annotation.added'. + - `"in_progress"` - - `agent: optional object { agent_name }` + - `"completed"` - The agent that owns this multi-agent streaming event. + - `"incomplete"` - - `agent_name: string` +### Beta Response Usage - The canonical name of the agent that produced this item. +- `beta_response_usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }` -### Beta Response Prompt + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. -- `beta_response_prompt: object { id, variables, version }` + - `input_tokens: number` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The number of input tokens. - - `id: string` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The unique identifier of the prompt template to use. + A detailed breakdown of the input tokens. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `cache_write_tokens: number` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The number of input tokens that were written to the cache. - - `union_member_0: string` + - `cached_tokens: number` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - A text input to the model. + - `output_tokens: number` - - `text: string` + The number of output tokens. - The text input to the model. + - `output_tokens_details: object { reasoning_tokens }` - - `type: "input_text"` + A detailed breakdown of the output tokens. - The type of the input item. Always `input_text`. + - `reasoning_tokens: number` - - `prompt_cache_breakpoint: optional object { mode }` + The number of reasoning tokens. - 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. + - `total_tokens: number` - - `mode: "explicit"` + The total number of tokens used. - The breakpoint mode. Always `explicit`. +### Beta Response Web Search Call Completed Event - - `beta_response_input_image: object { detail, type, file_id, 2 more }` +- `beta_response_web_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Emitted when a web search call is completed. - - `detail: "low" or "high" or "auto" or "original"` + - `item_id: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Unique ID for the output item associated with the web search call. - - `"low"` + - `output_index: number` - - `"high"` + The index of the output item that the web search call is associated with. - - `"auto"` + - `sequence_number: number` - - `"original"` + The sequence number of the web search call being processed. - - `type: "input_image"` + - `type: "response.web_search_call.completed"` - The type of the input item. Always `input_image`. + The type of the event. Always `response.web_search_call.completed`. - - `file_id: optional string` + - `agent: optional object { agent_name }` - The ID of the file to be sent to the model. + The agent that owns this multi-agent streaming event. - - `image_url: optional string` + - `agent_name: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` +### Beta Response Web Search Call In Progress Event - 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. +- `beta_response_web_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `mode: "explicit"` + Emitted when a web search call is initiated. - The breakpoint mode. Always `explicit`. + - `item_id: string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Unique ID for the output item associated with the web search call. - A file input to the model. + - `output_index: number` - - `type: "input_file"` + The index of the output item that the web search call is associated with. - The type of the input item. Always `input_file`. + - `sequence_number: number` - - `detail: optional "auto" or "low" or "high"` + The sequence number of the web search call being processed. - 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`. + - `type: "response.web_search_call.in_progress"` - - `"auto"` + The type of the event. Always `response.web_search_call.in_progress`. - - `"low"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that owns this multi-agent streaming event. - - `file_data: optional string` + - `agent_name: string` - The content of the file to be sent to the model. + The canonical name of the agent that produced this item. - - `file_id: optional string` +### Beta Response Web Search Call Searching Event - The ID of the file to be sent to the model. +- `beta_response_web_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` - - `file_url: optional string` + Emitted when a web search call is executing. - The URL of the file to be sent to the model. + - `item_id: string` - - `filename: optional string` + Unique ID for the output item associated with the web search call. - The name of the file to be sent to the model. + - `output_index: number` - - `prompt_cache_breakpoint: optional object { mode }` + The index of the output item that the web search call is associated with. - 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. + - `sequence_number: number` - - `mode: "explicit"` + The sequence number of the web search call being processed. - The breakpoint mode. Always `explicit`. + - `type: "response.web_search_call.searching"` - - `version: optional string` + The type of the event. Always `response.web_search_call.searching`. - Optional version of the prompt template. + - `agent: optional object { agent_name }` -### Beta Response Queued Event + The agent that owns this multi-agent streaming event. -- `beta_response_queued_event: object { response, sequence_number, type, agent }` + - `agent_name: string` - Emitted when a response is queued and waiting to be processed. + The canonical name of the agent that produced this item. - - `response: object { id, created_at, error, 31 more }` +### Beta Responses Client Event - The full response object that is queued. +- `beta_responses_client_event: object { type, background, context_management, 30 more } or BetaResponseInjectEvent` - - `id: string` + Client events accepted by the Responses WebSocket server. - Unique identifier for this Response. + - `response.create: object { type, background, context_management, 30 more }` - - `created_at: number` + Client event for creating a response over a persistent WebSocket connection. + This payload uses the same top-level fields as `POST /v1/responses`. - Unix timestamp (in seconds) of when this Response was created. + Notes: - - `error: object { code, message }` + - `stream` is implicit over WebSocket and should not be sent. + - `background` is not supported over WebSocket. - An error object returned when the model fails to generate a Response. + - `type: "response.create"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + The type of the client event. Always `response.create`. - The error code for the response. + - `background: optional boolean` - - `"server_error"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `"rate_limit_exceeded"` + - `context_management: optional array of object { type, compact_threshold }` - - `"invalid_prompt"` + Context management configuration for this request. - - `"bio_policy"` + - `type: string` - - `"vector_store_timeout"` + The context management entry type. Currently only 'compaction' is supported. - - `"invalid_image"` + - `compact_threshold: optional number` - - `"invalid_image_format"` + Token threshold at which compaction should be triggered for this entry. - - `"invalid_base64_image"` + - `conversation: optional string or BetaResponseConversationParam` - - `"invalid_image_url"` + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - - `"image_too_large"` + - `Conversation ID: string` - - `"image_too_small"` + The unique ID of the conversation. - - `"image_parse_error"` + - `beta_response_conversation_param: object { id }` - - `"image_content_policy_violation"` + The conversation that this response belongs to. - - `"invalid_image_mode"` + - `id: string` - - `"image_file_too_large"` + The unique ID of the conversation. - - `"unsupported_image_media_type"` + - `include: optional array of BetaResponseIncludable` - - `"empty_image_file"` + Specify additional output data to include in the model response. Currently supported values are: - - `"failed_to_download_image"` + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - `"image_file_not_found"` + - `"file_search_call.results"` - - `message: string` + - `"web_search_call.results"` - A human-readable description of the error. + - `"web_search_call.action.sources"` - - `incomplete_details: object { reason }` + - `"message.input_image.image_url"` - Details about why the response is incomplete. + - `"computer_call_output.output.image_url"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `"code_interpreter_call.outputs"` - The reason why the response is incomplete. + - `"reasoning.encrypted_content"` - - `"max_output_tokens"` + - `"message.output_text.logprobs"` - - `"content_filter"` + - `input: optional string or BetaResponseInput` - - `instructions: string or array of BetaResponseInputItem` + Text, image, or file inputs to the model, used to generate a response. - A system (or developer) message inserted into the model's context. + Learn more: - When using 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. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) - - `union_member_0: string` + - `Text input: string` A text input to the model, equivalent to a text input with the - `developer` role. + `user` role. - - `Input item list: array of BetaResponseInputItem` + - `beta_response_input: array of BetaResponseInputItem` A list of one or many input items to the model, containing different content types. @@ -105973,7 +117708,7 @@ openai beta:responses compact \ - `"developer"` - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -105981,6 +117716,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `type: optional "message"` The type of the message input. Always `message`. @@ -106216,7 +117953,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -106224,6 +117961,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -107334,7 +119073,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -107344,7 +119083,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -107391,7 +119134,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -107401,7 +119144,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -109445,7 +121192,23 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `metadata: map[string]` + - `instructions: optional string` + + A system (or developer) message inserted into the model's context. + + When using 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. + + - `max_output_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: optional number` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `metadata: optional map[string]` 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 @@ -109454,7 +121217,7 @@ openai beta:responses compact \ Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance @@ -109651,150 +121414,77 @@ openai beta:responses compact \ - `"gpt-5.1-codex-max"` - - `object: "response"` - - The object type of this resource - always set to `response`. - - - `output: array of BetaResponseOutputItem` - - An array of content items generated by the model. - - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. - - - `beta_response_output_message: object { id, content, role, 4 more }` - - An output message from the model. - - - `id: string` - - The unique ID of the output message. - - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - The content of the output message. - - - `role: "assistant"` - - The role of the output message. Always `assistant`. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `type: "message"` - - The type of the output message. Always `message`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `phase: optional "commentary"` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - The results of a file search tool call. See the - [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - - `id: string` - - The unique ID of the file search tool call. - - - `queries: array of string` - - The queries used to search for files. - - - `status: "in_progress" or "searching" or "completed" or 2 more` - - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `moderation: optional object { model, policy }` - - `type: "file_search_call"` + Configuration for running moderation on the input and output of this response. - The type of the file search tool call. Always `file_search_call`. + - `model: string` - - `agent: optional object { agent_name }` + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - The agent that produced this item. + - `policy: optional object { input, output }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The policy to apply to moderated response input and output. - The results of the file search tool call. + - `input: optional object { mode }` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + The moderation policy for the response input. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `mode: "score" or "block"` - - `arguments: string` + - `"score"` - A JSON string of the arguments to pass to the function. + - `"block"` - - `call_id: string` + - `output: optional object { mode }` - The unique ID of the function tool call generated by the model. + The moderation policy for the response output. - - `name: string` + - `mode: "score" or "block"` - The name of the function to run. + - `"score"` - - `type: "function_call"` + - `"block"` - The type of the function tool call. Always `function_call`. + - `multi_agent: optional object { enabled, max_concurrent_subagents }` - - `id: optional string` + Configuration for server-hosted multi-agent execution. - The unique ID of the function tool call. + - `enabled: boolean` - - `agent: optional object { agent_name }` + Whether to enable server-hosted multi-agent execution for this response. - The agent that produced this item. + - `max_concurrent_subagents: optional number` - - `caller: optional object { type } or object { caller_id, type }` + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. - The execution context that produced this tool call. + - `parallel_tool_calls: optional boolean` - - `namespace: optional string` + Whether to allow the model to run tool calls in parallel. - The namespace of the function to run. + - `previous_response_id: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + 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`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `prompt: optional object { id, variables, version }` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - The unique ID of the function call tool output. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `string output: string` + The unique identifier of the prompt template to use. - A string of the output of the function call. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - Text, image, or file output of the function call. + - `union_member_0: string` - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` @@ -109808,1118 +121498,1229 @@ openai beta:responses compact \ A file input to the model. - - `status: "in_progress" or "completed" or "incomplete"` + - `version: optional string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Optional version of the prompt template. - - `"in_progress"` + - `prompt_cache_key: optional string` - - `"completed"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"incomplete"` + - `prompt_cache_options: optional object { mode, ttl }` - - `type: "function_call_output"` + 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. - The type of the function tool call output. Always `function_call_output`. + - `mode: optional "implicit" or "explicit"` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + - `"implicit"` - - `agent_name: string` + - `"explicit"` - The canonical name of the agent that produced this item. + - `ttl: optional "30m"` - - `caller: optional object { type } or object { caller_id, type }` + 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. - The execution context that produced this tool call. + - `"30m"` - - `direct: object { type }` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `program: object { caller_id, type }` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `caller_id: string` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - The call ID of the program item that produced this tool call. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `type: "program"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The caller type. Always `program`. + - `"in_memory"` - - `created_by: optional string` + - `"24h"` - The identifier of the actor that created the item. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `agent_message: object { id, author, content, 3 more }` + **gpt-5 and o-series models only** - - `id: string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The unique ID of the agent message. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `author: string` + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. - The sending agent identity. + - `"auto"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"current_turn"` - Encrypted content sent between agents. + - `"all_turns"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `effort: optional "none" or "minimal" or "low" or 4 more` - A text input to the model. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"none"` - A text output from the model. + - `"minimal"` - - `text: object { text, type }` + - `"low"` - A text content. + - `"medium"` - - `text: string` + - `"high"` - - `type: "text"` + - `"xhigh"` - - `summary_text: object { text, type }` + - `"max"` - A summary text from the model. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `text: string` + **Deprecated:** use `summary` instead. - A summary of the reasoning output from the model so far. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `type: "summary_text"` + - `"auto"` - The type of the object. Always `summary_text`. + - `"concise"` - - `reasoning_text: object { text, type }` + - `"detailed"` - Reasoning text from the model. + - `mode: optional string or "standard" or "pro"` - - `text: string` + Controls the reasoning execution mode for the request. - The reasoning text from the model. + When returned on a response, this is the effective execution mode. - - `type: "reasoning_text"` + - `"standard"` - The type of the reasoning text. Always `reasoning_text`. + - `"pro"` - - `beta_response_output_refusal: object { refusal, type }` + - `summary: optional "auto" or "concise" or "detailed"` - A refusal from the model. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `"auto"` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `"concise"` - A screenshot of a computer. + - `"detailed"` - - `detail: "low" or "high" or "auto" or "original"` + - `safety_identifier: optional string` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"low"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `"high"` + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - `"auto"` - - `"original"` + - `"default"` - - `file_id: string` + - `"flex"` - The identifier of an uploaded file that contains the screenshot. + - `"scale"` - - `image_url: string` + - `"priority"` - The URL of the screenshot image. + - `store: optional boolean` - - `type: "computer_screenshot"` + Whether to store the generated model response for later retrieval via + API. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `stream: optional boolean` - - `prompt_cache_breakpoint: optional object { mode }` + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. - 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. + - `stream_options: optional object { include_obfuscation }` - - `mode: "explicit"` + Options for streaming responses. Only set this when you set `stream: true`. - The breakpoint mode. Always `explicit`. + - `include_obfuscation: optional boolean` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. - A file input to the model. + - `temperature: optional number` - - `encrypted_content: object { encrypted_content, type }` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `text: optional object { format, verbosity }` - - `encrypted_content: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - Opaque encrypted content. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `type: "encrypted_content"` + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - The type of the input item. Always `encrypted_content`. + An object specifying the format that the model must output. - - `recipient: string` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The destination agent identity. + The default format is `{ "type": "text" }` with no additional options. - - `type: "agent_message"` + **Not recommended for gpt-4o and newer models:** - The type of the item. Always `agent_message`. + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `agent: optional object { agent_name }` + - `text: object { type }` - The agent that produced this item. + Default response format. Used to generate text responses. - - `agent_name: string` + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` - The canonical name of the agent that produced this item. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `name: string` - - `id: string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The unique ID of the multi-agent call item. + - `schema: map[unknown]` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The multi-agent action to execute. + - `type: "json_schema"` - - `"spawn_agent"` + The type of response format being defined. Always `json_schema`. - - `"interrupt_agent"` + - `description: optional string` - - `"list_agents"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"send_message"` + - `strict: optional boolean` - - `"followup_task"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"wait_agent"` + - `json_object: object { type }` - - `arguments: string` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The JSON string of arguments generated for the action. + - `verbosity: optional "low" or "medium" or "high"` - - `call_id: string` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - The unique ID linking this call to its output. + - `"low"` - - `type: "multi_agent_call"` + - `"medium"` - The type of the multi-agent call. Always `multi_agent_call`. + - `"high"` - - `agent: optional object { agent_name }` + - `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The agent that produced this item. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `agent_name: string` + - `beta_tool_choice_options: "none" or "auto" or "required"` - The canonical name of the agent that produced this item. + Controls which (if any) tool is called by the model. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + `none` means the model will not call any tool and instead generates a message. - - `id: string` + `auto` means the model can pick between generating a message or calling one or + more tools. - The unique ID of the multi-agent call output item. + `required` means the model must call one or more tools. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"none"` - The multi-agent action that produced this result. + - `"auto"` - - `"spawn_agent"` + - `"required"` - - `"interrupt_agent"` + - `beta_tool_choice_allowed: object { mode, tools, type }` - - `"list_agents"` + Constrains the tools available to the model to a pre-defined set. - - `"send_message"` + - `mode: "auto" or "required"` - - `"followup_task"` + Constrains the tools available to the model to a pre-defined set. - - `"wait_agent"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `call_id: string` + `required` requires the model to call one or more of the allowed tools. - The unique ID of the multi-agent call. + - `"auto"` - - `output: array of BetaResponseOutputText` + - `"required"` - Text output returned by the multi-agent action. + - `tools: array of map[unknown]` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + A list of tool definitions that the model should be allowed to call. - The annotations of the text output. + For the Responses API, the list of tool definitions might look like: - - `text: string` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The text output from the model. + - `type: "allowed_tools"` - - `type: "output_text"` + Allowed tool configuration type. Always `allowed_tools`. - The type of the output text. Always `output_text`. + - `beta_tool_choice_types: object { type }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - - `type: "multi_agent_call_output"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - The type of the multi-agent result. Always `multi_agent_call_output`. + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - - `agent: optional object { agent_name }` + Allowed values are: - The agent that produced this item. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `agent_name: string` + - `"file_search"` - The canonical name of the agent that produced this item. + - `"web_search_preview"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `"computer"` - 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. + - `"computer_use_preview"` - - `id: string` + - `"computer_use"` - The unique ID of the web search tool call. + - `"web_search_preview_2025_03_11"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `"image_generation"` - 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). + - `"code_interpreter"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `beta_tool_choice_function: object { name, type }` - The status of the web search tool call. + Use this option to force the model to call a specific function. - - `type: "web_search_call"` + - `name: string` - The type of the web search tool call. Always `web_search_call`. + The name of the function to call. - - `agent: optional object { agent_name }` + - `type: "function"` - The agent that produced this item. + For function calling, the type is always `function`. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `beta_tool_choice_mcp: object { server_label, type, name }` - 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. + Use this option to force the model to call a specific tool on a remote MCP server. - - `id: string` + - `server_label: string` - The unique ID of the computer call. + The label of the MCP server to use. - - `call_id: string` + - `type: "mcp"` - An identifier used when responding to the tool call with output. + For MCP tools, the type is always `mcp`. - - `pending_safety_checks: array of object { id, code, message }` + - `name: optional string` - The pending safety checks for the computer call. + The name of the tool to call on the server. - - `status: "in_progress" or "completed" or "incomplete"` + - `beta_tool_choice_custom: object { name, type }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Use this option to force the model to call a specific custom tool. - - `type: "computer_call"` + - `name: string` - The type of the computer call. Always `computer_call`. + The name of the custom tool to call. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `type: "custom"` - A click action. + For custom tool calling, the type is always `custom`. - - `actions: optional array of BetaComputerAction` + - `BetaSpecificProgrammaticToolCallingParam: object { type }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `beta_tool_choice_apply_patch: object { type }` - - `agent: optional object { agent_name }` + Forces the model to call the apply_patch tool when executing a tool call. - The agent that produced this item. + - `type: "apply_patch"` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + The tool to call. Always `apply_patch`. - - `id: string` + - `beta_tool_choice_shell: object { type }` - The unique ID of the computer call tool output. + Forces the model to call the shell tool when a tool call is required. - - `call_id: string` + - `type: "shell"` - The ID of the computer tool call that produced the output. + The tool to call. Always `shell`. - - `output: object { type, file_id, image_url }` + - `tools: optional array of BetaTool` - A computer screenshot image used with the computer use tool. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `type: "computer_screenshot"` + We support the following categories of tools: - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `file_id: optional string` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The identifier of an uploaded file that contains the screenshot. + 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). - - `image_url: optional string` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The URL of the screenshot image. + 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). - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `beta_computer_tool: object { type }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"completed"` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `"incomplete"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"failed"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - - `"in_progress"` + 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: "computer_call_output"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - The type of the computer tool call output. Always `computer_call_output`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `code_interpreter: object { container, type, allowed_callers }` - The safety checks reported by the API that have been acknowledged by the - developer. + A tool that runs Python code to help generate a response to a prompt. - - `id: string` + - `programmatic_tool_calling: object { type }` - The ID of the pending safety check. + - `image_generation: object { type, action, background, 9 more }` - - `code: optional string` + A tool that generates images using the GPT image models. - The type of the pending safety check. + - `local_shell: object { type }` - - `message: optional string` + A tool that allows the model to execute shell commands in a local environment. - Details about the pending safety check. + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `agent: optional object { agent_name }` + A tool that allows the model to execute shell commands. - The agent that produced this item. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `agent_name: string` + 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) - The canonical name of the agent that produced this item. + - `beta_namespace_tool: object { description, name, tools, type }` - - `created_by: optional string` + Groups function/custom tools under a shared namespace. - The identifier of the actor that created the item. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + Hosted or BYOT tool search configuration for deferred tools. - 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). + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `id: string` + 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). - The unique identifier of the reasoning content. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `summary: array of object { text, type }` + Allows the assistant to create, delete, or update files using unified diffs. - Reasoning summary content. + - `top_logprobs: optional number` - - `type: "reasoning"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - The type of the object. Always `reasoning`. + - `top_p: optional number` - - `agent: optional object { agent_name }` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - The agent that produced this item. + We generally recommend altering this or `temperature` but not both. - - `content: optional array of object { text, type }` + - `truncation: optional "auto" or "disabled"` - Reasoning text content. + The truncation strategy to use for the model response. - - `encrypted_content: optional string` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"disabled"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `user: optional string` - - `program: object { id, call_id, code, 3 more }` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `id: string` + - `beta_response_inject_event: object { input, response_id, type }` - The unique ID of the program item. + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. - - `call_id: string` + - `input: array of BetaResponseInputItem` - The stable call ID of the program item. + Input items to inject into the active response. - - `code: string` + - `beta_easy_input_message: object { content, role, phase, type }` - The JavaScript source executed by programmatic tool calling. + 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. - - `fingerprint: string` + - `message: object { content, role, agent, 2 more }` - Opaque program replay fingerprint that must be round-tripped. + 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. - - `type: "program"` + - `beta_response_output_message: object { id, content, role, 4 more }` - The type of the item. Always `program`. + An output message from the model. - - `agent: optional object { agent_name }` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - The agent that produced this item. + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - - `agent_name: string` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - The canonical name of the agent that produced this item. + 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. - - `program_output: object { id, call_id, result, 3 more }` + - `computer_call_output: object { call_id, output, type, 4 more }` - - `id: string` + The output of a computer tool call. - The unique ID of the program output item. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `call_id: string` + 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. - The call ID of the program item. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `result: string` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - The result produced by the program item. + - `function_call_output: object { call_id, output, type, 4 more }` - - `status: "completed" or "incomplete"` + The output of a function tool call. - The terminal status of the program output item. + - `agent_message: object { author, content, recipient, 3 more }` - - `"completed"` + A message routed between agents. - - `"incomplete"` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - `type: "program_output"` + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - The type of the item. Always `program_output`. + - `tool_search_call: object { arguments, type, id, 4 more }` - - `agent: optional object { agent_name }` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - The agent that produced this item. + - `additional_tools: object { role, tools, type, 2 more }` - - `agent_name: string` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - The canonical name of the agent that produced this item. + 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). - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - - `id: string` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The unique ID of the tool search call item. + - `image_generation_call: object { id, result, status, 2 more }` - - `arguments: unknown` + An image generation request made by the model. - Arguments used for the tool search call. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `call_id: string` + A tool call to run code. - The unique ID of the tool search call generated by the model. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `execution: "server" or "client"` + A tool call to run a command on the local shell. - Whether tool search was executed by the server or by the client. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `"server"` + The output of a local shell tool call. - - `"client"` + - `shell_call: object { action, call_id, type, 5 more }` - - `status: "in_progress" or "completed" or "incomplete"` + A tool representing a request to execute one or more shell commands. - The status of the tool search call item that was recorded. + - `shell_call_output: object { call_id, output, type, 5 more }` - - `"in_progress"` + The streamed output items emitted by a shell tool call. - - `"completed"` + - `apply_patch_call: object { call_id, operation, status, 4 more }` - - `"incomplete"` + A tool call representing a request to create, delete, or update files using diff patches. - - `type: "tool_search_call"` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The type of the item. Always `tool_search_call`. + The streamed output emitted by an apply patch tool call. - - `agent: optional object { agent_name }` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The agent that produced this item. + A list of tools available on an MCP server. - - `agent_name: string` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - The canonical name of the agent that produced this item. + A request for human approval of a tool invocation. - - `created_by: optional string` + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - The identifier of the actor that created the item. + A response to an MCP approval request. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `mcp_call: object { id, arguments, name, 7 more }` - - `id: string` + An invocation of a tool on an MCP server. - The unique ID of the tool search output item. + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `call_id: string` + The output of a custom tool call from your code, being sent back to the model. - The unique ID of the tool search call generated by the model. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `execution: "server" or "client"` + A call to a custom tool created by the model. - Whether tool search was executed by the server or by the client. + - `compaction_trigger: object { type, agent }` - - `"server"` + Compacts the current context. Must be the final input item. - - `"client"` + - `item_reference: object { id, agent, type }` - - `status: "in_progress" or "completed" or "incomplete"` + An internal identifier for an item to reference. - The status of the tool search output item that was recorded. + - `program: object { id, call_id, code, 3 more }` - - `"in_progress"` + - `program_output: object { id, call_id, result, 3 more }` - - `"completed"` + - `response_id: string` - - `"incomplete"` + The ID of the active response that should receive the input. - - `tools: array of BetaTool` + - `type: "response.inject"` - The loaded tool definitions returned by tool search. + The event discriminator. Always `response.inject`. - - `beta_function_tool: object { name, parameters, strict, 5 more }` +### Beta Responses Server Event - 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). +- `beta_responses_server_event: BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 52 more` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + Server events emitted by the Responses WebSocket server. - 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). + - `beta_response_audio_delta_event: object { delta, sequence_number, type, agent }` - - `beta_computer_tool: object { type }` + Emitted when there is a partial audio response. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `delta: string` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + A chunk of Base64 encoded response audio bytes. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `sequence_number: number` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + A sequence number for this chunk of the stream response. - 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: "response.audio.delta"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The type of the event. Always `response.audio.delta`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `agent: optional object { agent_name }` - - `code_interpreter: object { container, type, allowed_callers }` + The agent that owns this multi-agent streaming event. - A tool that runs Python code to help generate a response to a prompt. + - `agent_name: string` - - `programmatic_tool_calling: object { type }` + The canonical name of the agent that produced this item. - - `image_generation: object { type, action, background, 9 more }` + - `beta_response_audio_done_event: object { sequence_number, type, agent }` - A tool that generates images using the GPT image models. + Emitted when the audio response is complete. - - `local_shell: object { type }` + - `sequence_number: number` - A tool that allows the model to execute shell commands in a local environment. + The sequence number of the delta. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `type: "response.audio.done"` - A tool that allows the model to execute shell commands. + The type of the event. Always `response.audio.done`. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `agent: optional object { agent_name }` - 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) + The agent that owns this multi-agent streaming event. - - `beta_namespace_tool: object { description, name, tools, type }` + - `agent_name: string` - Groups function/custom tools under a shared namespace. + The canonical name of the agent that produced this item. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `beta_response_audio_transcript_delta_event: object { delta, sequence_number, type, agent }` - Hosted or BYOT tool search configuration for deferred tools. + Emitted when there is a partial transcript of audio. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `delta: string` - 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). + The partial transcript of the audio response. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `sequence_number: number` - Allows the assistant to create, delete, or update files using unified diffs. + The sequence number of this event. - - `type: "tool_search_output"` + - `type: "response.audio.transcript.delta"` - The type of the item. Always `tool_search_output`. + The type of the event. Always `response.audio.transcript.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `created_by: optional string` + - `beta_response_audio_transcript_done_event: object { sequence_number, type, agent }` - The identifier of the actor that created the item. + Emitted when the full audio transcript is completed. - - `additional_tools: object { id, role, tools, 2 more }` + - `sequence_number: number` - - `id: string` + The sequence number of this event. - The unique ID of the additional tools item. + - `type: "response.audio.transcript.done"` - - `role: "unknown" or "user" or "assistant" or 5 more` + The type of the event. Always `response.audio.transcript.done`. - The role that provided the additional tools. + - `agent: optional object { agent_name }` - - `"unknown"` + The agent that owns this multi-agent streaming event. - - `"user"` + - `agent_name: string` - - `"assistant"` + The canonical name of the agent that produced this item. - - `"system"` + - `beta_response_code_interpreter_call_code_delta_event: object { delta, item_id, output_index, 3 more }` - - `"critic"` + Emitted when a partial code snippet is streamed by the code interpreter. - - `"discriminator"` + - `delta: string` - - `"developer"` + The partial code snippet being streamed by the code interpreter. - - `"tool"` + - `item_id: string` - - `tools: array of BetaTool` + The unique identifier of the code interpreter tool call item. - The additional tool definitions made available at this item. + - `output_index: number` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The index of the output item in the response for which the code is being streamed. - 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). + - `sequence_number: number` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The sequence number of this event, used to order streaming events. - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + - `type: "response.code_interpreter_call_code.delta"` - - `beta_computer_tool: object { type }` + The type of the event. Always `response.code_interpreter_call_code.delta`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent: optional object { agent_name }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The agent that owns this multi-agent streaming event. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: string` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The canonical name of the agent that produced this item. - 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). + - `beta_response_code_interpreter_call_code_done_event: object { code, item_id, output_index, 3 more }` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + Emitted when the code snippet is finalized by the code interpreter. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `code: string` - - `code_interpreter: object { container, type, allowed_callers }` + The final code snippet output by the code interpreter. - A tool that runs Python code to help generate a response to a prompt. + - `item_id: string` - - `programmatic_tool_calling: object { type }` + The unique identifier of the code interpreter tool call item. - - `image_generation: object { type, action, background, 9 more }` + - `output_index: number` - A tool that generates images using the GPT image models. + The index of the output item in the response for which the code is finalized. - - `local_shell: object { type }` + - `sequence_number: number` - A tool that allows the model to execute shell commands in a local environment. + The sequence number of this event, used to order streaming events. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `type: "response.code_interpreter_call_code.done"` - A tool that allows the model to execute shell commands. + The type of the event. Always `response.code_interpreter_call_code.done`. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `agent: optional object { agent_name }` - 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) + The agent that owns this multi-agent streaming event. - - `beta_namespace_tool: object { description, name, tools, type }` + - `agent_name: string` - Groups function/custom tools under a shared namespace. + The canonical name of the agent that produced this item. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `beta_response_code_interpreter_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - Hosted or BYOT tool search configuration for deferred tools. + Emitted when the code interpreter call is completed. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `item_id: string` - 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). + The unique identifier of the code interpreter tool call item. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `output_index: number` - Allows the assistant to create, delete, or update files using unified diffs. + The index of the output item in the response for which the code interpreter call is completed. - - `type: "additional_tools"` + - `sequence_number: number` - The type of the item. Always `additional_tools`. + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call.completed"` + + The type of the event. Always `response.code_interpreter_call.completed`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `beta_response_code_interpreter_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Emitted when a code interpreter call is in progress. - - `id: string` + - `item_id: string` - The unique ID of the compaction item. + The unique identifier of the code interpreter tool call item. - - `encrypted_content: string` + - `output_index: number` - The encrypted content that was produced by compaction. + The index of the output item in the response for which the code interpreter call is in progress. - - `type: "compaction"` + - `sequence_number: number` - The type of the item. Always `compaction`. + The sequence number of this event, used to order streaming events. + + - `type: "response.code_interpreter_call.in_progress"` + + The type of the event. Always `response.code_interpreter_call.in_progress`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `image_generation_call: object { id, result, status, 2 more }` - - An image generation request made by the model. - - - `id: string` - - The unique ID of the image generation call. - - - `result: string` + - `beta_response_code_interpreter_call_interpreting_event: object { item_id, output_index, sequence_number, 2 more }` - The generated image encoded in base64. + Emitted when the code interpreter is actively interpreting the code snippet. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `item_id: string` - The status of the image generation call. + The unique identifier of the code interpreter tool call item. - - `"in_progress"` + - `output_index: number` - - `"completed"` + The index of the output item in the response for which the code interpreter is interpreting code. - - `"generating"` + - `sequence_number: number` - - `"failed"` + The sequence number of this event, used to order streaming events. - - `type: "image_generation_call"` + - `type: "response.code_interpreter_call.interpreting"` - The type of the image generation call. Always `image_generation_call`. + The type of the event. Always `response.code_interpreter_call.interpreting`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `beta_response_completed_event: object { response, sequence_number, type, agent }` - A tool call to run code. + Emitted when the model response is complete. - - `id: string` + - `response: object { id, created_at, error, 31 more }` - The unique ID of the code interpreter tool call. + Properties of the completed response. - - `code: string` + - `id: string` - The code to run, or null if not available. + Unique identifier for this Response. - - `container_id: string` + - `created_at: number` - The ID of the container used to run the code. + Unix timestamp (in seconds) of when this Response was created. - - `outputs: array of object { logs, type } or object { type, url }` + - `error: object { code, message }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + An error object returned when the model fails to generate a Response. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The error code for the response. - - `type: "code_interpreter_call"` + - `"server_error"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"rate_limit_exceeded"` - - `agent: optional object { agent_name }` + - `"invalid_prompt"` - The agent that produced this item. + - `"bio_policy"` - - `local_shell_call: object { id, action, call_id, 3 more }` + - `"vector_store_timeout"` - A tool call to run a command on the local shell. + - `"invalid_image"` - - `id: string` + - `"invalid_image_format"` - The unique ID of the local shell call. + - `"invalid_base64_image"` - - `action: object { command, env, type, 3 more }` + - `"invalid_image_url"` - Execute a shell command on the server. + - `"image_too_large"` - - `command: array of string` + - `"image_too_small"` - The command to run. + - `"image_parse_error"` - - `env: map[string]` + - `"image_content_policy_violation"` - Environment variables to set for the command. + - `"invalid_image_mode"` - - `type: "exec"` + - `"image_file_too_large"` - The type of the local shell action. Always `exec`. + - `"unsupported_image_media_type"` - - `timeout_ms: optional number` + - `"empty_image_file"` - Optional timeout in milliseconds for the command. + - `"failed_to_download_image"` - - `user: optional string` + - `"image_file_not_found"` - Optional user to run the command as. + - `message: string` - - `working_directory: optional string` + A human-readable description of the error. - Optional working directory to run the command in. + - `incomplete_details: object { reason }` - - `call_id: string` + Details about why the response is incomplete. - The unique ID of the local shell tool call generated by the model. + - `reason: optional "max_output_tokens" or "content_filter"` - - `status: "in_progress" or "completed" or "incomplete"` + The reason why the response is incomplete. - The status of the local shell call. + - `"max_output_tokens"` - - `"in_progress"` + - `"content_filter"` - - `"completed"` + - `instructions: string or array of BetaResponseInputItem` - - `"incomplete"` + A system (or developer) message inserted into the model's context. - - `type: "local_shell_call"` + When using 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. - The type of the local shell call. Always `local_shell_call`. + - `union_member_0: string` - - `agent: optional object { agent_name }` + A text input to the model, equivalent to a text input with the + `developer` role. - The agent that produced this item. + - `Input item list: array of BetaResponseInputItem` - - `agent_name: string` + A list of one or many input items to the model, containing + different content types. - The canonical name of the agent that produced this item. + - `beta_easy_input_message: object { content, role, phase, type }` - - `local_shell_call_output: object { id, output, type, 2 more }` + 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. - The output of a local shell tool call. + - `content: string or BetaResponseInputMessageContentList` - - `id: string` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The unique ID of the local shell tool call generated by the model. + - `Text input: string` - - `output: string` + A text input to the model. - A JSON string of the output of the local shell tool call. + - `beta_response_input_message_content_list: array of BetaResponseInputContent` - - `type: "local_shell_call_output"` + A list of one or many input items to the model, containing different content + types. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text input to the model. - The canonical name of the agent that produced this item. + - `type: "input_text"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the input item. Always `input_text`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"in_progress"` + 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. - - `"completed"` + - `mode: "explicit"` - - `"incomplete"` + The breakpoint mode. Always `explicit`. - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - A tool call that executes one or more shell commands in a managed environment. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `id: string` + - `detail: "low" or "high" or "auto" or "original"` - The unique ID of the shell tool call. Populated when this item is returned via API. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `action: object { commands, max_output_length, timeout_ms }` + - `"low"` - The shell commands and limits that describe how to run the tool call. + - `"high"` - - `commands: array of string` + - `"auto"` - - `max_output_length: number` + - `"original"` - Optional maximum number of characters to return from each command. + - `type: "input_image"` - - `timeout_ms: number` + The type of the input item. Always `input_image`. - Optional timeout in milliseconds for the commands. + - `file_id: optional string` - - `call_id: string` + The ID of the file to be sent to the model. - The unique ID of the shell tool call generated by the model. + - `image_url: optional string` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Represents the use of a local environment to perform shell actions. + - `prompt_cache_breakpoint: optional object { mode }` - - `beta_response_local_environment: object { type }` + 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. - Represents the use of a local environment to perform shell actions. + - `mode: "explicit"` - - `type: "local"` + The breakpoint mode. Always `explicit`. - The environment type. Always `local`. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `beta_response_container_reference: object { container_id, type }` + A file input to the model. - Represents a container created with /v1/containers. + - `type: "input_file"` - - `container_id: string` + The type of the input item. Always `input_file`. - - `type: "container_reference"` + - `detail: optional "auto" or "low" or "high"` - The environment type. Always `container_reference`. + 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`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"low"` - - `"in_progress"` + - `"high"` - - `"completed"` + - `file_data: optional string` - - `"incomplete"` + The content of the file to be sent to the model. - - `type: "shell_call"` + - `file_id: optional string` - The type of the item. Always `shell_call`. + The ID of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `file_url: optional string` - The agent that produced this item. + The URL of the file to be sent to the model. - - `agent_name: string` + - `filename: optional string` - The canonical name of the agent that produced this item. + The name of the file to be sent to the model. - - `caller: optional object { type } or object { caller_id, type }` + - `prompt_cache_breakpoint: optional object { mode }` - The execution context that produced this tool call. + 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. - - `direct: object { type }` + - `mode: "explicit"` - - `program: object { caller_id, type }` + The breakpoint mode. Always `explicit`. - - `caller_id: string` + - `role: "user" or "assistant" or "system" or "developer"` - The call ID of the program item that produced this tool call. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `type: "program"` + - `"user"` - - `created_by: optional string` + - `"assistant"` - The ID of the entity that created this tool call. + - `"system"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `"developer"` - The output of a shell tool call that was emitted. + - `phase: optional "commentary" or "final_answer"` - - `id: string` + 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. - The unique ID of the shell call output. Populated when this item is returned via API. + - `"commentary"` - - `call_id: string` + - `"final_answer"` - The unique ID of the shell tool call generated by the model. + - `type: optional "message"` - - `max_output_length: number` + The type of the message input. Always `message`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"message"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `message: object { content, role, agent, 2 more }` - An array of shell call output contents + 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. - - `outcome: object { type } or object { exit_code, type }` + - `content: array of BetaResponseInputContent` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + A list of one or many input items to the model, containing different content + types. - - `timeout: object { type }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - Indicates that the shell call exceeded its configured time limit. + A text input to the model. - - `exit: object { exit_code, type }` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - Indicates that the shell commands finished and returned an exit code. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `exit_code: number` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - Exit code from the shell process. + A file input to the model. - - `type: "exit"` + - `role: "user" or "system" or "developer"` - The outcome type. Always `exit`. + The role of the message input. One of `user`, `system`, or `developer`. - - `stderr: string` + - `"user"` - The standard error output that was captured. + - `"system"` - - `stdout: string` + - `"developer"` - The standard output that was captured. + - `agent: optional object { agent_name }` - - `created_by: optional string` + The agent that produced this item. - The identifier of the actor that created the item. + - `agent_name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The canonical name of the agent that produced this item. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -110927,211 +122728,224 @@ openai beta:responses compact \ - `"incomplete"` - - `type: "shell_call_output"` + - `type: optional "message"` - The type of the shell call output. Always `shell_call_output`. + The type of the message input. Always set to `message`. - - `agent: optional object { agent_name }` + - `"message"` - The agent that produced this item. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `agent_name: string` + An output message from the model. - The canonical name of the agent that produced this item. + - `id: string` - - `caller: optional object { type } or object { caller_id, type }` + The unique ID of the output message. - The execution context that produced this tool call. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `direct: object { type }` + The content of the output message. - - `program: object { caller_id, type }` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `caller_id: string` + A text output from the model. - The call ID of the program item that produced this tool call. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `type: "program"` + The annotations of the text output. - - `created_by: optional string` + - `file_citation: object { file_id, filename, index, type }` - The identifier of the actor that created the item. + A citation to a file. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `file_id: string` - A tool call that applies file diffs by creating, deleting, or updating files. + The ID of the file. - - `id: string` + - `filename: string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The filename of the file cited. - - `call_id: string` + - `index: number` - The unique ID of the apply patch tool call generated by the model. + The index of the file in the list of files. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `type: "file_citation"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The type of the file citation. Always `file_citation`. - - `create_file: object { diff, path, type }` + - `url_citation: object { end_index, start_index, title, 2 more }` - Instruction describing how to create a file via the apply_patch tool. + A citation for a web resource used to generate a model response. - - `diff: string` + - `end_index: number` - Diff to apply. + The index of the last character of the URL citation in the message. - - `path: string` + - `start_index: number` - Path of the file to create. + The index of the first character of the URL citation in the message. - - `type: "create_file"` + - `title: string` - Create a new file with the provided diff. + The title of the web resource. - - `delete_file: object { path, type }` + - `type: "url_citation"` - Instruction describing how to delete a file via the apply_patch tool. + The type of the URL citation. Always `url_citation`. - - `path: string` + - `url: string` - Path of the file to delete. + The URL of the web resource. - - `type: "delete_file"` + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - Delete the specified file. + A citation for a container file used to generate a model response. - - `update_file: object { diff, path, type }` + - `container_id: string` - Instruction describing how to update a file via the apply_patch tool. + The ID of the container file. - - `diff: string` + - `end_index: number` - Diff to apply. + The index of the last character of the container file citation in the message. - - `path: string` + - `file_id: string` - Path of the file to update. + The ID of the file. - - `type: "update_file"` + - `filename: string` - Update an existing file with the provided diff. + The filename of the container file cited. - - `status: "in_progress" or "completed"` + - `start_index: number` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The index of the first character of the container file citation in the message. - - `"in_progress"` + - `type: "container_file_citation"` - - `"completed"` + The type of the container file citation. Always `container_file_citation`. - - `type: "apply_patch_call"` + - `file_path: object { file_id, index, type }` - The type of the item. Always `apply_patch_call`. + A path to a file. - - `agent: optional object { agent_name }` + - `file_id: string` - The agent that produced this item. + The ID of the file. - - `agent_name: string` + - `index: number` - The canonical name of the agent that produced this item. + The index of the file in the list of files. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "file_path"` - The execution context that produced this tool call. + The type of the file path. Always `file_path`. - - `direct: object { type }` + - `text: string` - - `program: object { caller_id, type }` + The text output from the model. - - `caller_id: string` + - `type: "output_text"` - The call ID of the program item that produced this tool call. + The type of the output text. Always `output_text`. - - `type: "program"` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `created_by: optional string` + - `token: string` - The ID of the entity that created this tool call. + - `bytes: array of number` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `logprob: number` - The output emitted by an apply patch tool call. + - `top_logprobs: array of object { token, bytes, logprob }` - - `id: string` + - `token: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `bytes: array of number` - - `call_id: string` + - `logprob: number` - The unique ID of the apply patch tool call generated by the model. + - `beta_response_output_refusal: object { refusal, type }` - - `status: "completed" or "failed"` + A refusal from the model. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `refusal: string` - - `"completed"` + The refusal explanation from the model. - - `"failed"` + - `type: "refusal"` - - `type: "apply_patch_call_output"` + The type of the refusal. Always `refusal`. - The type of the item. Always `apply_patch_call_output`. + - `role: "assistant"` - - `agent: optional object { agent_name }` + The role of the output message. Always `assistant`. - The agent that produced this item. + - `status: "in_progress" or "completed" or "incomplete"` - - `agent_name: string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The canonical name of the agent that produced this item. + - `"in_progress"` - - `caller: optional object { type } or object { caller_id, type }` + - `"completed"` - The execution context that produced this tool call. + - `"incomplete"` - - `direct: object { type }` + - `type: "message"` - - `program: object { caller_id, type }` + The type of the output message. Always `message`. - - `caller_id: string` + - `agent: optional object { agent_name }` - The call ID of the program item that produced this tool call. + The agent that produced this item. - - `type: "program"` + - `agent_name: string` - - `created_by: optional string` + The canonical name of the agent that produced this item. - The ID of the entity that created this tool call output. + - `phase: optional "commentary" or "final_answer"` - - `output: optional string` + 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. - Optional textual output returned by the apply patch tool. + - `"commentary"` - - `mcp_call: object { id, arguments, name, 7 more }` + - `"final_answer"` - An invocation of a tool on an MCP server. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` - The unique ID of the tool call. + The unique ID of the file search tool call. - - `arguments: string` + - `queries: array of string` - A JSON string of the arguments passed to the tool. + The queries used to search for files. - - `name: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The name of the tool that was run. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `server_label: string` + - `"in_progress"` - The label of the MCP server running the tool. + - `"searching"` - - `type: "mcp_call"` + - `"completed"` - The type of the item. Always `mcp_call`. + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. - `agent: optional object { agent_name }` @@ -111141,2072 +122955,2028 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - 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. + The results of the file search tool call. - - `error: optional string` + - `attributes: optional map[string or number or boolean]` - The error from the tool call, if any. + 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. - - `output: optional string` + - `union_member_0: string` - The output from the tool call. + - `union_member_1: number` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `union_member_2: boolean` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `file_id: optional string` - - `"in_progress"` + The unique ID of the file. - - `"completed"` + - `filename: optional string` - - `"incomplete"` + The name of the file. - - `"calling"` + - `score: optional number` - - `"failed"` + The relevance score of the file - a value between 0 and 1. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `text: optional string` - A list of tools available on an MCP server. + The text that was retrieved from the file. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` - The unique ID of the list. + The unique ID of the computer call. - - `server_label: string` + - `call_id: string` - The label of the MCP server. + An identifier used when responding to the tool call with output. - - `tools: array of object { input_schema, name, annotations, description }` + - `pending_safety_checks: array of object { id, code, message }` - The tools available on the server. + The pending safety checks for the computer call. - - `input_schema: unknown` + - `id: string` - The JSON schema describing the tool's input. + The ID of the pending safety check. - - `name: string` + - `code: optional string` - The name of the tool. + The type of the pending safety check. - - `annotations: optional unknown` + - `message: optional string` - Additional annotations about the tool. + Details about the pending safety check. - - `description: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The description of the tool. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "mcp_list_tools"` + - `"in_progress"` - The type of the item. Always `mcp_list_tools`. + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that produced this item. + - `type: "computer_call"` - - `agent_name: string` + The type of the computer call. Always `computer_call`. - The canonical name of the agent that produced this item. + - `"computer_call"` - - `error: optional string` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - Error message if the server could not list tools. + A click action. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `click: object { button, type, x, 2 more }` - A request for human approval of a tool invocation. + A click action. - - `id: string` + - `button: "left" or "right" or "wheel" or 2 more` - The unique ID of the approval request. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `arguments: string` + - `"left"` - A JSON string of arguments for the tool. + - `"right"` - - `name: string` + - `"wheel"` - The name of the tool to run. + - `"back"` - - `server_label: string` + - `"forward"` - The label of the MCP server making the request. + - `type: "click"` - - `type: "mcp_approval_request"` + Specifies the event type. For a click action, this property is always `click`. - The type of the item. Always `mcp_approval_request`. + - `x: number` - - `agent: optional object { agent_name }` + The x-coordinate where the click occurred. - The agent that produced this item. + - `y: number` - - `agent_name: string` + The y-coordinate where the click occurred. - The canonical name of the agent that produced this item. + - `keys: optional array of string` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + The keys being held while clicking. - A response to an MCP approval request. + - `double_click: object { keys, type, x, y }` - - `id: string` + A double click action. - The unique ID of the approval response + - `keys: array of string` - - `approval_request_id: string` + The keys being held while double-clicking. - The ID of the approval request being answered. + - `type: "double_click"` - - `approve: boolean` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Whether the request was approved. + - `x: number` - - `type: "mcp_approval_response"` + The x-coordinate where the double click occurred. - The type of the item. Always `mcp_approval_response`. + - `y: number` - - `agent: optional object { agent_name }` + The y-coordinate where the double click occurred. - The agent that produced this item. + - `drag: object { path, type, keys }` - - `agent_name: string` + A drag action. - The canonical name of the agent that produced this item. + - `path: array of object { x, y }` - - `reason: optional string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - Optional reason for the decision. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `x: number` - A call to a custom tool created by the model. + The x-coordinate. - - `call_id: string` + - `y: number` - An identifier used to map this custom tool call to a tool call output. + The y-coordinate. - - `input: string` + - `type: "drag"` - The input for the custom tool call generated by the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `name: string` + - `keys: optional array of string` - The name of the custom tool being called. + The keys being held while dragging the mouse. - - `type: "custom_tool_call"` + - `keypress: object { keys, type }` - The type of the custom tool call. Always `custom_tool_call`. + A collection of keypresses the model would like to perform. - - `id: optional string` + - `keys: array of string` - The unique ID of the custom tool call in the OpenAI platform. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `agent: optional object { agent_name }` + - `type: "keypress"` - The agent that produced this item. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `caller: optional object { type } or object { caller_id, type }` + - `move: object { type, x, y, keys }` - The execution context that produced this tool call. + A mouse move action. - - `namespace: optional string` + - `type: "move"` - The namespace of the custom tool being called. + Specifies the event type. For a move action, this property is always set to `move`. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `x: number` - The output of a custom tool call from your code, being sent back to the model. + The x-coordinate to move to. - - `id: string` + - `y: number` - The unique ID of the custom tool call output item. + The y-coordinate to move to. - - `status: "in_progress" or "completed" or "incomplete"` + - `keys: optional array of string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The keys being held while moving the mouse. - - `"in_progress"` + - `screenshot: object { type }` - - `"completed"` + A screenshot action. + + - `scroll: object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. - - `"incomplete"` + - `scroll_x: number` - - `created_by: optional string` + The horizontal scroll distance. - The identifier of the actor that created the item. + - `scroll_y: number` - - `parallel_tool_calls: boolean` + The vertical scroll distance. - Whether to allow the model to run tool calls in parallel. + - `type: "scroll"` - - `temperature: number` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `x: number` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The x-coordinate where the scroll occurred. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `y: number` - - `beta_tool_choice_options: "none" or "auto" or "required"` + The y-coordinate where the scroll occurred. - Controls which (if any) tool is called by the model. + - `keys: optional array of string` - `none` means the model will not call any tool and instead generates a message. + The keys being held while scrolling. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `type: object { text, type }` - `required` means the model must call one or more tools. + An action to type in text. - - `"none"` + - `text: string` - - `"auto"` + The text to type. - - `"required"` + - `type: "type"` - - `beta_tool_choice_allowed: object { mode, tools, type }` + Specifies the event type. For a type action, this property is always set to `type`. - Constrains the tools available to the model to a pre-defined set. + - `wait: object { type }` - - `mode: "auto" or "required"` + A wait action. - Constrains the tools available to the model to a pre-defined set. + - `actions: optional array of BetaComputerAction` - `auto` allows the model to pick from among the allowed tools and generate a - message. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `required` requires the model to call one or more of the allowed tools. + - `click: object { button, type, x, 2 more }` - - `"auto"` + A click action. - - `"required"` + - `double_click: object { keys, type, x, y }` - - `tools: array of map[unknown]` + A double click action. - A list of tool definitions that the model should be allowed to call. + - `drag: object { path, type, keys }` - For the Responses API, the list of tool definitions might look like: + A drag action. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `keypress: object { keys, type }` - - `type: "allowed_tools"` + A collection of keypresses the model would like to perform. - Allowed tool configuration type. Always `allowed_tools`. + - `move: object { type, x, y, keys }` - - `beta_tool_choice_types: object { type }` + A mouse move action. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `screenshot: object { type }` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + A screenshot action. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - Allowed values are: + A scroll action. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `type: object { text, type }` - - `"file_search"` + An action to type in text. - - `"web_search_preview"` + - `wait: object { type }` - - `"computer"` + A wait action. - - `"computer_use_preview"` + - `agent: optional object { agent_name }` - - `"computer_use"` + The agent that produced this item. - - `"web_search_preview_2025_03_11"` + - `agent_name: string` - - `"image_generation"` + The canonical name of the agent that produced this item. - - `"code_interpreter"` + - `computer_call_output: object { call_id, output, type, 4 more }` - - `beta_tool_choice_function: object { name, type }` + The output of a computer tool call. - Use this option to force the model to call a specific function. + - `call_id: string` - - `name: string` + The ID of the computer tool call that produced the output. - The name of the function to call. + - `output: object { type, file_id, image_url }` - - `type: "function"` + A computer screenshot image used with the computer use tool. - For function calling, the type is always `function`. + - `type: "computer_screenshot"` - - `beta_tool_choice_mcp: object { server_label, type, name }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `file_id: optional string` - - `server_label: string` + The identifier of an uploaded file that contains the screenshot. - The label of the MCP server to use. + - `image_url: optional string` - - `type: "mcp"` + The URL of the screenshot image. - For MCP tools, the type is always `mcp`. + - `type: "computer_call_output"` - - `name: optional string` + The type of the computer tool call output. Always `computer_call_output`. - The name of the tool to call on the server. + - `id: optional string` - - `beta_tool_choice_custom: object { name, type }` + The ID of the computer tool call output. - Use this option to force the model to call a specific custom tool. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `name: string` + The safety checks reported by the API that have been acknowledged by the developer. - The name of the custom tool to call. + - `id: string` - - `type: "custom"` + The ID of the pending safety check. - For custom tool calling, the type is always `custom`. + - `code: optional string` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + The type of the pending safety check. - - `beta_tool_choice_apply_patch: object { type }` + - `message: optional string` - Forces the model to call the apply_patch tool when executing a tool call. + Details about the pending safety check. - - `type: "apply_patch"` + - `agent: optional object { agent_name }` - The tool to call. Always `apply_patch`. + The agent that produced this item. - - `beta_tool_choice_shell: object { type }` + - `agent_name: string` - Forces the model to call the shell tool when a tool call is required. + The canonical name of the agent that produced this item. - - `type: "shell"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The tool to call. Always `shell`. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `tools: array of BetaTool` + - `"in_progress"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `"completed"` - We support the following categories of tools: + - `"incomplete"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + 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. - 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). + - `id: string` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The unique ID of the web search tool call. - 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). + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `beta_computer_tool: object { type }` + 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). - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `search: object { type, queries, query, sources }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + Action type "search" - Performs a web search query. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "search"` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The action type. - 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). + - `queries: optional array of string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The search queries. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `query: optional string` - - `code_interpreter: object { container, type, allowed_callers }` + The search query. - A tool that runs Python code to help generate a response to a prompt. + - `sources: optional array of object { type, url }` - - `programmatic_tool_calling: object { type }` + The sources used in the search. - - `image_generation: object { type, action, background, 9 more }` + - `type: "url"` - A tool that generates images using the GPT image models. + The type of source. Always `url`. - - `local_shell: object { type }` + - `url: string` - A tool that allows the model to execute shell commands in a local environment. + The URL of the source. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `open_page: object { type, url }` - A tool that allows the model to execute shell commands. + Action type "open_page" - Opens a specific URL from search results. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `type: "open_page"` - 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) + The action type. - - `beta_namespace_tool: object { description, name, tools, type }` + - `url: optional string` - Groups function/custom tools under a shared namespace. + The URL opened by the model. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `find_in_page: object { pattern, type, url }` - Hosted or BYOT tool search configuration for deferred tools. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `pattern: string` - 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). + The pattern or text to search for within the page. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `type: "find_in_page"` - Allows the assistant to create, delete, or update files using unified diffs. + The action type. - - `top_p: number` + - `url: string` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The URL of the page searched for the pattern. - We generally recommend altering this or `temperature` but not both. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `background: optional boolean` + The status of the web search tool call. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"in_progress"` - - `completed_at: optional number` + - `"searching"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `"completed"` - - `conversation: optional object { id }` + - `"failed"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `type: "web_search_call"` - - `id: string` + The type of the web search tool call. Always `web_search_call`. - The unique ID of the conversation that this response was associated with. + - `agent: optional object { agent_name }` - - `max_output_tokens: optional number` + The agent that produced this item. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `agent_name: string` - - `max_tool_calls: optional number` + The canonical name of the agent that produced this item. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `moderation: optional object { input, output }` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - Moderation results for the response input and output, if moderated completions were requested. + - `arguments: string` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + A JSON string of the arguments to pass to the function. - Moderation for the response input. + - `call_id: string` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + The unique ID of the function tool call generated by the model. - A moderation result produced for the response input or output. + - `name: string` - - `categories: map[boolean]` + The name of the function to run. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `type: "function_call"` - - `category_applied_input_types: map[array of "text" or "image"]` + The type of the function tool call. Always `function_call`. - Which modalities of input are reflected by the score for each category. + - `id: optional string` - - `"text"` + The unique ID of the function tool call. - - `"image"` + - `agent: optional object { agent_name }` - - `category_scores: map[number]` + The agent that produced this item. - A dictionary of moderation categories to scores. + - `agent_name: string` - - `flagged: boolean` + The canonical name of the agent that produced this item. - A boolean indicating whether the content was flagged by any category. + - `caller: optional object { type } or object { caller_id, type }` - - `model: string` + The execution context that produced this tool call. - The moderation model that produced this result. + - `direct: object { type }` - - `type: "moderation_result"` + - `program: object { caller_id, type }` - The object type, which was always `moderation_result` for successful moderation results. + - `caller_id: string` - - `error: object { code, message, type }` + The call ID of the program item that produced this tool call. - An error produced while attempting moderation for the response input or output. + - `type: "program"` - - `code: string` + - `namespace: optional string` - The error code. + The namespace of the function to run. - - `message: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The error message. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "error"` + - `"in_progress"` - The object type, which was always `error` for moderation failures. + - `"completed"` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"incomplete"` - Moderation for the response output. + - `function_call_output: object { call_id, output, type, 4 more }` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + The output of a function tool call. - A moderation result produced for the response input or output. + - `call_id: string` - - `categories: map[boolean]` + The unique ID of the function tool call generated by the model. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `output: string or BetaResponseFunctionCallOutputItemList` - - `category_applied_input_types: map[array of "text" or "image"]` + Text, image, or file output of the function tool call. - Which modalities of input are reflected by the score for each category. + - `union_member_0: string` - - `"text"` + A JSON string of the output of the function tool call. - - `"image"` + - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` - - `category_scores: map[number]` + An array of content outputs (text, image, file) for the function tool call. - A dictionary of moderation categories to scores. + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `flagged: boolean` + A text input to the model. - A boolean indicating whether the content was flagged by any category. + - `text: string` - - `model: string` + The text input to the model. - The moderation model that produced this result. + - `type: "input_text"` - - `type: "moderation_result"` + The type of the input item. Always `input_text`. - The object type, which was always `moderation_result` for successful moderation results. + - `prompt_cache_breakpoint: optional object { mode }` - - `error: object { code, message, type }` + 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. - An error produced while attempting moderation for the response input or output. + - `mode: "explicit"` - - `code: string` + The breakpoint mode. Always `explicit`. - The error code. + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - - `message: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - The error message. + - `type: "input_image"` - - `type: "error"` + The type of the input item. Always `input_image`. - The object type, which was always `error` for moderation failures. + - `detail: optional "low" or "high" or "auto" or "original"` - - `previous_response_id: optional string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - 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`. + - `"low"` - - `prompt: optional object { id, variables, version }` + - `"high"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `"auto"` - - `id: string` + - `"original"` - The unique identifier of the prompt template to use. + - `file_id: optional string` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + The ID of the file to be sent to the model. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `image_url: optional string` - - `union_member_0: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `prompt_cache_breakpoint: optional object { mode }` - A text input to the model. + 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. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The breakpoint mode. Always `explicit`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` A file input to the model. - - `version: optional string` + - `type: "input_file"` - Optional version of the prompt template. + The type of the input item. Always `input_file`. - - `prompt_cache_key: optional string` + - `detail: optional "auto" or "low" or "high"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + 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`. - - `prompt_cache_options: optional object { mode, ttl }` + - `"auto"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"low"` - - `mode: "implicit" or "explicit"` + - `"high"` - Whether implicit prompt-cache breakpoints were enabled. + - `file_data: optional string` - - `"implicit"` + The base64-encoded data of the file to be sent to the model. - - `"explicit"` + - `file_id: optional string` - - `ttl: "30m"` + The ID of the file to be sent to the model. - The minimum lifetime applied to each cache breakpoint. + - `file_url: optional string` - - `"30m"` + The URL of the file to be sent to the model. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `filename: optional string` - Deprecated. Use `prompt_cache_options.ttl` instead. + The name of the file to be sent to the model. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `prompt_cache_breakpoint: optional object { mode }` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + 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. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `mode: "explicit"` - - `"in_memory"` + The breakpoint mode. Always `explicit`. - - `"24h"` + - `type: "function_call_output"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The type of the function tool call output. Always `function_call_output`. - **gpt-5 and o-series models only** + - `id: optional string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The unique ID of the function tool call output. Populated when this item is returned via API. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `agent: optional object { agent_name }` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `"current_turn"` + The canonical name of the agent that produced this item. - - `"all_turns"` + - `caller: optional object { type } or object { caller_id, type }` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The execution context that produced this tool call. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `direct: object { type }` - - `"none"` + - `program: object { caller_id, type }` - - `"minimal"` + - `caller_id: string` - - `"low"` + The call ID of the program item that produced this tool call. - - `"medium"` + - `type: "program"` - - `"high"` + The caller type. Always `program`. - - `"xhigh"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"max"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `"in_progress"` - **Deprecated:** use `summary` instead. + - `"completed"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"incomplete"` - - `"auto"` + - `agent_message: object { author, content, recipient, 3 more }` - - `"concise"` + A message routed between agents. - - `"detailed"` + - `author: string` - - `mode: optional string or "standard" or "pro"` + The sending agent identity. - Controls the reasoning execution mode for the request. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - When returned on a response, this is the effective execution mode. + Plaintext, image, or encrypted content sent between agents. - - `"standard"` + - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` - - `"pro"` + A text input to the model. - - `summary: optional "auto" or "concise" or "detailed"` + - `text: string` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The text input to the model. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `type: "input_text"` - - `"auto"` + The type of the input item. Always `input_text`. - - `"concise"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"detailed"` + 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. - - `safety_identifier: optional string` + - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `type: "input_image"` - Specifies the processing type used for serving the request. + The type of the input item. Always `input_image`. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `detail: optional "low" or "high" or "auto" or "original"` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"auto"` + - `file_id: optional string` - - `"default"` + The ID of the file to be sent to the model. - - `"flex"` + - `image_url: optional string` - - `"scale"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"priority"` + - `prompt_cache_breakpoint: optional object { mode }` - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + 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. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `encrypted_content: object { encrypted_content, type }` - - `"completed"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"failed"` + - `encrypted_content: string` - - `"in_progress"` + Opaque encrypted content. - - `"cancelled"` + - `type: "encrypted_content"` - - `"queued"` + The type of the input item. Always `encrypted_content`. - - `"incomplete"` + - `recipient: string` - - `text: optional object { format, verbosity }` + The destination agent identity. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `type: "agent_message"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The item type. Always `agent_message`. - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `id: optional string` - An object specifying the format that the model must output. + The unique ID of this agent message item. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `agent: optional object { agent_name }` - The default format is `{ "type": "text" }` with no additional options. + The agent that produced this item. - **Not recommended for gpt-4o and newer models:** + - `agent_name: string` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The canonical name of the agent that produced this item. - - `text: object { type }` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - Default response format. Used to generate text responses. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + The multi-agent action that was executed. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"spawn_agent"` - - `name: string` + - `"interrupt_agent"` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `"list_agents"` - - `schema: map[unknown]` + - `"send_message"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"followup_task"` - - `type: "json_schema"` + - `"wait_agent"` - The type of response format being defined. Always `json_schema`. + - `arguments: string` - - `description: optional string` + The action arguments as a JSON string. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `call_id: string` - - `strict: optional boolean` + The unique ID linking this call to its output. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "multi_agent_call"` - - `json_object: object { type }` + The item type. Always `multi_agent_call`. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `id: optional string` - - `verbosity: optional "low" or "medium" or "high"` + The unique ID of this multi-agent call. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `"medium"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `top_logprobs: optional number` + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `truncation: optional "auto" or "disabled"` + The multi-agent action that produced this result. - The truncation strategy to use for the model response. + - `"spawn_agent"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"interrupt_agent"` - - `"auto"` + - `"list_agents"` - - `"disabled"` + - `"send_message"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `"followup_task"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `"wait_agent"` - - `input_tokens: number` + - `call_id: string` - The number of input tokens. + The unique ID of the multi-agent call. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `output: array of object { text, type, annotations }` - A detailed breakdown of the input tokens. + Text output returned by the multi-agent action. - - `cache_write_tokens: number` + - `text: string` - The number of input tokens that were written to the cache. + The text content. - - `cached_tokens: number` + - `type: "output_text"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The content type. Always `output_text`. - - `output_tokens: number` + - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - The number of output tokens. + Citations associated with the text content. - - `output_tokens_details: object { reasoning_tokens }` + - `union_member_0: array of object { file_id, filename, index, type }` - A detailed breakdown of the output tokens. + - `file_id: string` - - `reasoning_tokens: number` + The ID of the file. - The number of reasoning tokens. + - `filename: string` - - `total_tokens: number` + The filename of the file cited. - The total number of tokens used. + - `index: number` - - `user: optional string` + The index of the file in the list of files. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `type: "file_citation"` - - `sequence_number: number` + The citation type. Always `file_citation`. - The sequence number for this event. + - `union_member_1: array of object { end_index, start_index, title, 2 more }` - - `type: "response.queued"` + - `end_index: number` - The type of the event. Always 'response.queued'. + The index of the last character of the citation in the message. - - `agent: optional object { agent_name }` + - `start_index: number` - The agent that owns this multi-agent streaming event. + The index of the first character of the citation in the message. - - `agent_name: string` + - `title: string` - The canonical name of the agent that produced this item. + The title of the cited resource. -### Beta Response Reasoning Item + - `type: "url_citation"` -- `beta_response_reasoning_item: object { id, summary, type, 4 more }` + The citation type. Always `url_citation`. - 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). + - `url: string` - - `id: string` + The URL of the cited resource. - The unique identifier of the reasoning content. + - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` - - `summary: array of object { text, type }` + - `container_id: string` - Reasoning summary content. + The ID of the container. - - `text: string` + - `end_index: number` - A summary of the reasoning output from the model so far. + The index of the last character of the citation in the message. - - `type: "summary_text"` + - `file_id: string` - The type of the object. Always `summary_text`. + The ID of the container file. - - `type: "reasoning"` + - `filename: string` - The type of the object. Always `reasoning`. + The filename of the container file cited. - - `agent: optional object { agent_name }` + - `start_index: number` - The agent that produced this item. + The index of the first character of the citation in the message. - - `agent_name: string` + - `type: "container_file_citation"` - The canonical name of the agent that produced this item. + The citation type. Always `container_file_citation`. - - `content: optional array of object { text, type }` + - `type: "multi_agent_call_output"` - Reasoning text content. + The item type. Always `multi_agent_call_output`. - - `text: string` + - `id: optional string` - The reasoning text from the model. + The unique ID of this multi-agent call output. - - `type: "reasoning_text"` + - `agent: optional object { agent_name }` - The type of the reasoning text. Always `reasoning_text`. + The agent that produced this item. - - `encrypted_content: optional string` + - `agent_name: string` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `tool_search_call: object { arguments, type, id, 4 more }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `arguments: unknown` - - `"in_progress"` + The arguments supplied to the tool search call. - - `"completed"` + - `type: "tool_search_call"` - - `"incomplete"` + The item type. Always `tool_search_call`. -### Beta Response Reasoning Summary Part Added Event + - `id: optional string` -- `beta_response_reasoning_summary_part_added_event: object { item_id, output_index, part, 4 more }` + The unique ID of this tool search call. - Emitted when a new reasoning summary part is added. + - `agent: optional object { agent_name }` - - `item_id: string` + The agent that produced this item. - The ID of the item this summary part is associated with. + - `agent_name: string` - - `output_index: number` + The canonical name of the agent that produced this item. - The index of the output item this summary part is associated with. + - `call_id: optional string` - - `part: object { text, type }` + The unique ID of the tool search call generated by the model. - The summary part that was added. + - `execution: optional "server" or "client"` - - `text: string` + Whether tool search was executed by the server or by the client. - The text of the summary part. + - `"server"` - - `type: "summary_text"` + - `"client"` - The type of the summary part. Always `summary_text`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `sequence_number: number` + The status of the tool search call. - The sequence number of this event. + - `"in_progress"` - - `summary_index: number` + - `"completed"` - The index of the summary part within the reasoning summary. + - `"incomplete"` - - `type: "response.reasoning_summary_part.added"` + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - The type of the event. Always `response.reasoning_summary_part.added`. + - `tools: array of BetaTool` - - `agent: optional object { agent_name }` + The loaded tool definitions returned by the tool search output. - The agent that owns this multi-agent streaming event. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `agent_name: string` + 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). - The canonical name of the agent that produced this item. + - `name: string` -### Beta Response Reasoning Summary Part Done Event + The name of the function to call. -- `beta_response_reasoning_summary_part_done_event: object { item_id, output_index, part, 5 more }` + - `parameters: map[unknown]` - Emitted when a reasoning summary part is completed. + A JSON schema object describing the parameters of the function. - - `item_id: string` + - `strict: boolean` - The ID of the item this summary part is associated with. + Whether strict parameter validation is enforced for this function tool. - - `output_index: number` + - `type: "function"` - The index of the output item this summary part is associated with. + The type of the function tool. Always `function`. - - `part: object { text, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The completed summary part. + The tool invocation context(s). - - `text: string` + - `"direct"` - The text of the summary part. + - `"programmatic"` - - `type: "summary_text"` + - `defer_loading: optional boolean` - The type of the summary part. Always `summary_text`. + Whether this function is deferred and loaded via tool search. - - `sequence_number: number` + - `description: optional string` - The sequence number of this event. + A description of the function. Used by the model to determine whether or not to call the function. - - `summary_index: number` + - `output_schema: optional map[unknown]` - The index of the summary part within the reasoning summary. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `type: "response.reasoning_summary_part.done"` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The type of the event. Always `response.reasoning_summary_part.done`. + 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). - - `agent: optional object { agent_name }` + - `type: "file_search"` - The agent that owns this multi-agent streaming event. + The type of the file search tool. Always `file_search`. - - `agent_name: string` + - `vector_store_ids: array of string` - The canonical name of the agent that produced this item. + The IDs of the vector stores to search. - - `status: optional "incomplete"` + - `filters: optional object { key, type, value } or object { filters, type }` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + A filter to apply. - - `"incomplete"` + - `Comparison Filter: object { key, type, value }` -### Beta Response Reasoning Summary Text Delta Event + A filter used to compare a specified attribute key to a given value using a defined comparison operation. -- `beta_response_reasoning_summary_text_delta_event: object { delta, item_id, output_index, 4 more }` + - `key: string` - Emitted when a delta is added to a reasoning summary text. + The key to compare against the value. - - `delta: string` + - `type: "eq" or "ne" or "gt" or 5 more` - The text delta that was added to the summary. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `item_id: string` + - `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 - The ID of the item this summary text delta is associated with. + - `"eq"` - - `output_index: number` + - `"ne"` - The index of the output item this summary text delta is associated with. + - `"gt"` - - `sequence_number: number` + - `"gte"` - The sequence number of this event. + - `"lt"` - - `summary_index: number` + - `"lte"` - The index of the summary part within the reasoning summary. + - `"in"` - - `type: "response.reasoning_summary_text.delta"` + - `"nin"` - The type of the event. Always `response.reasoning_summary_text.delta`. + - `value: string or number or boolean or array of string or number` - - `agent: optional object { agent_name }` + The value to compare against the attribute key; supports string, number, or boolean types. - The agent that owns this multi-agent streaming event. + - `union_member_0: string` - - `agent_name: string` + - `union_member_1: number` - The canonical name of the agent that produced this item. + - `union_member_2: boolean` -### Beta Response Reasoning Summary Text Done Event + - `union_member_3: array of string or number` -- `beta_response_reasoning_summary_text_done_event: object { item_id, output_index, sequence_number, 4 more }` + - `union_member_0: string` - Emitted when a reasoning summary text is completed. + - `union_member_1: number` - - `item_id: string` + - `Compound Filter: object { filters, type }` - The ID of the item this summary text is associated with. + Combine multiple filters using `and` or `or`. - - `output_index: number` + - `filters: array of object { key, type, value } or unknown` - The index of the output item this summary text is associated with. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `sequence_number: number` + - `Comparison Filter: object { key, type, value }` - The sequence number of this event. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `summary_index: number` + - `key: string` - The index of the summary part within the reasoning summary. + The key to compare against the value. - - `text: string` + - `type: "eq" or "ne" or "gt" or 5 more` - The full text of the completed reasoning summary. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "response.reasoning_summary_text.done"` + - `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 - The type of the event. Always `response.reasoning_summary_text.done`. + - `"eq"` - - `agent: optional object { agent_name }` + - `"ne"` - The agent that owns this multi-agent streaming event. + - `"gt"` - - `agent_name: string` + - `"gte"` - The canonical name of the agent that produced this item. + - `"lt"` -### Beta Response Reasoning Text Delta Event + - `"lte"` -- `beta_response_reasoning_text_delta_event: object { content_index, delta, item_id, 4 more }` + - `"in"` - Emitted when a delta is added to a reasoning text. + - `"nin"` - - `content_index: number` + - `value: string or number or boolean or array of string or number` - The index of the reasoning content part this delta is associated with. + The value to compare against the attribute key; supports string, number, or boolean types. - - `delta: string` + - `union_member_0: string` - The text delta that was added to the reasoning content. + - `union_member_1: number` - - `item_id: string` + - `union_member_2: boolean` - The ID of the item this reasoning text delta is associated with. + - `union_member_3: array of string or number` - - `output_index: number` + - `union_member_0: string` - The index of the output item this reasoning text delta is associated with. + - `union_member_1: number` - - `sequence_number: number` + - `union_member_1: unknown` - The sequence number of this event. + - `type: "and" or "or"` - - `type: "response.reasoning_text.delta"` + Type of operation: `and` or `or`. - The type of the event. Always `response.reasoning_text.delta`. + - `"and"` - - `agent: optional object { agent_name }` + - `"or"` - The agent that owns this multi-agent streaming event. + - `max_num_results: optional number` - - `agent_name: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The canonical name of the agent that produced this item. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` -### Beta Response Reasoning Text Done Event + Ranking options for search. -- `beta_response_reasoning_text_done_event: object { content_index, item_id, output_index, 4 more }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Emitted when a reasoning text is completed. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `content_index: number` + - `embedding_weight: number` - The index of the reasoning content part. + The weight of the embedding in the reciprocal ranking fusion. - - `item_id: string` + - `text_weight: number` - The ID of the item this reasoning text is associated with. + The weight of the text in the reciprocal ranking fusion. - - `output_index: number` + - `ranker: optional "auto" or "default-2024-11-15"` - The index of the output item this reasoning text is associated with. + The ranker to use for the file search. - - `sequence_number: number` + - `"auto"` - The sequence number of this event. + - `"default-2024-11-15"` - - `text: string` + - `score_threshold: optional number` - The full text of the completed reasoning content. + 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. - - `type: "response.reasoning_text.done"` + - `beta_computer_tool: object { type }` - The type of the event. Always `response.reasoning_text.done`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent: optional object { agent_name }` + - `type: "computer"` - The agent that owns this multi-agent streaming event. + The type of the computer tool. Always `computer`. - - `agent_name: string` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -### Beta Response Refusal Delta Event + - `display_height: number` -- `beta_response_refusal_delta_event: object { content_index, delta, item_id, 4 more }` + The height of the computer display. - Emitted when there is a partial refusal text. + - `display_width: number` - - `content_index: number` + The width of the computer display. - The index of the content part that the refusal text is added to. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `delta: string` + The type of computer environment to control. - The refusal text that is added. + - `"windows"` - - `item_id: string` + - `"mac"` - The ID of the output item that the refusal text is added to. + - `"linux"` - - `output_index: number` + - `"ubuntu"` - The index of the output item that the refusal text is added to. + - `"browser"` - - `sequence_number: number` + - `type: "computer_use_preview"` - The sequence number of this event. + The type of the computer use tool. Always `computer_use_preview`. - - `type: "response.refusal.delta"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the event. Always `response.refusal.delta`. + 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). - - `agent: optional object { agent_name }` + - `type: "web_search" or "web_search_2025_08_26"` - The agent that owns this multi-agent streaming event. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `agent_name: string` + - `"web_search"` - The canonical name of the agent that produced this item. + - `"web_search_2025_08_26"` -### Beta Response Refusal Done Event + - `filters: optional object { allowed_domains }` -- `beta_response_refusal_done_event: object { content_index, item_id, output_index, 4 more }` + Filters for the search. - Emitted when refusal text is finalized. + - `allowed_domains: optional array of string` - - `content_index: number` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The index of the content part that the refusal text is finalized. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `item_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The ID of the output item that the refusal text is finalized. + 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. - - `output_index: number` + - `"low"` - The index of the output item that the refusal text is finalized. + - `"medium"` - - `refusal: string` + - `"high"` - The refusal text that is finalized. + - `user_location: optional object { city, country, region, 2 more }` - - `sequence_number: number` + The approximate location of the user. - The sequence number of this event. + - `city: optional string` - - `type: "response.refusal.done"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the event. Always `response.refusal.done`. + - `country: optional string` - - `agent: optional object { agent_name }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The agent that owns this multi-agent streaming event. + - `region: optional string` - - `agent_name: string` + Free text input for the region of the user, e.g. `California`. - The canonical name of the agent that produced this item. + - `timezone: optional string` -### Beta Response Status + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. -- `beta_response_status: "completed" or "failed" or "in_progress" or 3 more` + - `type: optional "approximate"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The type of location approximation. Always `approximate`. - - `"completed"` + - `"approximate"` - - `"failed"` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `"in_progress"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `"cancelled"` + - `server_label: string` - - `"queued"` + A label for this MCP server, used to identify it in tool calls. - - `"incomplete"` + - `type: "mcp"` -### Beta Response Stream Event + The type of the MCP tool. Always `mcp`. -- `beta_response_stream_event: BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 50 more` + - `allowed_callers: optional array of "direct" or "programmatic"` - Emitted when there is a partial audio response. + The tool invocation context(s). - - `beta_response_audio_delta_event: object { delta, sequence_number, type, agent }` + - `"direct"` - Emitted when there is a partial audio response. + - `"programmatic"` - - `delta: string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - A chunk of Base64 encoded response audio bytes. + List of allowed tool names or a filter object. - - `sequence_number: number` + - `MCP allowed tools: array of string` - A sequence number for this chunk of the stream response. + A string array of allowed tool names - - `type: "response.audio.delta"` + - `MCP tool filter: object { read_only, tool_names }` - The type of the event. Always `response.audio.delta`. + A filter object to specify which tools are allowed. - - `agent: optional object { agent_name }` + - `read_only: optional boolean` - The agent that owns this multi-agent streaming event. + 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. - - `agent_name: string` + - `tool_names: optional array of string` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `beta_response_audio_done_event: object { sequence_number, type, agent }` + - `authorization: optional string` - Emitted when the audio response is complete. + 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. - - `sequence_number: number` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The sequence number of the delta. + 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). - - `type: "response.audio.done"` + Currently supported `connector_id` values are: - The type of the event. Always `response.audio.done`. + - 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` - - `agent: optional object { agent_name }` + - `"connector_dropbox"` - The agent that owns this multi-agent streaming event. + - `"connector_gmail"` - - `agent_name: string` + - `"connector_googlecalendar"` - The canonical name of the agent that produced this item. + - `"connector_googledrive"` - - `beta_response_audio_transcript_delta_event: object { delta, sequence_number, type, agent }` + - `"connector_microsoftteams"` - Emitted when there is a partial transcript of audio. + - `"connector_outlookcalendar"` - - `delta: string` + - `"connector_outlookemail"` - The partial transcript of the audio response. + - `"connector_sharepoint"` - - `sequence_number: number` + - `defer_loading: optional boolean` - The sequence number of this event. + Whether this MCP tool is deferred and discovered via tool search. - - `type: "response.audio.transcript.delta"` + - `headers: optional map[string]` - The type of the event. Always `response.audio.transcript.delta`. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `agent: optional object { agent_name }` + - `require_approval: optional object { always, never } or "always" or "never"` - The agent that owns this multi-agent streaming event. + Specify which of the MCP server's tools require approval. - - `agent_name: string` + - `MCP tool approval filter: object { always, never }` - The canonical name of the agent that produced this item. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `beta_response_audio_transcript_done_event: object { sequence_number, type, agent }` + - `always: optional object { read_only, tool_names }` - Emitted when the full audio transcript is completed. + A filter object to specify which tools are allowed. - - `sequence_number: number` + - `read_only: optional boolean` - The sequence number of this event. + 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. - - `type: "response.audio.transcript.done"` + - `tool_names: optional array of string` - The type of the event. Always `response.audio.transcript.done`. + List of allowed tool names. - - `agent: optional object { agent_name }` + - `never: optional object { read_only, tool_names }` - The agent that owns this multi-agent streaming event. + A filter object to specify which tools are allowed. - - `agent_name: string` + - `read_only: optional boolean` - The canonical name of the agent that produced this item. + 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. - - `beta_response_code_interpreter_call_code_delta_event: object { delta, item_id, output_index, 3 more }` + - `tool_names: optional array of string` - Emitted when a partial code snippet is streamed by the code interpreter. + List of allowed tool names. - - `delta: string` + - `MCP tool approval setting: "always" or "never"` - The partial code snippet being streamed by the code interpreter. + 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. - - `item_id: string` + - `"always"` - The unique identifier of the code interpreter tool call item. + - `"never"` - - `output_index: number` + - `server_description: optional string` - The index of the output item in the response for which the code is being streamed. + Optional description of the MCP server, used to provide more context. - - `sequence_number: number` + - `server_url: optional string` - The sequence number of this event, used to order streaming events. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "response.code_interpreter_call_code.delta"` + - `tunnel_id: optional string` - The type of the event. Always `response.code_interpreter_call_code.delta`. + 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. - - `agent: optional object { agent_name }` + - `code_interpreter: object { container, type, allowed_callers }` - The agent that owns this multi-agent streaming event. + A tool that runs Python code to help generate a response to a prompt. - - `agent_name: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The canonical name of the agent that produced this item. + 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. - - `beta_response_code_interpreter_call_code_done_event: object { code, item_id, output_index, 3 more }` + - `union_member_0: string` - Emitted when the code snippet is finalized by the code interpreter. + The container ID. - - `code: string` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - The final code snippet output by the code interpreter. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `item_id: string` + - `type: "auto"` - The unique identifier of the code interpreter tool call item. + Always `auto`. - - `output_index: number` + - `file_ids: optional array of string` - The index of the output item in the response for which the code is finalized. + An optional list of uploaded files to make available to your code. - - `sequence_number: number` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The sequence number of this event, used to order streaming events. + The memory limit for the code interpreter container. - - `type: "response.code_interpreter_call_code.done"` + - `"1g"` - The type of the event. Always `response.code_interpreter_call_code.done`. + - `"4g"` - - `agent: optional object { agent_name }` + - `"16g"` - The agent that owns this multi-agent streaming event. + - `"64g"` - - `agent_name: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The canonical name of the agent that produced this item. + Network access policy for the container. - - `beta_response_code_interpreter_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `beta_container_network_policy_disabled: object { type }` - Emitted when the code interpreter call is completed. + - `type: "disabled"` - - `item_id: string` + Disable outbound network access. Always `disabled`. - The unique identifier of the code interpreter tool call item. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `output_index: number` + - `allowed_domains: array of string` - The index of the output item in the response for which the code interpreter call is completed. + A list of allowed domains when type is `allowlist`. - - `sequence_number: number` + - `type: "allowlist"` - The sequence number of this event, used to order streaming events. + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "response.code_interpreter_call.completed"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The type of the event. Always `response.code_interpreter_call.completed`. + Optional domain-scoped secrets for allowlisted domains. - - `agent: optional object { agent_name }` + - `domain: string` - The agent that owns this multi-agent streaming event. + The domain associated with the secret. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the secret to inject for the domain. - - `beta_response_code_interpreter_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + - `value: string` - Emitted when a code interpreter call is in progress. + The secret value to inject for the domain. - - `item_id: string` + - `type: "code_interpreter"` - The unique identifier of the code interpreter tool call item. + The type of the code interpreter tool. Always `code_interpreter`. - - `output_index: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The index of the output item in the response for which the code interpreter call is in progress. + The tool invocation context(s). - - `sequence_number: number` + - `"direct"` - The sequence number of this event, used to order streaming events. + - `"programmatic"` - - `type: "response.code_interpreter_call.in_progress"` + - `programmatic_tool_calling: object { type }` - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `image_generation: object { type, action, background, 9 more }` - - `agent: optional object { agent_name }` + A tool that generates images using the GPT image models. - The agent that owns this multi-agent streaming event. + - `type: "image_generation"` - - `agent_name: string` + The type of the image generation tool. Always `image_generation`. - The canonical name of the agent that produced this item. + - `action: optional "generate" or "edit" or "auto"` - - `beta_response_code_interpreter_call_interpreting_event: object { item_id, output_index, sequence_number, 2 more }` + Whether to generate a new image or edit an existing image. Default: `auto`. - Emitted when the code interpreter is actively interpreting the code snippet. + - `"generate"` - - `item_id: string` + - `"edit"` - The unique identifier of the code interpreter tool call item. + - `"auto"` - - `output_index: number` + - `background: optional "transparent" or "opaque" or "auto"` - The index of the output item in the response for which the code interpreter is interpreting code. + 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. - - `sequence_number: number` + `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. - The sequence number of this event, used to order streaming events. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `type: "response.code_interpreter_call.interpreting"` + - `"transparent"` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `"opaque"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that owns this multi-agent streaming event. + - `input_fidelity: optional "high" or "low"` - - `agent_name: string` + 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`. - The canonical name of the agent that produced this item. + - `"high"` - - `beta_response_completed_event: object { response, sequence_number, type, agent }` + - `"low"` - Emitted when the model response is complete. + - `input_image_mask: optional object { file_id, image_url }` - - `response: object { id, created_at, error, 31 more }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Properties of the completed response. + - `file_id: optional string` - - `id: string` + File ID for the mask image. - Unique identifier for this Response. + - `image_url: optional string` - - `created_at: number` + Base64-encoded mask image. - Unix timestamp (in seconds) of when this Response was created. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `error: object { code, message }` + The image generation model to use. Default: `gpt-image-1`. - An error object returned when the model fails to generate a Response. + - `"gpt-image-1"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + - `"gpt-image-1-mini"` - The error code for the response. + - `"gpt-image-2"` - - `"server_error"` + - `"gpt-image-2-2026-04-21"` - - `"rate_limit_exceeded"` + - `"gpt-image-1.5"` - - `"invalid_prompt"` + - `"chatgpt-image-latest"` - - `"bio_policy"` + - `moderation: optional "auto" or "low"` - - `"vector_store_timeout"` + Moderation level for the generated image. Default: `auto`. - - `"invalid_image"` + - `"auto"` - - `"invalid_image_format"` + - `"low"` - - `"invalid_base64_image"` + - `output_compression: optional number` - - `"invalid_image_url"` + Compression level for the output image. Default: 100. - - `"image_too_large"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `"image_too_small"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"image_parse_error"` + - `"png"` - - `"image_content_policy_violation"` + - `"webp"` - - `"invalid_image_mode"` + - `"jpeg"` - - `"image_file_too_large"` + - `partial_images: optional number` - - `"unsupported_image_media_type"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"empty_image_file"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"failed_to_download_image"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"image_file_not_found"` + - `"low"` - - `message: string` + - `"medium"` - A human-readable description of the error. + - `"high"` - - `incomplete_details: object { reason }` + - `"auto"` - Details about why the response is incomplete. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `reason: optional "max_output_tokens" or "content_filter"` + 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`. - The reason why the response is incomplete. + - `"1024x1024"` - - `"max_output_tokens"` + - `"1024x1536"` - - `"content_filter"` + - `"1536x1024"` - - `instructions: string or array of BetaResponseInputItem` + - `"auto"` - A system (or developer) message inserted into the model's context. + - `local_shell: object { type }` - When using 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. + A tool that allows the model to execute shell commands in a local environment. - - `union_member_0: string` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - A text input to the model, equivalent to a text input with the - `developer` role. + A tool that allows the model to execute shell commands. - - `Input item list: array of BetaResponseInputItem` + - `type: "shell"` - A list of one or many input items to the model, containing - different content types. + The type of the shell tool. Always `shell`. - - `beta_easy_input_message: object { content, role, phase, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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. + The tool invocation context(s). - - `content: string or BetaResponseInputMessageContentList` + - `"direct"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"programmatic"` - - `Text input: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - A text input to the model. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `type: "container_auto"` - A list of one or many input items to the model, containing different content - types. + Automatically creates a container for this request - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `file_ids: optional array of string` - A text input to the model. + An optional list of uploaded files to make available to your code. - - `text: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The text input to the model. + The memory limit for the container. - - `type: "input_text"` + - `"1g"` - The type of the input item. Always `input_text`. + - `"4g"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"16g"` - 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. + - `"64g"` - - `mode: "explicit"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The breakpoint mode. Always `explicit`. + Network access policy for the container. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `beta_container_network_policy_disabled: object { type }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `detail: "low" or "high" or "auto" or "original"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + An optional list of skills referenced by id or inline data. - - `"low"` + - `beta_skill_reference: object { skill_id, type, version }` - - `"high"` + - `skill_id: string` - - `"auto"` + The ID of the referenced skill. - - `"original"` + - `type: "skill_reference"` - - `type: "input_image"` + References a skill created with the /v1/skills endpoint. - The type of the input item. Always `input_image`. + - `version: optional string` - - `file_id: optional string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The ID of the file to be sent to the model. + - `beta_inline_skill: object { description, name, source, type }` - - `image_url: optional string` + - `description: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The description of the skill. - - `prompt_cache_breakpoint: optional object { mode }` + - `name: string` - 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. + The name of the skill. - - `mode: "explicit"` + - `source: object { data, media_type, type }` - The breakpoint mode. Always `explicit`. + Inline skill payload - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `data: string` - A file input to the model. + Base64-encoded skill zip bundle. - - `type: "input_file"` + - `media_type: "application/zip"` - The type of the input item. Always `input_file`. + The media type of the inline skill payload. Must be `application/zip`. - - `detail: optional "auto" or "low" or "high"` + - `type: "base64"` - 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`. + The type of the inline skill source. Must be `base64`. - - `"auto"` + - `type: "inline"` - - `"low"` + Defines an inline skill for this request. - - `"high"` + - `beta_local_environment: object { type, skills }` - - `file_data: optional string` + - `type: "local"` - The content of the file to be sent to the model. + Use a local computer environment. - - `file_id: optional string` + - `skills: optional array of BetaLocalSkill` - The ID of the file to be sent to the model. + An optional list of skills. - - `file_url: optional string` + - `description: string` - The URL of the file to be sent to the model. + The description of the skill. - - `filename: optional string` + - `name: string` - The name of the file to be sent to the model. + The name of the skill. - - `prompt_cache_breakpoint: optional object { mode }` + - `path: string` - 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. + The path to the directory containing the skill. - - `mode: "explicit"` + - `beta_container_reference: object { container_id, type }` - The breakpoint mode. Always `explicit`. + - `container_id: string` - - `role: "user" or "assistant" or "system" or "developer"` + The ID of the referenced container. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `type: "container_reference"` - - `"user"` + References a container created with the /v1/containers endpoint - - `"assistant"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `"system"` + 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) - - `"developer"` + - `name: string` - - `phase: optional "commentary"` + The name of the custom tool, used to identify it in tool calls. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `type: "custom"` - - `"commentary"` + The type of the custom tool. Always `custom`. - - `type: optional "message"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the message input. Always `message`. + The tool invocation context(s). - - `"message"` + - `"direct"` - - `message: object { content, role, agent, 2 more }` + - `"programmatic"` - 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. + - `defer_loading: optional boolean` - - `content: array of BetaResponseInputContent` + Whether this tool should be deferred and discovered via tool search. - A list of one or many input items to the model, containing different content - types. + - `description: optional string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + Optional description of the custom tool, used to provide more context. - A text input to the model. + - `format: optional object { type } or object { definition, syntax, type }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The input format for the custom tool. Default is unconstrained text. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `text: object { type }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Unconstrained free-form text. - A file input to the model. + - `grammar: object { definition, syntax, type }` - - `role: "user" or "system" or "developer"` + A grammar defined by the user. - The role of the message input. One of `user`, `system`, or `developer`. + - `definition: string` - - `"user"` + The grammar definition. - - `"system"` + - `syntax: "lark" or "regex"` - - `"developer"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `agent: optional object { agent_name }` + - `"lark"` - The agent that produced this item. + - `"regex"` - - `agent_name: string` + - `type: "grammar"` - The canonical name of the agent that produced this item. + Grammar format. Always `grammar`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `beta_namespace_tool: object { description, name, tools, type }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Groups function/custom tools under a shared namespace. - - `"in_progress"` + - `description: string` - - `"completed"` + A description of the namespace shown to the model. - - `"incomplete"` + - `name: string` - - `type: optional "message"` + The namespace name used in tool calls (for example, `crm`). - The type of the message input. Always set to `message`. + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - - `"message"` + The function/custom tools available inside this namespace. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `function: object { name, type, allowed_callers, 5 more }` - An output message from the model. + - `name: string` - - `id: string` + - `type: "function"` - The unique ID of the output message. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The tool invocation context(s). - The content of the output message. + - `"direct"` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"programmatic"` - A text output from the model. + - `defer_loading: optional boolean` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + Whether this function should be deferred and discovered via tool search. - The annotations of the text output. + - `description: optional string` - - `file_citation: object { file_id, filename, index, type }` + - `output_schema: optional map[unknown]` - A citation to a file. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `file_id: string` + - `parameters: optional unknown` - The ID of the file. + - `strict: optional boolean` - - `filename: string` + 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. - The filename of the file cited. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `index: number` + 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) - The index of the file in the list of files. + - `name: string` - - `type: "file_citation"` + The name of the custom tool, used to identify it in tool calls. - The type of the file citation. Always `file_citation`. + - `type: "custom"` - - `url_citation: object { end_index, start_index, title, 2 more }` + The type of the custom tool. Always `custom`. - A citation for a web resource used to generate a model response. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `end_index: number` + The tool invocation context(s). - The index of the last character of the URL citation in the message. + - `defer_loading: optional boolean` - - `start_index: number` + Whether this tool should be deferred and discovered via tool search. - The index of the first character of the URL citation in the message. + - `description: optional string` - - `title: string` + Optional description of the custom tool, used to provide more context. - The title of the web resource. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "url_citation"` + The input format for the custom tool. Default is unconstrained text. - The type of the URL citation. Always `url_citation`. + - `type: "namespace"` - - `url: string` + The type of the tool. Always `namespace`. - The URL of the web resource. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + Hosted or BYOT tool search configuration for deferred tools. - A citation for a container file used to generate a model response. + - `type: "tool_search"` - - `container_id: string` + The type of the tool. Always `tool_search`. - The ID of the container file. + - `description: optional string` - - `end_index: number` + Description shown to the model for a client-executed tool search tool. - The index of the last character of the container file citation in the message. + - `execution: optional "server" or "client"` - - `file_id: string` + Whether tool search is executed by the server or by the client. - The ID of the file. + - `"server"` - - `filename: string` + - `"client"` - The filename of the container file cited. + - `parameters: optional unknown` - - `start_index: number` + Parameter schema for a client-executed tool search tool. - The index of the first character of the container file citation in the message. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `type: "container_file_citation"` + 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). - The type of the container file citation. Always `container_file_citation`. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `file_path: object { file_id, index, type }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A path to a file. + - `"web_search_preview"` - - `file_id: string` + - `"web_search_preview_2025_03_11"` - The ID of the file. + - `search_content_types: optional array of "text" or "image"` - - `index: number` + - `"text"` - The index of the file in the list of files. + - `"image"` - - `type: "file_path"` + - `search_context_size: optional "low" or "medium" or "high"` - The type of the file path. Always `file_path`. + 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. - - `text: string` + - `"low"` - The text output from the model. + - `"medium"` - - `type: "output_text"` + - `"high"` - The type of the output text. Always `output_text`. + - `user_location: optional object { type, city, country, 2 more }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + The user's location. - - `token: string` + - `type: "approximate"` - - `bytes: array of number` + The type of location approximation. Always `approximate`. - - `logprob: number` + - `city: optional string` - - `top_logprobs: array of object { token, bytes, logprob }` + Free text input for the city of the user, e.g. `San Francisco`. - - `token: string` + - `country: optional string` - - `bytes: array of number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `logprob: number` + - `region: optional string` - - `beta_response_output_refusal: object { refusal, type }` + Free text input for the region of the user, e.g. `California`. - A refusal from the model. + - `timezone: optional string` - - `refusal: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The refusal explanation from the model. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `type: "refusal"` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the refusal. Always `refusal`. + - `type: "apply_patch"` - - `role: "assistant"` + The type of the tool. Always `apply_patch`. - The role of the output message. Always `assistant`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `status: "in_progress" or "completed" or "incomplete"` + The tool invocation context(s). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `type: "tool_search_output"` - - `"incomplete"` + The item type. Always `tool_search_output`. - - `type: "message"` + - `id: optional string` - The type of the output message. Always `message`. + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -113216,400 +124986,389 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `call_id: optional string` - 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. + The unique ID of the tool search call generated by the model. - - `"commentary"` + - `execution: optional "server" or "client"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + Whether tool search was executed by the server or by the client. - 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. + - `"server"` - - `id: string` + - `"client"` - The unique ID of the file search tool call. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `queries: array of string` + The status of the tool search output. - The queries used to search for files. + - `"in_progress"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"completed"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"incomplete"` - - `"in_progress"` + - `additional_tools: object { role, tools, type, 2 more }` - - `"searching"` + - `role: "developer"` - - `"completed"` + The role that provided the additional tools. Only `developer` is supported. - - `"incomplete"` + - `tools: array of BetaTool` - - `"failed"` + A list of additional tools made available at this item. - - `type: "file_search_call"` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - The type of the file search tool call. Always `file_search_call`. + 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). - - `agent: optional object { agent_name }` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The agent that produced this item. + 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). - - `agent_name: string` + - `beta_computer_tool: object { type }` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - The results of the file search tool call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `attributes: optional map[string or number or boolean]` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - 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. + 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). - - `union_member_0: string` + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `union_member_1: number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `union_member_2: boolean` + - `code_interpreter: object { container, type, allowed_callers }` - - `file_id: optional string` + A tool that runs Python code to help generate a response to a prompt. - The unique ID of the file. + - `programmatic_tool_calling: object { type }` - - `filename: optional string` + - `image_generation: object { type, action, background, 9 more }` - The name of the file. + A tool that generates images using the GPT image models. - - `score: optional number` + - `local_shell: object { type }` - The relevance score of the file - a value between 0 and 1. + A tool that allows the model to execute shell commands in a local environment. - - `text: optional string` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - The text that was retrieved from the file. + A tool that allows the model to execute shell commands. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - 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. + 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) - - `id: string` + - `beta_namespace_tool: object { description, name, tools, type }` - The unique ID of the computer call. + Groups function/custom tools under a shared namespace. - - `call_id: string` + - `beta_tool_search_tool: object { type, description, execution, parameters }` - An identifier used when responding to the tool call with output. + Hosted or BYOT tool search configuration for deferred tools. - - `pending_safety_checks: array of object { id, code, message }` + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - The pending safety checks for the computer call. + 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). - - `id: string` + - `beta_apply_patch_tool: object { type, allowed_callers }` - The ID of the pending safety check. + Allows the assistant to create, delete, or update files using unified diffs. - - `code: optional string` + - `type: "additional_tools"` - The type of the pending safety check. + The item type. Always `additional_tools`. - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of this additional tools item. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The agent that produced this item. - - `"in_progress"` + - `agent_name: string` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `type: "computer_call"` + 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). - The type of the computer call. Always `computer_call`. + - `id: string` - - `"computer_call"` + The unique identifier of the reasoning content. - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `summary: array of object { text, type }` - A click action. + Reasoning summary content. - - `click: object { button, type, x, 2 more }` + - `text: string` - A click action. + A summary of the reasoning output from the model so far. - - `button: "left" or "right" or "wheel" or 2 more` + - `type: "summary_text"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The type of the object. Always `summary_text`. - - `"left"` + - `type: "reasoning"` - - `"right"` + The type of the object. Always `reasoning`. - - `"wheel"` + - `agent: optional object { agent_name }` - - `"back"` + The agent that produced this item. - - `"forward"` + - `agent_name: string` - - `type: "click"` + The canonical name of the agent that produced this item. - Specifies the event type. For a click action, this property is always `click`. + - `content: optional array of object { text, type }` - - `x: number` + Reasoning text content. - The x-coordinate where the click occurred. + - `text: string` - - `y: number` + The reasoning text from the model. - The y-coordinate where the click occurred. + - `type: "reasoning_text"` - - `keys: optional array of string` + The type of the reasoning text. Always `reasoning_text`. - The keys being held while clicking. + - `encrypted_content: optional string` - - `double_click: object { keys, type, x, y }` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - A double click action. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `keys: array of string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The keys being held while double-clicking. + - `"in_progress"` - - `type: "double_click"` + - `"completed"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"incomplete"` - - `x: number` + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - The x-coordinate where the double click occurred. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `y: number` + - `encrypted_content: string` - The y-coordinate where the double click occurred. + The encrypted content of the compaction summary. - - `drag: object { path, type, keys }` + - `type: "compaction"` - A drag action. + The type of the item. Always `compaction`. - - `path: array of object { x, y }` + - `id: optional string` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The ID of the compaction item. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `agent: optional object { agent_name }` - - `x: number` + The agent that produced this item. - The x-coordinate. + - `agent_name: string` - - `y: number` + The canonical name of the agent that produced this item. - The y-coordinate. + - `image_generation_call: object { id, result, status, 2 more }` - - `type: "drag"` + An image generation request made by the model. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `id: string` - - `keys: optional array of string` + The unique ID of the image generation call. - The keys being held while dragging the mouse. + - `result: string` - - `keypress: object { keys, type }` + The generated image encoded in base64. - A collection of keypresses the model would like to perform. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `keys: array of string` + The status of the image generation call. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"in_progress"` - - `type: "keypress"` + - `"completed"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"generating"` - - `move: object { type, x, y, keys }` + - `"failed"` - A mouse move action. + - `type: "image_generation_call"` - - `type: "move"` + The type of the image generation call. Always `image_generation_call`. - Specifies the event type. For a move action, this property is always set to `move`. + - `agent: optional object { agent_name }` - - `x: number` + The agent that produced this item. - The x-coordinate to move to. + - `agent_name: string` - - `y: number` + The canonical name of the agent that produced this item. - The y-coordinate to move to. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `keys: optional array of string` + A tool call to run code. - The keys being held while moving the mouse. + - `id: string` - - `screenshot: object { type }` + The unique ID of the code interpreter tool call. - A screenshot action. + - `code: string` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + The code to run, or null if not available. - A scroll action. + - `container_id: string` - - `scroll_x: number` + The ID of the container used to run the code. - The horizontal scroll distance. + - `outputs: array of object { logs, type } or object { type, url }` - - `scroll_y: number` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The vertical scroll distance. + - `logs: object { logs, type }` - - `type: "scroll"` + The logs output from the code interpreter. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `logs: string` - - `x: number` + The logs output from the code interpreter. - The x-coordinate where the scroll occurred. + - `type: "logs"` - - `y: number` + The type of the output. Always `logs`. - The y-coordinate where the scroll occurred. + - `image: object { type, url }` - - `keys: optional array of string` + The image output from the code interpreter. - The keys being held while scrolling. + - `type: "image"` - - `type: object { text, type }` + The type of the output. Always `image`. - An action to type in text. + - `url: string` - - `text: string` + The URL of the image output from the code interpreter. - The text to type. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "type"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Specifies the event type. For a type action, this property is always set to `type`. + - `"in_progress"` - - `wait: object { type }` + - `"completed"` - A wait action. + - `"incomplete"` - - `actions: optional array of BetaComputerAction` + - `"interpreting"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"failed"` - - `click: object { button, type, x, 2 more }` + - `type: "code_interpreter_call"` - A click action. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `double_click: object { keys, type, x, y }` + - `agent: optional object { agent_name }` - A double click action. + The agent that produced this item. - - `drag: object { path, type, keys }` + - `agent_name: string` - A drag action. + The canonical name of the agent that produced this item. - - `keypress: object { keys, type }` + - `local_shell_call: object { id, action, call_id, 3 more }` - A collection of keypresses the model would like to perform. + A tool call to run a command on the local shell. - - `move: object { type, x, y, keys }` + - `id: string` - A mouse move action. + The unique ID of the local shell call. - - `screenshot: object { type }` + - `action: object { command, env, type, 3 more }` - A screenshot action. + Execute a shell command on the server. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `command: array of string` - A scroll action. + The command to run. - - `type: object { text, type }` + - `env: map[string]` - An action to type in text. + Environment variables to set for the command. - - `wait: object { type }` + - `type: "exec"` - A wait action. + The type of the local shell action. Always `exec`. - - `agent: optional object { agent_name }` + - `timeout_ms: optional number` - The agent that produced this item. + Optional timeout in milliseconds for the command. - - `agent_name: string` + - `user: optional string` - The canonical name of the agent that produced this item. + Optional user to run the command as. - - `computer_call_output: object { call_id, output, type, 4 more }` + - `working_directory: optional string` - The output of a computer tool call. + Optional working directory to run the command in. - `call_id: string` - The ID of the computer tool call that produced the output. - - - `output: object { type, file_id, image_url }` + The unique ID of the local shell tool call generated by the model. - A computer screenshot image used with the computer use tool. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "computer_screenshot"` + The status of the local shell call. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"in_progress"` - - `file_id: optional string` + - `"completed"` - The identifier of an uploaded file that contains the screenshot. + - `"incomplete"` - - `image_url: optional string` + - `type: "local_shell_call"` - The URL of the screenshot image. + The type of the local shell call. Always `local_shell_call`. - - `type: "computer_call_output"` + - `agent: optional object { agent_name }` - The type of the computer tool call output. Always `computer_call_output`. + The agent that produced this item. - - `id: optional string` + - `agent_name: string` - The ID of the computer tool call output. + The canonical name of the agent that produced this item. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `local_shell_call_output: object { id, output, type, 2 more }` - The safety checks reported by the API that have been acknowledged by the developer. + The output of a local shell tool call. - `id: string` - The ID of the pending safety check. + The unique ID of the local shell tool call generated by the model. - - `code: optional string` + - `output: string` - The type of the pending safety check. + A JSON string of the output of the local shell tool call. - - `message: optional string` + - `type: "local_shell_call_output"` - Details about the pending safety check. + The type of the local shell tool call output. Always `local_shell_call_output`. - `agent: optional object { agent_name }` @@ -113621,7 +125380,7 @@ openai beta:responses compact \ - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -113629,124 +125388,127 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `shell_call: object { action, call_id, type, 5 more }` - 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. + A tool representing a request to execute one or more shell commands. - - `id: string` + - `action: object { commands, max_output_length, timeout_ms }` - The unique ID of the web search tool call. + The shell commands and limits that describe how to run the tool call. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `commands: array of string` - 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). + Ordered shell commands for the execution environment to run. - - `search: object { type, queries, query, sources }` + - `max_output_length: optional number` - Action type "search" - Performs a web search query. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `type: "search"` + - `timeout_ms: optional number` - The action type. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `queries: optional array of string` + - `call_id: string` - The search queries. + The unique ID of the shell tool call generated by the model. - - `query: optional string` + - `type: "shell_call"` - The search query. + The type of the item. Always `shell_call`. - - `sources: optional array of object { type, url }` + - `id: optional string` - The sources used in the search. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: "url"` + - `agent: optional object { agent_name }` - The type of source. Always `url`. + The agent that produced this item. - - `url: string` + - `agent_name: string` - The URL of the source. + The canonical name of the agent that produced this item. - - `open_page: object { type, url }` + - `caller: optional object { type } or object { caller_id, type }` - Action type "open_page" - Opens a specific URL from search results. + The execution context that produced this tool call. - - `type: "open_page"` + - `direct: object { type }` - The action type. + - `program: object { caller_id, type }` - - `url: optional string` + - `caller_id: string` - The URL opened by the model. + The call ID of the program item that produced this tool call. - - `find_in_page: object { pattern, type, url }` + - `type: "program"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The caller type. Always `program`. - - `pattern: string` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - The pattern or text to search for within the page. + The environment to execute the shell commands in. - - `type: "find_in_page"` + - `beta_local_environment: object { type, skills }` - The action type. + - `beta_container_reference: object { container_id, type }` - - `url: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The URL of the page searched for the pattern. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"in_progress"` - The status of the web search tool call. + - `"completed"` - - `"in_progress"` + - `"incomplete"` - - `"searching"` + - `shell_call_output: object { call_id, output, type, 5 more }` - - `"completed"` + The streamed output items emitted by a shell tool call. - - `"failed"` + - `call_id: string` - - `type: "web_search_call"` + The unique ID of the shell tool call generated by the model. - The type of the web search tool call. Always `web_search_call`. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `agent: optional object { agent_name }` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The agent that produced this item. + - `outcome: object { type } or object { exit_code, type }` - - `agent_name: string` + The exit or timeout outcome associated with this shell call. - The canonical name of the agent that produced this item. + - `timeout: object { type }` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + Indicates that the shell call exceeded its configured time limit. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `exit: object { exit_code, type }` - - `arguments: string` + Indicates that the shell commands finished and returned an exit code. - A JSON string of the arguments to pass to the function. + - `exit_code: number` - - `call_id: string` + The exit code returned by the shell process. - The unique ID of the function tool call generated by the model. + - `type: "exit"` - - `name: string` + The outcome type. Always `exit`. - The name of the function to run. + - `stderr: string` - - `type: "function_call"` + Captured stderr output for the shell call. - The type of the function tool call. Always `function_call`. + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. - `id: optional string` - The unique ID of the function tool call. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -113770,14 +125532,15 @@ openai beta:responses compact \ - `type: "program"` - - `namespace: optional string` + The caller type. Always `program`. - The namespace of the function to run. + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call output. - `"in_progress"` @@ -113785,131 +125548,125 @@ openai beta:responses compact \ - `"incomplete"` - - `function_call_output: object { call_id, output, type, 4 more }` + - `apply_patch_call: object { call_id, operation, status, 4 more }` - The output of a function tool call. + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` - The unique ID of the function tool call generated by the model. - - - `output: string or BetaResponseFunctionCallOutputItemList` - - Text, image, or file output of the function tool call. - - - `union_member_0: string` + The unique ID of the apply patch tool call generated by the model. - A JSON string of the output of the function tool call. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + The specific create, delete, or update instruction for the apply_patch tool call. - An array of content outputs (text, image, file) for the function tool call. + - `create_file: object { diff, path, type }` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + Instruction for creating a new file via the apply_patch tool. - A text input to the model. + - `diff: string` - - `text: string` + Unified diff content to apply when creating the file. - The text input to the model. + - `path: string` - - `type: "input_text"` + Path of the file to create relative to the workspace root. - The type of the input item. Always `input_text`. + - `type: "create_file"` - - `prompt_cache_breakpoint: optional object { mode }` + The operation type. Always `create_file`. - 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. + - `delete_file: object { path, type }` - - `mode: "explicit"` + Instruction for deleting an existing file via the apply_patch tool. - The breakpoint mode. Always `explicit`. + - `path: string` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + Path of the file to delete relative to the workspace root. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `type: "delete_file"` - - `type: "input_image"` + The operation type. Always `delete_file`. - The type of the input item. Always `input_image`. + - `update_file: object { diff, path, type }` - - `detail: optional "low" or "high" or "auto" or "original"` + Instruction for updating an existing file via the apply_patch tool. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `diff: string` - - `"low"` + Unified diff content to apply to the existing file. - - `"high"` + - `path: string` - - `"auto"` + Path of the file to update relative to the workspace root. - - `"original"` + - `type: "update_file"` - - `file_id: optional string` + The operation type. Always `update_file`. - The ID of the file to be sent to the model. + - `status: "in_progress" or "completed"` - - `image_url: optional string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"in_progress"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"completed"` - 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. + - `type: "apply_patch_call"` - - `mode: "explicit"` + The type of the item. Always `apply_patch_call`. - The breakpoint mode. Always `explicit`. + - `id: optional string` - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - A file input to the model. + - `agent: optional object { agent_name }` - - `type: "input_file"` + The agent that produced this item. - The type of the input item. Always `input_file`. + - `agent_name: string` - - `detail: optional "auto" or "low" or "high"` + The canonical name of the agent that produced this item. - 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`. + - `caller: optional object { type } or object { caller_id, type }` - - `"auto"` + The execution context that produced this tool call. - - `"low"` + - `direct: object { type }` - - `"high"` + - `program: object { caller_id, type }` - - `file_data: optional string` + - `caller_id: string` - The base64-encoded data of the file to be sent to the model. + The call ID of the program item that produced this tool call. - - `file_id: optional string` + - `type: "program"` - The ID of the file to be sent to the model. + The caller type. Always `program`. - - `file_url: optional string` + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - The URL of the file to be sent to the model. + The streamed output emitted by an apply patch tool call. - - `filename: optional string` + - `call_id: string` - The name of the file to be sent to the model. + The unique ID of the apply patch tool call generated by the model. - - `prompt_cache_breakpoint: optional object { mode }` + - `status: "completed" or "failed"` - 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. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `mode: "explicit"` + - `"completed"` - The breakpoint mode. Always `explicit`. + - `"failed"` - - `type: "function_call_output"` + - `type: "apply_patch_call_output"` - The type of the function tool call output. Always `function_call_output`. + The type of the item. Always `apply_patch_call_output`. - `id: optional string` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -113935,91 +125692,109 @@ openai beta:responses compact \ The caller type. Always `program`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `output: optional string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `"in_progress"` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `"completed"` + A list of tools available on an MCP server. - - `"incomplete"` + - `id: string` - - `agent_message: object { author, content, recipient, 3 more }` + The unique ID of the list. - A message routed between agents. + - `server_label: string` - - `author: string` + The label of the MCP server. - The sending agent identity. + - `tools: array of object { input_schema, name, annotations, description }` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The tools available on the server. - Plaintext, image, or encrypted content sent between agents. + - `input_schema: unknown` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + The JSON schema describing the tool's input. - A text input to the model. + - `name: string` - - `text: string` + The name of the tool. - The text input to the model. + - `annotations: optional unknown` - - `type: "input_text"` + Additional annotations about the tool. - The type of the input item. Always `input_text`. + - `description: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The description of the tool. - 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. + - `type: "mcp_list_tools"` - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + The type of the item. Always `mcp_list_tools`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `agent: optional object { agent_name }` - - `type: "input_image"` + The agent that produced this item. - The type of the input item. Always `input_image`. + - `agent_name: string` - - `detail: optional "low" or "high" or "auto" or "original"` + The canonical name of the agent that produced this item. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `error: optional string` - - `file_id: optional string` + Error message if the server could not list tools. - The ID of the file to be sent to the model. + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `image_url: optional string` + A request for human approval of a tool invocation. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique ID of the approval request. - 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. + - `arguments: string` - - `encrypted_content: object { encrypted_content, type }` + A JSON string of arguments for the tool. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `name: string` - - `encrypted_content: string` + The name of the tool to run. - Opaque encrypted content. + - `server_label: string` - - `type: "encrypted_content"` + The label of the MCP server making the request. - The type of the input item. Always `encrypted_content`. + - `type: "mcp_approval_request"` - - `recipient: string` + The type of the item. Always `mcp_approval_request`. - The destination agent identity. + - `agent: optional object { agent_name }` - - `type: "agent_message"` + The agent that produced this item. - The item type. Always `agent_message`. + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. - `id: optional string` - The unique ID of this agent message item. + The unique ID of the approval response - `agent: optional object { agent_name }` @@ -114029,39 +125804,33 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. - - - `"spawn_agent"` + - `reason: optional string` - - `"interrupt_agent"` + Optional reason for the decision. - - `"list_agents"` + - `mcp_call: object { id, arguments, name, 7 more }` - - `"send_message"` + An invocation of a tool on an MCP server. - - `"followup_task"` + - `id: string` - - `"wait_agent"` + The unique ID of the tool call. - `arguments: string` - The action arguments as a JSON string. + A JSON string of the arguments passed to the tool. - - `call_id: string` + - `name: string` - The unique ID linking this call to its output. + The name of the tool that was run. - - `type: "multi_agent_call"` + - `server_label: string` - The item type. Always `multi_agent_call`. + The label of the MCP server running the tool. - - `id: optional string` + - `type: "mcp_call"` - The unique ID of this multi-agent call. + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` @@ -114071,117 +125840,133 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + - `approval_request_id: optional string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + 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. - The multi-agent action that produced this result. + - `error: optional string` - - `"spawn_agent"` + The error from the tool call, if any. - - `"interrupt_agent"` + - `output: optional string` - - `"list_agents"` + The output from the tool call. - - `"send_message"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"followup_task"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"wait_agent"` + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + + The output of a custom tool call from your code, being sent back to the model. - `call_id: string` - The unique ID of the multi-agent call. + The call ID, used to map this custom tool call output to a custom tool call. - - `output: array of object { text, type, annotations }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Text output returned by the multi-agent action. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `text: string` + - `string output: string` - The text content. + A string of the output of the custom tool call. - - `type: "output_text"` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The content type. Always `output_text`. + Text, image, or file output of the custom tool call. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - Citations associated with the text content. + A text input to the model. - - `union_member_0: array of object { file_id, filename, index, type }` + - `text: string` - - `file_id: string` + The text input to the model. - The ID of the file. + - `type: "input_text"` - - `filename: string` + The type of the input item. Always `input_text`. - The filename of the file cited. + - `prompt_cache_breakpoint: optional object { mode }` - - `index: number` + 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. - The index of the file in the list of files. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `type: "file_citation"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The citation type. Always `file_citation`. + - `detail: "low" or "high" or "auto" or "original"` - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `end_index: number` + - `type: "input_image"` - The index of the last character of the citation in the message. + The type of the input item. Always `input_image`. - - `start_index: number` + - `file_id: optional string` - The index of the first character of the citation in the message. + The ID of the file to be sent to the model. - - `title: string` + - `image_url: optional string` - The title of the cited resource. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: "url_citation"` + - `prompt_cache_breakpoint: optional object { mode }` - The citation type. Always `url_citation`. + 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. - - `url: string` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The URL of the cited resource. + A file input to the model. - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + - `type: "input_file"` - - `container_id: string` + The type of the input item. Always `input_file`. - The ID of the container. + - `detail: optional "auto" or "low" or "high"` - - `end_index: number` + 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`. - The index of the last character of the citation in the message. + - `file_data: optional string` - - `file_id: string` + The content of the file to be sent to the model. - The ID of the container file. + - `file_id: optional string` - - `filename: string` + The ID of the file to be sent to the model. - The filename of the container file cited. + - `file_url: optional string` - - `start_index: number` + The URL of the file to be sent to the model. - The index of the first character of the citation in the message. + - `filename: optional string` - - `type: "container_file_citation"` + The name of the file to be sent to the model. - The citation type. Always `container_file_citation`. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "multi_agent_call_output"` + 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. - The item type. Always `multi_agent_call_output`. + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. - `id: optional string` - The unique ID of this multi-agent call output. + The unique ID of the custom tool call output in the OpenAI platform. - `agent: optional object { agent_name }` @@ -114191,1093 +125976,1082 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `tool_search_call: object { arguments, type, id, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - - `arguments: unknown` + The execution context that produced this tool call. - The arguments supplied to the tool search call. + - `direct: object { type }` - - `type: "tool_search_call"` + - `program: object { caller_id, type }` - The item type. Always `tool_search_call`. + - `caller_id: string` - - `id: optional string` + The call ID of the program item that produced this tool call. - The unique ID of this tool search call. + - `type: "program"` - - `agent: optional object { agent_name }` + The caller type. Always `program`. - The agent that produced this item. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `agent_name: string` + A call to a custom tool created by the model. - The canonical name of the agent that produced this item. + - `call_id: string` - - `call_id: optional string` + An identifier used to map this custom tool call to a tool call output. - The unique ID of the tool search call generated by the model. + - `input: string` - - `execution: optional "server" or "client"` + The input for the custom tool call generated by the model. - Whether tool search was executed by the server or by the client. + - `name: string` - - `"server"` + The name of the custom tool being called. - - `"client"` + - `type: "custom_tool_call"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the custom tool call. Always `custom_tool_call`. - The status of the tool search call. + - `id: optional string` - - `"in_progress"` + The unique ID of the custom tool call in the OpenAI platform. - - `"completed"` + - `agent: optional object { agent_name }` - - `"incomplete"` + The agent that produced this item. - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + - `agent_name: string` - - `tools: array of BetaTool` + The canonical name of the agent that produced this item. - The loaded tool definitions returned by the tool search output. + - `caller: optional object { type } or object { caller_id, type }` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The execution context that produced this tool call. - 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). + - `direct: object { type }` - - `name: string` + - `program: object { caller_id, type }` - The name of the function to call. + - `caller_id: string` - - `parameters: map[unknown]` + The call ID of the program item that produced this tool call. - A JSON schema object describing the parameters of the function. + - `type: "program"` - - `strict: boolean` + - `namespace: optional string` - Whether strict parameter validation is enforced for this function tool. + The namespace of the custom tool being called. - - `type: "function"` + - `compaction_trigger: object { type, agent }` - The type of the function tool. Always `function`. + Compacts the current context. Must be the final input item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "compaction_trigger"` - The tool invocation context(s). + The type of the item. Always `compaction_trigger`. - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that produced this item. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this function is deferred and loaded via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `item_reference: object { id, agent, type }` - A description of the function. Used by the model to determine whether or not to call the function. + An internal identifier for an item to reference. - - `output_schema: optional map[unknown]` + - `id: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The ID of the item to reference. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `agent: optional object { agent_name }` - 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). + The agent that produced this item. - - `type: "file_search"` + - `agent_name: string` - The type of the file search tool. Always `file_search`. + The canonical name of the agent that produced this item. - - `vector_store_ids: array of string` + - `type: optional "item_reference"` - The IDs of the vector stores to search. + The type of item to reference. Always `item_reference`. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"item_reference"` - A filter to apply. + - `program: object { id, call_id, code, 3 more }` - - `Comparison Filter: object { key, type, value }` + - `id: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The unique ID of this program item. - - `key: string` + - `call_id: string` - The key to compare against the value. + The stable call ID of the program item. - - `type: "eq" or "ne" or "gt" or 5 more` + - `code: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The JavaScript source executed by programmatic tool calling. - - `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 + - `fingerprint: string` - - `"eq"` + Opaque program replay fingerprint that must be round-tripped. - - `"ne"` + - `type: "program"` - - `"gt"` + The item type. Always `program`. - - `"gte"` + - `agent: optional object { agent_name }` - - `"lt"` + The agent that produced this item. - - `"lte"` + - `agent_name: string` - - `"in"` + The canonical name of the agent that produced this item. - - `"nin"` + - `program_output: object { id, call_id, result, 3 more }` - - `value: string or number or boolean or array of unknown` + - `id: string` - The value to compare against the attribute key; supports string, number, or boolean types. + The unique ID of this program output item. - - `union_member_0: string` + - `call_id: string` - - `union_member_1: number` + The call ID of the program item. - - `union_member_2: boolean` + - `result: string` - - `union_member_3: array of unknown` + The result produced by the program item. - - `Compound Filter: object { filters, type }` + - `status: "completed" or "incomplete"` - Combine multiple filters using `and` or `or`. + The terminal status of the program output. - - `filters: array of object { key, type, value } or unknown` + - `"completed"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"incomplete"` - - `Comparison Filter: object { key, type, value }` + - `type: "program_output"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The item type. Always `program_output`. - - `key: string` + - `agent: optional object { agent_name }` - The key to compare against the value. + The agent that produced this item. - - `type: "eq" or "ne" or "gt" or 5 more` + - `agent_name: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The canonical name of the agent that produced this item. - - `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 + - `metadata: map[string]` - - `"eq"` + 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. - - `"ne"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"gt"` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `"gte"` + Model ID used to generate the response, like `gpt-4o` 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. - - `"lt"` + - `"gpt-5.6-sol"` - - `"lte"` + - `"gpt-5.6-terra"` - - `"in"` + - `"gpt-5.6-luna"` - - `"nin"` + - `"gpt-5.4"` - - `value: string or number or boolean or array of unknown` + - `"gpt-5.4-mini"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-5.4-nano"` - - `union_member_0: string` + - `"gpt-5.4-mini-2026-03-17"` - - `union_member_1: number` + - `"gpt-5.4-nano-2026-03-17"` - - `union_member_2: boolean` + - `"gpt-5.3-chat-latest"` - - `union_member_3: array of unknown` + - `"gpt-5.2"` - - `union_member_1: unknown` + - `"gpt-5.2-2025-12-11"` - - `type: "and" or "or"` + - `"gpt-5.2-chat-latest"` - Type of operation: `and` or `or`. + - `"gpt-5.2-pro"` - - `"and"` + - `"gpt-5.2-pro-2025-12-11"` - - `"or"` + - `"gpt-5.1"` - - `max_num_results: optional number` + - `"gpt-5.1-2025-11-13"` + + - `"gpt-5.1-codex"` + + - `"gpt-5.1-mini"` + + - `"gpt-5.1-chat-latest"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"gpt-5"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"gpt-5-mini"` - Ranking options for search. + - `"gpt-5-nano"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"gpt-5-2025-08-07"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"gpt-5-mini-2025-08-07"` - - `embedding_weight: number` + - `"gpt-5-nano-2025-08-07"` - The weight of the embedding in the reciprocal ranking fusion. + - `"gpt-5-chat-latest"` - - `text_weight: number` + - `"gpt-4.1"` - The weight of the text in the reciprocal ranking fusion. + - `"gpt-4.1-mini"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"gpt-4.1-nano"` - The ranker to use for the file search. + - `"gpt-4.1-2025-04-14"` - - `"auto"` + - `"gpt-4.1-mini-2025-04-14"` - - `"default-2024-11-15"` + - `"gpt-4.1-nano-2025-04-14"` - - `score_threshold: optional number` + - `"o4-mini"` - 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. + - `"o4-mini-2025-04-16"` - - `beta_computer_tool: object { type }` + - `"o3"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"o3-2025-04-16"` - - `type: "computer"` + - `"o3-mini"` - The type of the computer tool. Always `computer`. + - `"o3-mini-2025-01-31"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `"o1"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"o1-2024-12-17"` - - `display_height: number` + - `"o1-preview"` - The height of the computer display. + - `"o1-preview-2024-09-12"` - - `display_width: number` + - `"o1-mini"` - The width of the computer display. + - `"o1-mini-2024-09-12"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"gpt-4o"` - The type of computer environment to control. + - `"gpt-4o-2024-11-20"` - - `"windows"` + - `"gpt-4o-2024-08-06"` - - `"mac"` + - `"gpt-4o-2024-05-13"` - - `"linux"` + - `"gpt-4o-audio-preview"` - - `"ubuntu"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `"browser"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `type: "computer_use_preview"` + - `"gpt-4o-audio-preview-2025-06-03"` - The type of the computer use tool. Always `computer_use_preview`. + - `"gpt-4o-mini-audio-preview"` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - 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). + - `"gpt-4o-search-preview"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"gpt-4o-mini-search-preview"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"gpt-4o-search-preview-2025-03-11"` - - `"web_search"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"web_search_2025_08_26"` + - `"chatgpt-4o-latest"` - - `filters: optional object { allowed_domains }` + - `"codex-mini-latest"` - Filters for the search. + - `"gpt-4o-mini"` - - `allowed_domains: optional array of string` + - `"gpt-4o-mini-2024-07-18"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"gpt-4-turbo"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"gpt-4-turbo-2024-04-09"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"gpt-4-0125-preview"` - 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. + - `"gpt-4-turbo-preview"` - - `"low"` + - `"gpt-4-1106-preview"` - - `"medium"` + - `"gpt-4-vision-preview"` - - `"high"` + - `"gpt-4"` - - `user_location: optional object { city, country, region, 2 more }` + - `"gpt-4-0314"` - The approximate location of the user. + - `"gpt-4-0613"` - - `city: optional string` + - `"gpt-4-32k"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"gpt-4-32k-0314"` - - `country: optional string` + - `"gpt-4-32k-0613"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"gpt-3.5-turbo"` - - `region: optional string` + - `"gpt-3.5-turbo-16k"` - Free text input for the region of the user, e.g. `California`. + - `"gpt-3.5-turbo-0301"` - - `timezone: optional string` + - `"gpt-3.5-turbo-0613"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"gpt-3.5-turbo-1106"` - - `type: optional "approximate"` + - `"gpt-3.5-turbo-0125"` - The type of location approximation. Always `approximate`. + - `"gpt-3.5-turbo-16k-0613"` - - `"approximate"` + - `"o1-pro"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `"o1-pro-2025-03-19"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"o3-pro"` - - `server_label: string` + - `"o3-pro-2025-06-10"` - A label for this MCP server, used to identify it in tool calls. + - `"o3-deep-research"` - - `type: "mcp"` + - `"o3-deep-research-2025-06-26"` - The type of the MCP tool. Always `mcp`. + - `"o4-mini-deep-research"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"o4-mini-deep-research-2025-06-26"` - The tool invocation context(s). + - `"computer-use-preview"` - - `"direct"` + - `"computer-use-preview-2025-03-11"` - - `"programmatic"` + - `"gpt-5-codex"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"gpt-5-pro"` - List of allowed tool names or a filter object. + - `"gpt-5-pro-2025-10-06"` - - `MCP allowed tools: array of string` + - `"gpt-5.1-codex-max"` - A string array of allowed tool names + - `object: "response"` - - `MCP tool filter: object { read_only, tool_names }` + The object type of this resource - always set to `response`. - A filter object to specify which tools are allowed. + - `output: array of BetaResponseOutputItem` - - `read_only: optional boolean` + An array of content items generated by the model. - 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. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `tool_names: optional array of string` + - `beta_response_output_message: object { id, content, role, 4 more }` - List of allowed tool names. + An output message from the model. - - `authorization: optional string` + - `id: string` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The unique ID of the output message. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - 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). + The content of the output message. - Currently supported `connector_id` values are: + - `role: "assistant"` - - 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` + The role of the output message. Always `assistant`. - - `"connector_dropbox"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"connector_gmail"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"connector_googlecalendar"` + - `type: "message"` - - `"connector_googledrive"` + The type of the output message. Always `message`. - - `"connector_microsoftteams"` + - `agent: optional object { agent_name }` - - `"connector_outlookcalendar"` + The agent that produced this item. - - `"connector_outlookemail"` + - `phase: optional "commentary" or "final_answer"` - - `"connector_sharepoint"` + 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. - - `defer_loading: optional boolean` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - Whether this MCP tool is deferred and discovered via tool search. + 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. - - `headers: optional map[string]` + - `id: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The unique ID of the file search tool call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `queries: array of string` - Specify which of the MCP server's tools require approval. + The queries used to search for files. - - `MCP tool approval filter: object { always, never }` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `always: optional object { read_only, tool_names }` + - `type: "file_search_call"` - A filter object to specify which tools are allowed. + The type of the file search tool call. Always `file_search_call`. - - `read_only: optional boolean` + - `agent: optional object { agent_name }` - 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. + The agent that produced this item. - - `tool_names: optional array of string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - List of allowed tool names. + The results of the file search tool call. - - `never: optional object { read_only, tool_names }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - A filter object to specify which tools are allowed. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `read_only: optional boolean` + - `arguments: string` - 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. + A JSON string of the arguments to pass to the function. - - `tool_names: optional array of string` + - `call_id: string` - List of allowed tool names. + The unique ID of the function tool call generated by the model. - - `MCP tool approval setting: "always" or "never"` + - `name: string` - 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. + The name of the function to run. - - `"always"` + - `type: "function_call"` - - `"never"` + The type of the function tool call. Always `function_call`. - - `server_description: optional string` + - `id: optional string` - Optional description of the MCP server, used to provide more context. + The unique ID of the function tool call. - - `server_url: optional string` + - `agent: optional object { agent_name }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The agent that produced this item. - - `tunnel_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - - `code_interpreter: object { container, type, allowed_callers }` + - `namespace: optional string` - A tool that runs Python code to help generate a response to a prompt. + The namespace of the function to run. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `status: optional "in_progress" or "completed" or "incomplete"` - 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. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `union_member_0: string` + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - The container ID. + - `id: string` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + The unique ID of the function call tool output. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `call_id: string` - - `type: "auto"` + The unique ID of the function tool call generated by the model. - Always `auto`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `file_ids: optional array of string` + The output from the function call generated by your code. + Can be a string or an list of output content. - An optional list of uploaded files to make available to your code. + - `string output: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A string of the output of the function call. - The memory limit for the code interpreter container. + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"1g"` + Text, image, or file output of the function call. - - `"4g"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"16g"` + A text input to the model. - - `"64g"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Network access policy for the container. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `beta_container_network_policy_disabled: object { type }` + A file input to the model. - - `type: "disabled"` + - `status: "in_progress" or "completed" or "incomplete"` - Disable outbound network access. Always `disabled`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `"in_progress"` - - `allowed_domains: array of string` + - `"completed"` - A list of allowed domains when type is `allowlist`. + - `"incomplete"` - - `type: "allowlist"` + - `type: "function_call_output"` - Allow outbound network access only to specified domains. Always `allowlist`. + The type of the function tool call output. Always `function_call_output`. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `agent: optional object { agent_name }` - Optional domain-scoped secrets for allowlisted domains. + The agent that produced this item. - - `domain: string` + - `agent_name: string` - The domain associated with the secret. + The canonical name of the agent that produced this item. - - `name: string` + - `caller: optional object { type } or object { caller_id, type }` - The name of the secret to inject for the domain. + The execution context that produced this tool call. - - `value: string` + - `direct: object { type }` - The secret value to inject for the domain. + - `program: object { caller_id, type }` - - `type: "code_interpreter"` + - `caller_id: string` - The type of the code interpreter tool. Always `code_interpreter`. + The call ID of the program item that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "program"` - The tool invocation context(s). + The caller type. Always `program`. - - `"direct"` + - `created_by: optional string` - - `"programmatic"` + The identifier of the actor that created the item. - - `programmatic_tool_calling: object { type }` + - `agent_message: object { id, author, content, 3 more }` - - `image_generation: object { type, action, background, 9 more }` + - `id: string` - A tool that generates images using the GPT image models. + The unique ID of the agent message. - - `type: "image_generation"` + - `author: string` - The type of the image generation tool. Always `image_generation`. + The sending agent identity. - - `action: optional "generate" or "edit" or "auto"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - Whether to generate a new image or edit an existing image. Default: `auto`. + Encrypted content sent between agents. - - `"generate"` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `"edit"` + A text input to the model. - - `"auto"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `background: optional "transparent" or "opaque" or "auto"` + A text output from the model. - 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. + - `text: object { text, type }` - `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. + A text content. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `text: string` - - `"transparent"` + - `type: "text"` - - `"opaque"` + - `summary_text: object { text, type }` - - `"auto"` + A summary text from the model. - - `input_fidelity: optional "high" or "low"` + - `text: string` - 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`. + A summary of the reasoning output from the model so far. - - `"high"` + - `type: "summary_text"` - - `"low"` + The type of the object. Always `summary_text`. - - `input_image_mask: optional object { file_id, image_url }` + - `reasoning_text: object { text, type }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Reasoning text from the model. - - `file_id: optional string` + - `text: string` - File ID for the mask image. + The reasoning text from the model. - - `image_url: optional string` + - `type: "reasoning_text"` - Base64-encoded mask image. + The type of the reasoning text. Always `reasoning_text`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `beta_response_output_refusal: object { refusal, type }` - The image generation model to use. Default: `gpt-image-1`. + A refusal from the model. - - `"gpt-image-1"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `"gpt-image-1-mini"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `"gpt-image-2"` + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - - `"gpt-image-2-2026-04-21"` + A screenshot of a computer. - - `"gpt-image-1.5"` + - `detail: "low" or "high" or "auto" or "original"` - - `"chatgpt-image-latest"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `moderation: optional "auto" or "low"` + - `"low"` - Moderation level for the generated image. Default: `auto`. + - `"high"` - `"auto"` - - `"low"` + - `"original"` - - `output_compression: optional number` + - `file_id: string` - Compression level for the output image. Default: 100. + The identifier of an uploaded file that contains the screenshot. - - `output_format: optional "png" or "webp" or "jpeg"` + - `image_url: string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The URL of the screenshot image. - - `"png"` + - `type: "computer_screenshot"` - - `"webp"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"jpeg"` + - `prompt_cache_breakpoint: optional object { mode }` - - `partial_images: optional number` + 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. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `mode: "explicit"` - - `quality: optional "low" or "medium" or "high" or "auto"` + The breakpoint mode. Always `explicit`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"low"` + A file input to the model. - - `"medium"` + - `encrypted_content: object { encrypted_content, type }` - - `"high"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"auto"` + - `encrypted_content: string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Opaque encrypted content. - 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`. + - `type: "encrypted_content"` - - `"1024x1024"` + The type of the input item. Always `encrypted_content`. - - `"1024x1536"` + - `recipient: string` - - `"1536x1024"` + The destination agent identity. - - `"auto"` + - `type: "agent_message"` - - `local_shell: object { type }` + The type of the item. Always `agent_message`. - A tool that allows the model to execute shell commands in a local environment. + - `agent: optional object { agent_name }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The agent that produced this item. - A tool that allows the model to execute shell commands. + - `agent_name: string` - - `type: "shell"` + The canonical name of the agent that produced this item. - The type of the shell tool. Always `shell`. + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the multi-agent call item. - - `"direct"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"programmatic"` + The multi-agent action to execute. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"spawn_agent"` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `"interrupt_agent"` - - `type: "container_auto"` + - `"list_agents"` - Automatically creates a container for this request + - `"send_message"` - - `file_ids: optional array of string` + - `"followup_task"` - An optional list of uploaded files to make available to your code. + - `"wait_agent"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `arguments: string` - The memory limit for the container. + The JSON string of arguments generated for the action. - - `"1g"` + - `call_id: string` - - `"4g"` + The unique ID linking this call to its output. - - `"16g"` + - `type: "multi_agent_call"` - - `"64g"` + The type of the multi-agent call. Always `multi_agent_call`. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `agent: optional object { agent_name }` - Network access policy for the container. + The agent that produced this item. - - `beta_container_network_policy_disabled: object { type }` + - `agent_name: string` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The canonical name of the agent that produced this item. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - An optional list of skills referenced by id or inline data. + - `id: string` - - `beta_skill_reference: object { skill_id, type, version }` + The unique ID of the multi-agent call output item. - - `skill_id: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The ID of the referenced skill. + The multi-agent action that produced this result. - - `type: "skill_reference"` + - `"spawn_agent"` - References a skill created with the /v1/skills endpoint. + - `"interrupt_agent"` - - `version: optional string` + - `"list_agents"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"send_message"` - - `beta_inline_skill: object { description, name, source, type }` + - `"followup_task"` - - `description: string` + - `"wait_agent"` - The description of the skill. + - `call_id: string` - - `name: string` + The unique ID of the multi-agent call. - The name of the skill. + - `output: array of BetaResponseOutputText` - - `source: object { data, media_type, type }` + Text output returned by the multi-agent action. - Inline skill payload + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `data: string` + The annotations of the text output. - Base64-encoded skill zip bundle. + - `text: string` - - `media_type: "application/zip"` + The text output from the model. - The media type of the inline skill payload. Must be `application/zip`. + - `type: "output_text"` - - `type: "base64"` + The type of the output text. Always `output_text`. - The type of the inline skill source. Must be `base64`. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "inline"` + - `type: "multi_agent_call_output"` - Defines an inline skill for this request. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `beta_local_environment: object { type, skills }` + - `agent: optional object { agent_name }` - - `type: "local"` + The agent that produced this item. - Use a local computer environment. + - `agent_name: string` - - `skills: optional array of BetaLocalSkill` + The canonical name of the agent that produced this item. - An optional list of skills. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `description: string` + 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. - The description of the skill. + - `id: string` - - `name: string` + The unique ID of the web search tool call. - The name of the skill. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `path: string` + 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). - The path to the directory containing the skill. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `beta_container_reference: object { container_id, type }` + The status of the web search tool call. - - `container_id: string` + - `type: "web_search_call"` - The ID of the referenced container. + The type of the web search tool call. Always `web_search_call`. - - `type: "container_reference"` + - `agent: optional object { agent_name }` - References a container created with the /v1/containers endpoint + The agent that produced this item. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - 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) + 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. - - `name: string` + - `id: string` - The name of the custom tool, used to identify it in tool calls. + The unique ID of the computer call. - - `type: "custom"` + - `call_id: string` - The type of the custom tool. Always `custom`. + An identifier used when responding to the tool call with output. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `pending_safety_checks: array of object { id, code, message }` - The tool invocation context(s). + The pending safety checks for the computer call. - - `"direct"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"programmatic"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `defer_loading: optional boolean` + - `type: "computer_call"` - Whether this tool should be deferred and discovered via tool search. + The type of the computer call. Always `computer_call`. - - `description: optional string` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - Optional description of the custom tool, used to provide more context. + A click action. - - `format: optional object { type } or object { definition, syntax, type }` + - `actions: optional array of BetaComputerAction` - The input format for the custom tool. Default is unconstrained text. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `text: object { type }` + - `agent: optional object { agent_name }` - Unconstrained free-form text. + The agent that produced this item. - - `grammar: object { definition, syntax, type }` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - A grammar defined by the user. + - `id: string` - - `definition: string` + The unique ID of the computer call tool output. - The grammar definition. + - `call_id: string` - - `syntax: "lark" or "regex"` + The ID of the computer tool call that produced the output. - The syntax of the grammar definition. One of `lark` or `regex`. + - `output: object { type, file_id, image_url }` - - `"lark"` + A computer screenshot image used with the computer use tool. - - `"regex"` + - `type: "computer_screenshot"` - - `type: "grammar"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Grammar format. Always `grammar`. + - `file_id: optional string` - - `beta_namespace_tool: object { description, name, tools, type }` + The identifier of an uploaded file that contains the screenshot. - Groups function/custom tools under a shared namespace. + - `image_url: optional string` - - `description: string` + The URL of the screenshot image. - A description of the namespace shown to the model. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `name: string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The namespace name used in tool calls (for example, `crm`). + - `"completed"` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `"incomplete"` - The function/custom tools available inside this namespace. + - `"failed"` - - `function: object { name, type, allowed_callers, 5 more }` + - `"in_progress"` - - `name: string` + - `type: "computer_call_output"` - - `type: "function"` + The type of the computer tool call output. Always `computer_call_output`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The tool invocation context(s). + The safety checks reported by the API that have been acknowledged by the + developer. - - `"direct"` + - `id: string` - - `"programmatic"` + The ID of the pending safety check. - - `defer_loading: optional boolean` + - `code: optional string` - Whether this function should be deferred and discovered via tool search. + The type of the pending safety check. - - `description: optional string` + - `message: optional string` - - `output_schema: optional map[unknown]` + Details about the pending safety check. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `agent: optional object { agent_name }` - - `parameters: optional unknown` + The agent that produced this item. - - `strict: optional boolean` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `created_by: optional string` - 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) + The identifier of the actor that created the item. - - `name: string` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - The name of the custom tool, used to identify it in tool calls. + 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). - - `type: "custom"` + - `id: string` - The type of the custom tool. Always `custom`. + The unique identifier of the reasoning content. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `summary: array of object { text, type }` - The tool invocation context(s). + Reasoning summary content. - - `defer_loading: optional boolean` + - `type: "reasoning"` - Whether this tool should be deferred and discovered via tool search. + The type of the object. Always `reasoning`. - - `description: optional string` + - `agent: optional object { agent_name }` - Optional description of the custom tool, used to provide more context. + The agent that produced this item. - - `format: optional object { type } or object { definition, syntax, type }` + - `content: optional array of object { text, type }` - The input format for the custom tool. Default is unconstrained text. + Reasoning text content. - - `type: "namespace"` + - `encrypted_content: optional string` - The type of the tool. Always `namespace`. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Hosted or BYOT tool search configuration for deferred tools. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "tool_search"` + - `program: object { id, call_id, code, 3 more }` - The type of the tool. Always `tool_search`. + - `id: string` - - `description: optional string` + The unique ID of the program item. - Description shown to the model for a client-executed tool search tool. + - `call_id: string` - - `execution: optional "server" or "client"` + The stable call ID of the program item. - Whether tool search is executed by the server or by the client. + - `code: string` - - `"server"` + The JavaScript source executed by programmatic tool calling. - - `"client"` + - `fingerprint: string` - - `parameters: optional unknown` + Opaque program replay fingerprint that must be round-tripped. - Parameter schema for a client-executed tool search tool. + - `type: "program"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The type of the item. Always `program`. - 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). + - `agent: optional object { agent_name }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The agent that produced this item. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `agent_name: string` - - `"web_search_preview"` + The canonical name of the agent that produced this item. - - `"web_search_preview_2025_03_11"` + - `program_output: object { id, call_id, result, 3 more }` - - `search_content_types: optional array of "text" or "image"` + - `id: string` - - `"text"` + The unique ID of the program output item. - - `"image"` + - `call_id: string` - - `search_context_size: optional "low" or "medium" or "high"` + The call ID of the program item. - 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. + - `result: string` - - `"low"` + The result produced by the program item. - - `"medium"` + - `status: "completed" or "incomplete"` - - `"high"` + The terminal status of the program output item. - - `user_location: optional object { type, city, country, 2 more }` + - `"completed"` - The user's location. + - `"incomplete"` - - `type: "approximate"` + - `type: "program_output"` - The type of location approximation. Always `approximate`. + The type of the item. Always `program_output`. - - `city: optional string` + - `agent: optional object { agent_name }` - Free text input for the city of the user, e.g. `San Francisco`. + The agent that produced this item. - - `country: optional string` + - `agent_name: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The canonical name of the agent that produced this item. - - `region: optional string` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - Free text input for the region of the user, e.g. `California`. + - `id: string` - - `timezone: optional string` + The unique ID of the tool search call item. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `arguments: unknown` - - `beta_apply_patch_tool: object { type, allowed_callers }` + Arguments used for the tool search call. - Allows the assistant to create, delete, or update files using unified diffs. + - `call_id: string` - - `type: "apply_patch"` + The unique ID of the tool search call generated by the model. - The type of the tool. Always `apply_patch`. + - `execution: "server" or "client"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Whether tool search was executed by the server or by the client. - The tool invocation context(s). + - `"server"` - - `"direct"` + - `"client"` - - `"programmatic"` + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "tool_search_output"` + The status of the tool search call item that was recorded. - The item type. Always `tool_search_output`. + - `"in_progress"` - - `id: optional string` + - `"completed"` - The unique ID of this tool search output. + - `"incomplete"` + + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -115287,11 +127061,21 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` The unique ID of the tool search call generated by the model. - - `execution: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -115299,9 +127083,9 @@ openai beta:responses compact \ - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -115309,15 +127093,9 @@ openai beta:responses compact \ - `"incomplete"` - - `additional_tools: object { role, tools, type, 2 more }` - - - `role: "developer"` - - The role that provided the additional tools. Only `developer` is supported. - - `tools: array of BetaTool` - A list of additional tools made available at this item. + The loaded tool definitions returned by tool search. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -115383,13 +127161,9 @@ openai beta:responses compact \ Allows the assistant to create, delete, or update files using unified diffs. - - `type: "additional_tools"` - - The item type. Always `additional_tools`. - - - `id: optional string` + - `type: "tool_search_output"` - The unique ID of this additional tools item. + The type of the item. Always `tool_search_output`. - `agent: optional object { agent_name }` @@ -115399,85 +127173,132 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `created_by: optional string` - 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). + The identifier of the actor that created the item. + + - `additional_tools: object { id, role, tools, 2 more }` - `id: string` - The unique identifier of the reasoning content. + The unique ID of the additional tools item. - - `summary: array of object { text, type }` + - `role: "unknown" or "user" or "assistant" or 5 more` - Reasoning summary content. + The role that provided the additional tools. - - `text: string` + - `"unknown"` - A summary of the reasoning output from the model so far. + - `"user"` - - `type: "summary_text"` + - `"assistant"` - The type of the object. Always `summary_text`. + - `"system"` - - `type: "reasoning"` + - `"critic"` - The type of the object. Always `reasoning`. + - `"discriminator"` - - `agent: optional object { agent_name }` + - `"developer"` - The agent that produced this item. + - `"tool"` - - `agent_name: string` + - `tools: array of BetaTool` - The canonical name of the agent that produced this item. + The additional tool definitions made available at this item. - - `content: optional array of object { text, type }` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - Reasoning text content. + 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). - - `text: string` + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - The reasoning text from the model. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "reasoning_text"` + - `beta_computer_tool: object { type }` - The type of the reasoning text. Always `reasoning_text`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `encrypted_content: optional string` + Allows the assistant to create, delete, or update files using unified diffs. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `type: "additional_tools"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the item. Always `additional_tools`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `agent: optional object { agent_name }` - - `"in_progress"` + The agent that produced this item. - - `"completed"` + - `agent_name: string` - - `"incomplete"` + The canonical name of the agent that produced this item. - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `id: string` + + The unique ID of the compaction item. + - `encrypted_content: string` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: "compaction"` The type of the item. Always `compaction`. - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -115486,6 +127307,10 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -115543,44 +127368,10 @@ openai beta:responses compact \ The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - - `logs: object { logs, type }` - - The logs output from the code interpreter. - - - `logs: string` - - The logs output from the code interpreter. - - - `type: "logs"` - - The type of the output. Always `logs`. - - - `image: object { type, url }` - - The image output from the code interpreter. - - - `type: "image"` - - The type of the output. Always `image`. - - - `url: string` - - The URL of the image output from the code interpreter. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"interpreting"` - - - `"failed"` - - `type: "code_interpreter_call"` The type of the code interpreter tool call. Always `code_interpreter_call`. @@ -115589,10 +127380,6 @@ openai beta:responses compact \ The agent that produced this item. - - `agent_name: string` - - The canonical name of the agent that produced this item. - - `local_shell_call: object { id, action, call_id, 3 more }` A tool call to run a command on the local shell. @@ -115689,9 +127476,13 @@ openai beta:responses compact \ - `"incomplete"` - - `shell_call: object { action, call_id, type, 5 more }` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - A tool representing a request to execute one or more shell commands. + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. - `action: object { commands, max_output_length, timeout_ms }` @@ -115699,27 +127490,53 @@ openai beta:responses compact \ - `commands: array of string` - Ordered shell commands for the execution environment to run. - - - `max_output_length: optional number` + - `max_output_length: number` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - - `timeout_ms: optional number` + - `timeout_ms: number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `type: "shell_call"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The type of the item. Always `shell_call`. + Represents the use of a local environment to perform shell actions. - - `id: optional string` + - `beta_response_local_environment: object { type }` - The unique ID of the shell tool call. Populated when this item is returned via API. + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. - `agent: optional object { agent_name }` @@ -115743,41 +127560,33 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `beta_local_environment: object { type, skills }` - - - `beta_container_reference: object { container_id, type }` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: optional string` - - `"in_progress"` + The ID of the entity that created this tool call. - - `"completed"` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `"incomplete"` + The output of a shell tool call that was emitted. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `id: string` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `max_output_length: number` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents - `outcome: object { type } or object { exit_code, type }` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `timeout: object { type }` @@ -115789,7 +127598,7 @@ openai beta:responses compact \ - `exit_code: number` - The exit code returned by the shell process. + Exit code from the shell process. - `type: "exit"` @@ -115797,19 +127606,29 @@ openai beta:responses compact \ - `stderr: string` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: string` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: "shell_call_output"` + - `created_by: optional string` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `id: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. - `agent: optional object { agent_name }` @@ -115833,25 +127652,17 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `max_output_length: optional number` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` @@ -115859,51 +127670,51 @@ openai beta:responses compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `create_file: object { diff, path, type }` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: string` - Unified diff content to apply when creating the file. + Diff to apply. - `path: string` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: "create_file"` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `delete_file: object { path, type }` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: string` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: "delete_file"` - The operation type. Always `delete_file`. + Delete the specified file. - `update_file: object { diff, path, type }` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: string` - Unified diff content to apply to the existing file. + Diff to apply. - `path: string` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: "update_file"` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `status: "in_progress" or "completed"` @@ -115917,10 +127728,6 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call`. - - `id: optional string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -115943,11 +127750,17 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. + - `created_by: optional string` - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + The ID of the entity that created this tool call. - The streamed output emitted by an apply patch tool call. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: string` @@ -115965,10 +127778,6 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call_output`. - - `id: optional string` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -115991,11 +127800,72 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. + - `created_by: optional string` + + The ID of the entity that created this tool call output. - `output: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. + + - `mcp_call: object { id, arguments, name, 7 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` - `mcp_list_tools: object { id, server_label, tools, 3 more }` @@ -116077,10 +127947,14 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` A response to an MCP approval request. + - `id: string` + + The unique ID of the approval response + - `approval_request_id: string` The ID of the approval request being answered. @@ -116093,10 +127967,6 @@ openai beta:responses compact \ The type of the item. Always `mcp_approval_response`. - - `id: optional string` - - The unique ID of the approval response - - `agent: optional object { agent_name }` The agent that produced this item. @@ -116109,54 +127979,54 @@ openai beta:responses compact \ Optional reason for the decision. - - `mcp_call: object { id, arguments, name, 7 more }` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - An invocation of a tool on an MCP server. + A call to a custom tool created by the model. - - `id: string` + - `call_id: string` - The unique ID of the tool call. + An identifier used to map this custom tool call to a tool call output. - - `arguments: string` + - `input: string` - A JSON string of the arguments passed to the tool. + The input for the custom tool call generated by the model. - `name: string` - The name of the tool that was run. + The name of the custom tool being called. - - `server_label: string` + - `type: "custom_tool_call"` - The label of the MCP server running the tool. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "mcp_call"` + - `id: optional string` - The type of the item. Always `mcp_call`. + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` The agent that produced this item. - - `agent_name: string` + - `caller: optional object { type } or object { caller_id, type }` - The canonical name of the agent that produced this item. + The execution context that produced this tool call. - - `approval_request_id: optional string` + - `namespace: optional string` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The namespace of the custom tool being called. - - `error: optional string` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - The error from the tool call, if any. + The output of a custom tool call from your code, being sent back to the model. - - `output: optional string` + - `id: string` - The output from the tool call. + The unique ID of the custom tool call output item. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -116164,286 +128034,905 @@ openai beta:responses compact \ - `"incomplete"` - - `"calling"` + - `created_by: optional string` - - `"failed"` + The identifier of the actor that created the item. - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `parallel_tool_calls: boolean` - The output of a custom tool call from your code, being sent back to the model. + Whether to allow the model to run tool calls in parallel. - - `call_id: string` + - `temperature: number` - The call ID, used to map this custom tool call output to a custom tool call. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `string output: string` + - `beta_tool_choice_options: "none" or "auto" or "required"` - A string of the output of the custom tool call. + Controls which (if any) tool is called by the model. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + `none` means the model will not call any tool and instead generates a message. - Text, image, or file output of the custom tool call. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + `required` means the model must call one or more tools. - A text input to the model. + - `"none"` - - `text: string` + - `"auto"` - The text input to the model. + - `"required"` - - `type: "input_text"` + - `beta_tool_choice_allowed: object { mode, tools, type }` - The type of the input item. Always `input_text`. + Constrains the tools available to the model to a pre-defined set. - - `prompt_cache_breakpoint: optional object { mode }` + - `mode: "auto" or "required"` - 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. + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `beta_tool_choice_types: object { type }` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `beta_tool_choice_function: object { name, type }` + + Use this option to force the model to call a specific function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `beta_tool_choice_mcp: object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `name: optional string` + + The name of the tool to call on the server. + + - `beta_tool_choice_custom: object { name, type }` + + Use this option to force the model to call a specific custom tool. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `BetaSpecificProgrammaticToolCallingParam: object { type }` + + - `beta_tool_choice_apply_patch: object { type }` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: "apply_patch"` + + The tool to call. Always `apply_patch`. + + - `beta_tool_choice_shell: object { type }` + + Forces the model to call the shell tool when a tool call is required. + + - `type: "shell"` + + The tool to call. Always `shell`. + + - `tools: array of BetaTool` + + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. + + - `beta_function_tool: object { name, parameters, strict, 5 more }` + + 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). + + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + + 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). + + - `beta_computer_tool: object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + + 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: object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `code_interpreter: object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `programmatic_tool_calling: object { type }` + + - `image_generation: object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `local_shell: object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `beta_function_shell_tool: object { type, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + + 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) + + - `beta_namespace_tool: object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `beta_tool_search_tool: object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `beta_apply_patch_tool: object { type, allowed_callers }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `top_p: number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `background: optional boolean` + + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + + - `completed_at: optional number` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: optional object { id }` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: string` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + + - `max_tool_calls: optional number` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: optional object { input, output }` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response input. + + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `error: object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response output. + + - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `error: object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `previous_response_id: optional string` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: optional object { id, variables, version }` + + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: string` + + The unique identifier of the prompt template to use. + + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `union_member_0: string` + + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + + A text input to the model. - `beta_response_input_image: object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `detail: "low" or "high" or "auto" or "original"` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A file input to the model. - - `type: "input_image"` + - `version: optional string` - The type of the input item. Always `input_image`. + Optional version of the prompt template. - - `file_id: optional string` + - `prompt_cache_key: optional string` - The ID of the file to be sent to the model. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `image_url: optional string` + - `prompt_cache_options: optional object { mode, ttl }` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: "implicit" or "explicit"` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: "30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: optional "in_memory" or "24h"` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `"in_memory"` + + - `"24h"` + + - `reasoning: optional object { context, effort, generate_summary, 2 more }` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: optional "auto" or "current_turn" or "all_turns"` + + Controls which reasoning items are rendered back to the model on later turns. + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` + + - `"current_turn"` + + - `"all_turns"` + + - `effort: optional "none" or "minimal" or "low" or 4 more` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `generate_summary: optional "auto" or "concise" or "detailed"` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `mode: optional string or "standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + + - `summary: optional "auto" or "concise" or "detailed"` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `safety_identifier: optional string` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: optional "completed" or "failed" or "in_progress" or 3 more` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + + - `text: optional object { format, verbosity }` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + + - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `text: object { type }` + + Default response format. Used to generate text responses. + + - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `schema: map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). + + - `json_object: object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `verbosity: optional "low" or "medium" or "high"` - - `prompt_cache_breakpoint: optional object { mode }` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. - 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. + - `"low"` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"medium"` - A file input to the model. + - `"high"` - - `type: "input_file"` + - `top_logprobs: optional number` - The type of the input item. Always `input_file`. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `detail: optional "auto" or "low" or "high"` + - `truncation: optional "auto" or "disabled"` - 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`. + The truncation strategy to use for the model response. - - `file_data: optional string` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The content of the file to be sent to the model. + - `"auto"` - - `file_id: optional string` + - `"disabled"` - The ID of the file to be sent to the model. + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `file_url: optional string` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The URL of the file to be sent to the model. + - `input_tokens: number` - - `filename: optional string` + The number of input tokens. - The name of the file to be sent to the model. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `prompt_cache_breakpoint: optional object { mode }` + A detailed breakdown of the input tokens. - 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. + - `cache_write_tokens: number` - - `type: "custom_tool_call_output"` + The number of input tokens that were written to the cache. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `cached_tokens: number` - - `id: optional string` + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - The unique ID of the custom tool call output in the OpenAI platform. + - `output_tokens: number` - - `agent: optional object { agent_name }` + The number of output tokens. - The agent that produced this item. + - `output_tokens_details: object { reasoning_tokens }` - - `agent_name: string` + A detailed breakdown of the output tokens. - The canonical name of the agent that produced this item. + - `reasoning_tokens: number` - - `caller: optional object { type } or object { caller_id, type }` + The number of reasoning tokens. - The execution context that produced this tool call. + - `total_tokens: number` - - `direct: object { type }` + The total number of tokens used. - - `program: object { caller_id, type }` + - `user: optional string` - - `caller_id: string` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The call ID of the program item that produced this tool call. + - `sequence_number: number` - - `type: "program"` + The sequence number for this event. - The caller type. Always `program`. + - `type: "response.completed"` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + The type of the event. Always `response.completed`. - A call to a custom tool created by the model. + - `agent: optional object { agent_name }` - - `call_id: string` + The agent that owns this multi-agent streaming event. - An identifier used to map this custom tool call to a tool call output. + - `agent_name: string` - - `input: string` + The canonical name of the agent that produced this item. - The input for the custom tool call generated by the model. + - `beta_response_content_part_added_event: object { content_index, item_id, output_index, 4 more }` - - `name: string` + Emitted when a new content part is added. - The name of the custom tool being called. + - `content_index: number` - - `type: "custom_tool_call"` + The index of the content part that was added. - The type of the custom tool call. Always `custom_tool_call`. + - `item_id: string` - - `id: optional string` + The ID of the output item that the content part was added to. - The unique ID of the custom tool call in the OpenAI platform. + - `output_index: number` - - `agent: optional object { agent_name }` + The index of the output item that the content part was added to. - The agent that produced this item. + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `agent_name: string` + The content part that was added. - The canonical name of the agent that produced this item. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `caller: optional object { type } or object { caller_id, type }` + A text output from the model. - The execution context that produced this tool call. + - `beta_response_output_refusal: object { refusal, type }` - - `direct: object { type }` + A refusal from the model. - - `program: object { caller_id, type }` + - `reasoning_text: object { text, type }` - - `caller_id: string` + Reasoning text from the model. - The call ID of the program item that produced this tool call. + - `text: string` - - `type: "program"` + The reasoning text from the model. - - `namespace: optional string` + - `type: "reasoning_text"` - The namespace of the custom tool being called. + The type of the reasoning text. Always `reasoning_text`. - - `compaction_trigger: object { type, agent }` + - `sequence_number: number` - Compacts the current context. Must be the final input item. + The sequence number of this event. - - `type: "compaction_trigger"` + - `type: "response.content_part.added"` - The type of the item. Always `compaction_trigger`. + The type of the event. Always `response.content_part.added`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `item_reference: object { id, agent, type }` + - `beta_response_content_part_done_event: object { content_index, item_id, output_index, 4 more }` - An internal identifier for an item to reference. + Emitted when a content part is done. - - `id: string` + - `content_index: number` - The ID of the item to reference. + The index of the content part that is done. - - `agent: optional object { agent_name }` + - `item_id: string` - The agent that produced this item. + The ID of the output item that the content part was added to. - - `agent_name: string` + - `output_index: number` - The canonical name of the agent that produced this item. + The index of the output item that the content part was added to. - - `type: optional "item_reference"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - The type of item to reference. Always `item_reference`. + The content part that is done. - - `"item_reference"` + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `program: object { id, call_id, code, 3 more }` + A text output from the model. - - `id: string` + - `beta_response_output_refusal: object { refusal, type }` - The unique ID of this program item. + A refusal from the model. - - `call_id: string` + - `reasoning_text: object { text, type }` - The stable call ID of the program item. + Reasoning text from the model. - - `code: string` + - `text: string` - The JavaScript source executed by programmatic tool calling. + The reasoning text from the model. - - `fingerprint: string` + - `type: "reasoning_text"` - Opaque program replay fingerprint that must be round-tripped. + The type of the reasoning text. Always `reasoning_text`. - - `type: "program"` + - `sequence_number: number` - The item type. Always `program`. + The sequence number of this event. + + - `type: "response.content_part.done"` + + The type of the event. Always `response.content_part.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `program_output: object { id, call_id, result, 3 more }` - - - `id: string` - - The unique ID of this program output item. + - `beta_response_created_event: object { response, sequence_number, type, agent }` - - `call_id: string` + An event that is emitted when a response is created. - The call ID of the program item. + - `response: object { id, created_at, error, 31 more }` - - `result: string` + The response that was created. - The result produced by the program item. + - `id: string` - - `status: "completed" or "incomplete"` + Unique identifier for this Response. - The terminal status of the program output. + - `created_at: number` - - `"completed"` + Unix timestamp (in seconds) of when this Response was created. - - `"incomplete"` + - `error: object { code, message }` - - `type: "program_output"` + An error object returned when the model fails to generate a Response. - The item type. Always `program_output`. + - `incomplete_details: object { reason }` - - `agent: optional object { agent_name }` + Details about why the response is incomplete. - The agent that produced this item. + - `instructions: string or array of BetaResponseInputItem` - - `agent_name: string` + A system (or developer) message inserted into the model's context. - The canonical name of the agent that produced this item. + When using 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. - `metadata: map[string]` @@ -116461,2271 +128950,2445 @@ openai beta:responses compact \ characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - - `"gpt-5.6-sol"` - - - `"gpt-5.6-terra"` - - - `"gpt-5.6-luna"` - - - `"gpt-5.4"` - - - `"gpt-5.4-mini"` - - - `"gpt-5.4-nano"` - - - `"gpt-5.4-mini-2026-03-17"` - - - `"gpt-5.4-nano-2026-03-17"` - - - `"gpt-5.3-chat-latest"` - - - `"gpt-5.2"` - - - `"gpt-5.2-2025-12-11"` - - - `"gpt-5.2-chat-latest"` - - - `"gpt-5.2-pro"` + - `object: "response"` - - `"gpt-5.2-pro-2025-12-11"` + The object type of this resource - always set to `response`. - - `"gpt-5.1"` + - `output: array of BetaResponseOutputItem` - - `"gpt-5.1-2025-11-13"` + An array of content items generated by the model. - - `"gpt-5.1-codex"` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `"gpt-5.1-mini"` + - `parallel_tool_calls: boolean` - - `"gpt-5.1-chat-latest"` + Whether to allow the model to run tool calls in parallel. - - `"gpt-5"` + - `temperature: number` - - `"gpt-5-mini"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `"gpt-5-nano"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `"gpt-5-2025-08-07"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `"gpt-5-mini-2025-08-07"` + - `tools: array of BetaTool` - - `"gpt-5-nano-2025-08-07"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"gpt-5-chat-latest"` + We support the following categories of tools: - - `"gpt-4.1"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"gpt-4.1-mini"` + - `top_p: number` - - `"gpt-4.1-nano"` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `"gpt-4.1-2025-04-14"` + We generally recommend altering this or `temperature` but not both. - - `"gpt-4.1-mini-2025-04-14"` + - `background: optional boolean` - - `"gpt-4.1-nano-2025-04-14"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `"o4-mini"` + - `completed_at: optional number` - - `"o4-mini-2025-04-16"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"o3"` + - `conversation: optional object { id }` - - `"o3-2025-04-16"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `"o3-mini"` + - `max_output_tokens: optional number` - - `"o3-mini-2025-01-31"` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `"o1"` + - `max_tool_calls: optional number` - - `"o1-2024-12-17"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `"o1-preview"` + - `moderation: optional object { input, output }` - - `"o1-preview-2024-09-12"` + Moderation results for the response input and output, if moderated completions were requested. - - `"o1-mini"` + - `previous_response_id: optional string` - - `"o1-mini-2024-09-12"` + 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`. - - `"gpt-4o"` + - `prompt: optional object { id, variables, version }` - - `"gpt-4o-2024-11-20"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `"gpt-4o-2024-08-06"` + - `prompt_cache_key: optional string` - - `"gpt-4o-2024-05-13"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - `"gpt-4o-audio-preview"` + - `prompt_cache_options: optional object { mode, ttl }` - - `"gpt-4o-audio-preview-2024-10-01"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `"gpt-4o-audio-preview-2024-12-17"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `"gpt-4o-audio-preview-2025-06-03"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `"gpt-4o-mini-audio-preview"` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"gpt-4o-search-preview"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `"gpt-4o-mini-search-preview"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `"gpt-4o-search-preview-2025-03-11"` + **gpt-5 and o-series models only** - - `"gpt-4o-mini-search-preview-2025-03-11"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `"chatgpt-4o-latest"` + - `safety_identifier: optional string` - - `"codex-mini-latest"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"gpt-4o-mini"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `"gpt-4o-mini-2024-07-18"` + Specifies the processing type used for serving the request. - - `"gpt-4-turbo"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `"gpt-4-turbo-2024-04-09"` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `"gpt-4-0125-preview"` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `"gpt-4-turbo-preview"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"gpt-4-1106-preview"` + - `text: optional object { format, verbosity }` - - `"gpt-4-vision-preview"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"gpt-4"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `"gpt-4-0314"` + - `top_logprobs: optional number` - - `"gpt-4-0613"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `"gpt-4-32k"` + - `truncation: optional "auto" or "disabled"` - - `"gpt-4-32k-0314"` + The truncation strategy to use for the model response. - - `"gpt-4-32k-0613"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `"gpt-3.5-turbo"` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `"gpt-3.5-turbo-16k"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `"gpt-3.5-turbo-0301"` + - `user: optional string` - - `"gpt-3.5-turbo-0613"` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `"gpt-3.5-turbo-1106"` + - `sequence_number: number` - - `"gpt-3.5-turbo-0125"` + The sequence number for this event. - - `"gpt-3.5-turbo-16k-0613"` + - `type: "response.created"` - - `"o1-pro"` + The type of the event. Always `response.created`. - - `"o1-pro-2025-03-19"` + - `agent: optional object { agent_name }` - - `"o3-pro"` + The agent that owns this multi-agent streaming event. - - `"o3-pro-2025-06-10"` + - `agent_name: string` - - `"o3-deep-research"` + The canonical name of the agent that produced this item. - - `"o3-deep-research-2025-06-26"` + - `beta_response_error_event: object { code, message, param, 3 more }` - - `"o4-mini-deep-research"` + Emitted when an error occurs. - - `"o4-mini-deep-research-2025-06-26"` + - `code: string` - - `"computer-use-preview"` + The error code. - - `"computer-use-preview-2025-03-11"` + - `message: string` - - `"gpt-5-codex"` + The error message. - - `"gpt-5-pro"` + - `param: string` - - `"gpt-5-pro-2025-10-06"` + The error parameter. - - `"gpt-5.1-codex-max"` + - `sequence_number: number` - - `object: "response"` + The sequence number of this event. - The object type of this resource - always set to `response`. + - `type: "error"` - - `output: array of BetaResponseOutputItem` + The type of the event. Always `error`. - An array of content items generated by the model. + - `agent: optional object { agent_name }` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The agent that owns this multi-agent streaming event. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `agent_name: string` - An output message from the model. + The canonical name of the agent that produced this item. - - `id: string` + - `beta_response_file_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - The unique ID of the output message. + Emitted when a file search call is completed (results found). - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `item_id: string` - The content of the output message. + The ID of the output item that the file search call is initiated. - - `role: "assistant"` + - `output_index: number` - The role of the output message. Always `assistant`. + The index of the output item that the file search call is initiated. - - `status: "in_progress" or "completed" or "incomplete"` + - `sequence_number: number` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The sequence number of this event. - - `type: "message"` + - `type: "response.file_search_call.completed"` - The type of the output message. Always `message`. + The type of the event. Always `response.file_search_call.completed`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - - `phase: optional "commentary"` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `beta_response_file_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - 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. + Emitted when a file search call is initiated. - - `id: string` + - `item_id: string` - The unique ID of the file search tool call. + The ID of the output item that the file search call is initiated. - - `queries: array of string` + - `output_index: number` - The queries used to search for files. + The index of the output item that the file search call is initiated. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `sequence_number: number` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The sequence number of this event. - - `type: "file_search_call"` + - `type: "response.file_search_call.in_progress"` - The type of the file search tool call. Always `file_search_call`. + The type of the event. Always `response.file_search_call.in_progress`. - `agent: optional object { agent_name }` - The agent that produced this item. - - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. + The agent that owns this multi-agent streaming event. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `agent_name: string` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The canonical name of the agent that produced this item. - - `arguments: string` + - `beta_response_file_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` - A JSON string of the arguments to pass to the function. + Emitted when a file search is currently searching. - - `call_id: string` + - `item_id: string` - The unique ID of the function tool call generated by the model. + The ID of the output item that the file search call is initiated. - - `name: string` + - `output_index: number` - The name of the function to run. + The index of the output item that the file search call is searching. - - `type: "function_call"` + - `sequence_number: number` - The type of the function tool call. Always `function_call`. + The sequence number of this event. - - `id: optional string` + - `type: "response.file_search_call.searching"` - The unique ID of the function tool call. + The type of the event. Always `response.file_search_call.searching`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - - `caller: optional object { type } or object { caller_id, type }` + - `agent_name: string` - The execution context that produced this tool call. + The canonical name of the agent that produced this item. - - `namespace: optional string` + - `beta_response_function_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` - The namespace of the function to run. + Emitted when there is a partial function-call arguments delta. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `delta: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The function-call arguments delta that is added. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `item_id: string` - - `id: string` + The ID of the output item that the function-call arguments delta is added to. - The unique ID of the function call tool output. + - `output_index: number` - - `call_id: string` + The index of the output item that the function-call arguments delta is added to. - The unique ID of the function tool call generated by the model. + - `sequence_number: number` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The sequence number of this event. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `type: "response.function_call_arguments.delta"` - - `string output: string` + The type of the event. Always `response.function_call_arguments.delta`. - A string of the output of the function call. + - `agent: optional object { agent_name }` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The agent that owns this multi-agent streaming event. - Text, image, or file output of the function call. + - `agent_name: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The canonical name of the agent that produced this item. - A text input to the model. + - `beta_response_function_call_arguments_done_event: object { arguments, item_id, name, 4 more }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + Emitted when function-call arguments are finalized. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `arguments: string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The function-call arguments. - A file input to the model. + - `item_id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The ID of the item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `name: string` - - `"in_progress"` + The name of the function that was called. - - `"completed"` + - `output_index: number` - - `"incomplete"` + The index of the output item. - - `type: "function_call_output"` + - `sequence_number: number` - The type of the function tool call output. Always `function_call_output`. + The sequence number of this event. + + - `type: "response.function_call_arguments.done"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` + - `beta_response_in_progress_event: object { response, sequence_number, type, agent }` - - `program: object { caller_id, type }` + Emitted when the response is in progress. - - `caller_id: string` + - `response: object { id, created_at, error, 31 more }` - The call ID of the program item that produced this tool call. + The response that is in progress. - - `type: "program"` + - `id: string` - The caller type. Always `program`. + Unique identifier for this Response. - - `created_by: optional string` + - `created_at: number` - The identifier of the actor that created the item. + Unix timestamp (in seconds) of when this Response was created. - - `agent_message: object { id, author, content, 3 more }` + - `error: object { code, message }` - - `id: string` + An error object returned when the model fails to generate a Response. - The unique ID of the agent message. + - `incomplete_details: object { reason }` - - `author: string` + Details about why the response is incomplete. - The sending agent identity. + - `instructions: string or array of BetaResponseInputItem` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + A system (or developer) message inserted into the model's context. - Encrypted content sent between agents. + When using 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. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `metadata: map[string]` - A text input to the model. + 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. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A text output from the model. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `text: object { text, type }` + Model ID used to generate the response, like `gpt-4o` 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. - A text content. + - `object: "response"` - - `text: string` + The object type of this resource - always set to `response`. - - `type: "text"` + - `output: array of BetaResponseOutputItem` - - `summary_text: object { text, type }` + An array of content items generated by the model. - A summary text from the model. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `text: string` + - `parallel_tool_calls: boolean` - A summary of the reasoning output from the model so far. + Whether to allow the model to run tool calls in parallel. - - `type: "summary_text"` + - `temperature: number` - The type of the object. Always `summary_text`. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `reasoning_text: object { text, type }` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - Reasoning text from the model. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `text: string` + - `tools: array of BetaTool` - The reasoning text from the model. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `type: "reasoning_text"` + We support the following categories of tools: - The type of the reasoning text. Always `reasoning_text`. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `beta_response_output_refusal: object { refusal, type }` + - `top_p: number` - A refusal from the model. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + We generally recommend altering this or `temperature` but not both. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `background: optional boolean` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - A screenshot of a computer. + - `completed_at: optional number` - - `detail: "low" or "high" or "auto" or "original"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `conversation: optional object { id }` - - `"low"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `"high"` + - `max_output_tokens: optional number` - - `"auto"` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `"original"` + - `max_tool_calls: optional number` - - `file_id: string` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - The identifier of an uploaded file that contains the screenshot. + - `moderation: optional object { input, output }` - - `image_url: string` + Moderation results for the response input and output, if moderated completions were requested. - The URL of the screenshot image. + - `previous_response_id: optional string` - - `type: "computer_screenshot"` + 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`. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `prompt: optional object { id, variables, version }` - - `prompt_cache_breakpoint: optional object { mode }` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - 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. + - `prompt_cache_key: optional string` - - `mode: "explicit"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - The breakpoint mode. Always `explicit`. + - `prompt_cache_options: optional object { mode, ttl }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - A file input to the model. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `encrypted_content: object { encrypted_content, type }` + Deprecated. Use `prompt_cache_options.ttl` instead. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `encrypted_content: string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - Opaque encrypted content. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `type: "encrypted_content"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - The type of the input item. Always `encrypted_content`. + **gpt-5 and o-series models only** - - `recipient: string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The destination agent identity. + - `safety_identifier: optional string` - - `type: "agent_message"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - The type of the item. Always `agent_message`. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `agent: optional object { agent_name }` + Specifies the processing type used for serving the request. - The agent that produced this item. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `agent_name: string` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The canonical name of the agent that produced this item. + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `multi_agent_call: object { id, action, arguments, 3 more }` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `id: string` + - `text: optional object { format, verbosity }` - The unique ID of the multi-agent call item. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - The multi-agent action to execute. + - `top_logprobs: optional number` - - `"spawn_agent"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `"interrupt_agent"` + - `truncation: optional "auto" or "disabled"` - - `"list_agents"` + The truncation strategy to use for the model response. - - `"send_message"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `"followup_task"` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `"wait_agent"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `arguments: string` + - `user: optional string` - The JSON string of arguments generated for the action. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `call_id: string` + - `sequence_number: number` - The unique ID linking this call to its output. + The sequence number of this event. - - `type: "multi_agent_call"` + - `type: "response.in_progress"` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the event. Always `response.in_progress`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `beta_response_failed_event: object { response, sequence_number, type, agent }` + + An event that is emitted when a response fails. + + - `response: object { id, created_at, error, 31 more }` + + The response that failed. - `id: string` - The unique ID of the multi-agent call output item. + Unique identifier for this Response. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `created_at: number` - The multi-agent action that produced this result. + Unix timestamp (in seconds) of when this Response was created. - - `"spawn_agent"` + - `error: object { code, message }` - - `"interrupt_agent"` + An error object returned when the model fails to generate a Response. - - `"list_agents"` + - `incomplete_details: object { reason }` - - `"send_message"` + Details about why the response is incomplete. - - `"followup_task"` + - `instructions: string or array of BetaResponseInputItem` - - `"wait_agent"` + A system (or developer) message inserted into the model's context. - - `call_id: string` + When using 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. - The unique ID of the multi-agent call. + - `metadata: map[string]` - - `output: array of BetaResponseOutputText` + 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. - Text output returned by the multi-agent action. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The annotations of the text output. + Model ID used to generate the response, like `gpt-4o` 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. - - `text: string` + - `object: "response"` - The text output from the model. + The object type of this resource - always set to `response`. - - `type: "output_text"` + - `output: array of BetaResponseOutputItem` - The type of the output text. Always `output_text`. + An array of content items generated by the model. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `type: "multi_agent_call_output"` + - `parallel_tool_calls: boolean` - The type of the multi-agent result. Always `multi_agent_call_output`. + Whether to allow the model to run tool calls in parallel. - - `agent: optional object { agent_name }` + - `temperature: number` - The agent that produced this item. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `agent_name: string` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The canonical name of the agent that produced this item. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `tools: array of BetaTool` - 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. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `id: string` + We support the following categories of tools: - The unique ID of the web search tool call. + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `top_p: number` - 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). + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `status: "in_progress" or "searching" or "completed" or "failed"` + We generally recommend altering this or `temperature` but not both. - The status of the web search tool call. + - `background: optional boolean` - - `type: "web_search_call"` + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - The type of the web search tool call. Always `web_search_call`. + - `completed_at: optional number` - - `agent: optional object { agent_name }` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - The agent that produced this item. + - `conversation: optional object { id }` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - 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. + - `max_output_tokens: optional number` - - `id: string` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - The unique ID of the computer call. + - `max_tool_calls: optional number` - - `call_id: string` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - An identifier used when responding to the tool call with output. + - `moderation: optional object { input, output }` - - `pending_safety_checks: array of object { id, code, message }` + Moderation results for the response input and output, if moderated completions were requested. - The pending safety checks for the computer call. + - `previous_response_id: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + 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`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `prompt: optional object { id, variables, version }` - - `type: "computer_call"` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The type of the computer call. Always `computer_call`. + - `prompt_cache_key: optional string` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - A click action. + - `prompt_cache_options: optional object { mode, ttl }` - - `actions: optional array of BetaComputerAction` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `agent: optional object { agent_name }` + Deprecated. Use `prompt_cache_options.ttl` instead. - The agent that produced this item. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `id: string` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The unique ID of the computer call tool output. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `call_id: string` + **gpt-5 and o-series models only** - The ID of the computer tool call that produced the output. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `output: object { type, file_id, image_url }` + - `safety_identifier: optional string` - A computer screenshot image used with the computer use tool. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `type: "computer_screenshot"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Specifies the processing type used for serving the request. - - `file_id: optional string` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The identifier of an uploaded file that contains the screenshot. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `image_url: optional string` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - The URL of the screenshot image. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `text: optional object { format, verbosity }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"completed"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `"incomplete"` + - `top_logprobs: optional number` - - `"failed"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `"in_progress"` + - `truncation: optional "auto" or "disabled"` - - `type: "computer_call_output"` + The truncation strategy to use for the model response. - The type of the computer tool call output. Always `computer_call_output`. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - The safety checks reported by the API that have been acknowledged by the - developer. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `id: string` + - `user: optional string` - The ID of the pending safety check. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `code: optional string` + - `sequence_number: number` - The type of the pending safety check. + The sequence number of this event. - - `message: optional string` + - `type: "response.failed"` - Details about the pending safety check. + The type of the event. Always `response.failed`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `created_by: optional string` + - `beta_response_incomplete_event: object { response, sequence_number, type, agent }` - The identifier of the actor that created the item. + An event that is emitted when a response finishes as incomplete. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `response: object { id, created_at, error, 31 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The response that was incomplete. - `id: string` - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - Reasoning summary content. + Unique identifier for this Response. - - `type: "reasoning"` + - `created_at: number` - The type of the object. Always `reasoning`. + Unix timestamp (in seconds) of when this Response was created. - - `agent: optional object { agent_name }` + - `error: object { code, message }` - The agent that produced this item. + An error object returned when the model fails to generate a Response. - - `content: optional array of object { text, type }` + - `incomplete_details: object { reason }` - Reasoning text content. + Details about why the response is incomplete. - - `encrypted_content: optional string` + - `instructions: string or array of BetaResponseInputItem` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + A system (or developer) message inserted into the model's context. - - `status: optional "in_progress" or "completed" or "incomplete"` + When using 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. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `metadata: map[string]` - - `program: object { id, call_id, code, 3 more }` + 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. - - `id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The unique ID of the program item. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `call_id: string` + Model ID used to generate the response, like `gpt-4o` 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. - The stable call ID of the program item. + - `object: "response"` - - `code: string` + The object type of this resource - always set to `response`. - The JavaScript source executed by programmatic tool calling. + - `output: array of BetaResponseOutputItem` - - `fingerprint: string` + An array of content items generated by the model. - Opaque program replay fingerprint that must be round-tripped. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `type: "program"` + - `parallel_tool_calls: boolean` - The type of the item. Always `program`. + Whether to allow the model to run tool calls in parallel. - - `agent: optional object { agent_name }` + - `temperature: number` - The agent that produced this item. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `agent_name: string` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The canonical name of the agent that produced this item. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `program_output: object { id, call_id, result, 3 more }` + - `tools: array of BetaTool` - - `id: string` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - The unique ID of the program output item. + We support the following categories of tools: - - `call_id: string` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - The call ID of the program item. + - `top_p: number` - - `result: string` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - The result produced by the program item. + We generally recommend altering this or `temperature` but not both. - - `status: "completed" or "incomplete"` + - `background: optional boolean` - The terminal status of the program output item. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `"completed"` + - `completed_at: optional number` - - `"incomplete"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `type: "program_output"` + - `conversation: optional object { id }` - The type of the item. Always `program_output`. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `agent: optional object { agent_name }` + - `max_output_tokens: optional number` - The agent that produced this item. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `agent_name: string` + - `max_tool_calls: optional number` - The canonical name of the agent that produced this item. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `moderation: optional object { input, output }` - - `id: string` + Moderation results for the response input and output, if moderated completions were requested. - The unique ID of the tool search call item. + - `previous_response_id: optional string` - - `arguments: unknown` + 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`. - Arguments used for the tool search call. + - `prompt: optional object { id, variables, version }` - - `call_id: string` + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - The unique ID of the tool search call generated by the model. + - `prompt_cache_key: optional string` - - `execution: "server" or "client"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - Whether tool search was executed by the server or by the client. + - `prompt_cache_options: optional object { mode, ttl }` - - `"server"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `"client"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `status: "in_progress" or "completed" or "incomplete"` + Deprecated. Use `prompt_cache_options.ttl` instead. - The status of the tool search call item that was recorded. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `"in_progress"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `"completed"` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `"incomplete"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `type: "tool_search_call"` + **gpt-5 and o-series models only** - The type of the item. Always `tool_search_call`. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `agent: optional object { agent_name }` + - `safety_identifier: optional string` - The agent that produced this item. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `agent_name: string` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - The canonical name of the agent that produced this item. + Specifies the processing type used for serving the request. - - `created_by: optional string` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - The identifier of the actor that created the item. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `id: string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The unique ID of the tool search output item. + - `text: optional object { format, verbosity }` - - `call_id: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The unique ID of the tool search call generated by the model. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `execution: "server" or "client"` + - `top_logprobs: optional number` - Whether tool search was executed by the server or by the client. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `"server"` + - `truncation: optional "auto" or "disabled"` - - `"client"` + The truncation strategy to use for the model response. - - `status: "in_progress" or "completed" or "incomplete"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The status of the tool search output item that was recorded. + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `"in_progress"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `"completed"` + - `user: optional string` - - `"incomplete"` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - - `tools: array of BetaTool` + - `sequence_number: number` - The loaded tool definitions returned by tool search. + The sequence number of this event. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `type: "response.incomplete"` - 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). + The type of the event. Always `response.incomplete`. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `agent: optional object { agent_name }` - 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). + The agent that owns this multi-agent streaming event. - - `beta_computer_tool: object { type }` + - `agent_name: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The canonical name of the agent that produced this item. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `beta_response_output_item_added_event: object { item, output_index, sequence_number, 2 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Emitted when a new output item is added. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` - 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). + The output item that was added. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `beta_response_output_message: object { id, content, role, 4 more }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + An output message from the model. - - `code_interpreter: object { container, type, allowed_callers }` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - A tool that runs Python code to help generate a response to a prompt. + 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. - - `programmatic_tool_calling: object { type }` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `image_generation: object { type, action, background, 9 more }` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - A tool that generates images using the GPT image models. + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `local_shell: object { type }` + - `agent_message: object { id, author, content, 3 more }` - A tool that allows the model to execute shell commands in a local environment. + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - A tool that allows the model to execute shell commands. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + 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. - 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) + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `beta_namespace_tool: object { description, name, tools, type }` + 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. - Groups function/custom tools under a shared namespace. + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - Hosted or BYOT tool search configuration for deferred tools. + 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). - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `program: object { id, call_id, code, 3 more }` - 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). + - `program_output: object { id, call_id, result, 3 more }` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - Allows the assistant to create, delete, or update files using unified diffs. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `type: "tool_search_output"` + - `additional_tools: object { id, role, tools, 2 more }` - The type of the item. Always `tool_search_output`. + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - `agent: optional object { agent_name }` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The agent that produced this item. + - `image_generation_call: object { id, result, status, 2 more }` - - `agent_name: string` + An image generation request made by the model. - The canonical name of the agent that produced this item. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `created_by: optional string` + A tool call to run code. - The identifier of the actor that created the item. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `additional_tools: object { id, role, tools, 2 more }` + A tool call to run a command on the local shell. - - `id: string` + - `local_shell_call_output: object { id, output, type, 2 more }` - The unique ID of the additional tools item. + The output of a local shell tool call. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - The role that provided the additional tools. + A tool call that executes one or more shell commands in a managed environment. - - `"unknown"` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `"user"` + The output of a shell tool call that was emitted. - - `"assistant"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"system"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `"critic"` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `"discriminator"` + The output emitted by an apply patch tool call. - - `"developer"` + - `mcp_call: object { id, arguments, name, 7 more }` - - `"tool"` + An invocation of a tool on an MCP server. - - `tools: array of BetaTool` + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - The additional tool definitions made available at this item. + A list of tools available on an MCP server. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - 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). + A request for human approval of a tool invocation. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - 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). + A response to an MCP approval request. - - `beta_computer_tool: object { type }` + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A call to a custom tool created by the model. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output of a custom tool call from your code, being sent back to the model. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `output_index: number` - 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). + The index of the output item that was added. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `sequence_number: number` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The sequence number of this event. - - `code_interpreter: object { container, type, allowed_callers }` + - `type: "response.output_item.added"` - A tool that runs Python code to help generate a response to a prompt. + The type of the event. Always `response.output_item.added`. - - `programmatic_tool_calling: object { type }` + - `agent: optional object { agent_name }` - - `image_generation: object { type, action, background, 9 more }` + The agent that owns this multi-agent streaming event. - A tool that generates images using the GPT image models. + - `agent_name: string` - - `local_shell: object { type }` + The canonical name of the agent that produced this item. - A tool that allows the model to execute shell commands in a local environment. + - `beta_response_output_item_done_event: object { item, output_index, sequence_number, 2 more }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + Emitted when an output item is marked done. - A tool that allows the model to execute shell commands. + - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The output item that was marked done. - 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) + - `beta_response_output_message: object { id, content, role, 4 more }` - - `beta_namespace_tool: object { description, name, tools, type }` + An output message from the model. - Groups function/custom tools under a shared namespace. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + 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. - Hosted or BYOT tool search configuration for deferred tools. + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - 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). + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `agent_message: object { id, author, content, 3 more }` - Allows the assistant to create, delete, or update files using unified diffs. + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `type: "additional_tools"` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - The type of the item. Always `additional_tools`. + - `beta_response_function_web_search: object { id, action, status, 2 more }` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - - `id: string` + - `program: object { id, call_id, code, 3 more }` - The unique ID of the compaction item. + - `program_output: object { id, call_id, result, 3 more }` - - `encrypted_content: string` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - The encrypted content that was produced by compaction. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `type: "compaction"` + - `additional_tools: object { id, role, tools, 2 more }` - The type of the item. Always `compaction`. + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - - `agent: optional object { agent_name }` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The agent that produced this item. + - `image_generation_call: object { id, result, status, 2 more }` - - `agent_name: string` + An image generation request made by the model. - The canonical name of the agent that produced this item. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `created_by: optional string` + A tool call to run code. - The identifier of the actor that created the item. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `image_generation_call: object { id, result, status, 2 more }` + A tool call to run a command on the local shell. - An image generation request made by the model. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `id: string` + The output of a local shell tool call. - The unique ID of the image generation call. + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - `result: string` + A tool call that executes one or more shell commands in a managed environment. - The generated image encoded in base64. + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The output of a shell tool call that was emitted. - The status of the image generation call. + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"in_progress"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `"completed"` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - - `"generating"` + The output emitted by an apply patch tool call. - - `"failed"` + - `mcp_call: object { id, arguments, name, 7 more }` - - `type: "image_generation_call"` + An invocation of a tool on an MCP server. - The type of the image generation call. Always `image_generation_call`. + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `agent: optional object { agent_name }` + A list of tools available on an MCP server. - The agent that produced this item. + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `agent_name: string` + A request for human approval of a tool invocation. - The canonical name of the agent that produced this item. + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + A response to an MCP approval request. - A tool call to run code. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `id: string` + A call to a custom tool created by the model. - The unique ID of the code interpreter tool call. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `code: string` + The output of a custom tool call from your code, being sent back to the model. - The code to run, or null if not available. + - `output_index: number` - - `container_id: string` + The index of the output item that was marked done. - The ID of the container used to run the code. + - `sequence_number: number` - - `outputs: array of object { logs, type } or object { type, url }` + The sequence number of this event. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `type: "response.output_item.done"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The type of the event. Always `response.output_item.done`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `agent: optional object { agent_name }` - - `type: "code_interpreter_call"` + The agent that owns this multi-agent streaming event. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `agent_name: string` - - `agent: optional object { agent_name }` + The canonical name of the agent that produced this item. - The agent that produced this item. + - `beta_response_reasoning_summary_part_added_event: object { item_id, output_index, part, 4 more }` - - `local_shell_call: object { id, action, call_id, 3 more }` + Emitted when a new reasoning summary part is added. - A tool call to run a command on the local shell. + - `item_id: string` - - `id: string` + The ID of the item this summary part is associated with. - The unique ID of the local shell call. + - `output_index: number` - - `action: object { command, env, type, 3 more }` + The index of the output item this summary part is associated with. - Execute a shell command on the server. + - `part: object { text, type }` - - `command: array of string` + The summary part that was added. - The command to run. + - `text: string` - - `env: map[string]` + The text of the summary part. - Environment variables to set for the command. + - `type: "summary_text"` - - `type: "exec"` + The type of the summary part. Always `summary_text`. - The type of the local shell action. Always `exec`. + - `sequence_number: number` - - `timeout_ms: optional number` + The sequence number of this event. - Optional timeout in milliseconds for the command. + - `summary_index: number` - - `user: optional string` + The index of the summary part within the reasoning summary. - Optional user to run the command as. + - `type: "response.reasoning_summary_part.added"` - - `working_directory: optional string` + The type of the event. Always `response.reasoning_summary_part.added`. - Optional working directory to run the command in. + - `agent: optional object { agent_name }` - - `call_id: string` + The agent that owns this multi-agent streaming event. - The unique ID of the local shell tool call generated by the model. + - `agent_name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The canonical name of the agent that produced this item. - The status of the local shell call. + - `beta_response_reasoning_summary_part_done_event: object { item_id, output_index, part, 5 more }` - - `"in_progress"` + Emitted when a reasoning summary part is completed. - - `"completed"` + - `item_id: string` - - `"incomplete"` + The ID of the item this summary part is associated with. - - `type: "local_shell_call"` + - `output_index: number` - The type of the local shell call. Always `local_shell_call`. + The index of the output item this summary part is associated with. - - `agent: optional object { agent_name }` + - `part: object { text, type }` - The agent that produced this item. + The completed summary part. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + The text of the summary part. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `type: "summary_text"` - The output of a local shell tool call. + The type of the summary part. Always `summary_text`. - - `id: string` + - `sequence_number: number` - The unique ID of the local shell tool call generated by the model. + The sequence number of this event. - - `output: string` + - `summary_index: number` - A JSON string of the output of the local shell tool call. + The index of the summary part within the reasoning summary. - - `type: "local_shell_call_output"` + - `type: "response.reasoning_summary_part.done"` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the event. Always `response.reasoning_summary_part.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` + - `status: optional "incomplete"` - - `"completed"` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - `"incomplete"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `beta_response_reasoning_summary_text_delta_event: object { delta, item_id, output_index, 4 more }` - A tool call that executes one or more shell commands in a managed environment. + Emitted when a delta is added to a reasoning summary text. - - `id: string` + - `delta: string` - The unique ID of the shell tool call. Populated when this item is returned via API. + The text delta that was added to the summary. - - `action: object { commands, max_output_length, timeout_ms }` + - `item_id: string` - The shell commands and limits that describe how to run the tool call. + The ID of the item this summary text delta is associated with. - - `commands: array of string` + - `output_index: number` - - `max_output_length: number` + The index of the output item this summary text delta is associated with. - Optional maximum number of characters to return from each command. + - `sequence_number: number` - - `timeout_ms: number` + The sequence number of this event. - Optional timeout in milliseconds for the commands. + - `summary_index: number` - - `call_id: string` + The index of the summary part within the reasoning summary. - The unique ID of the shell tool call generated by the model. + - `type: "response.reasoning_summary_text.delta"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The type of the event. Always `response.reasoning_summary_text.delta`. - Represents the use of a local environment to perform shell actions. + - `agent: optional object { agent_name }` - - `beta_response_local_environment: object { type }` + The agent that owns this multi-agent streaming event. - Represents the use of a local environment to perform shell actions. + - `agent_name: string` - - `type: "local"` + The canonical name of the agent that produced this item. - The environment type. Always `local`. + - `beta_response_reasoning_summary_text_done_event: object { item_id, output_index, sequence_number, 4 more }` - - `beta_response_container_reference: object { container_id, type }` + Emitted when a reasoning summary text is completed. - Represents a container created with /v1/containers. + - `item_id: string` - - `container_id: string` + The ID of the item this summary text is associated with. - - `type: "container_reference"` + - `output_index: number` - The environment type. Always `container_reference`. + The index of the output item this summary text is associated with. - - `status: "in_progress" or "completed" or "incomplete"` + - `sequence_number: number` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The sequence number of this event. - - `"in_progress"` + - `summary_index: number` - - `"completed"` + The index of the summary part within the reasoning summary. - - `"incomplete"` + - `text: string` - - `type: "shell_call"` + The full text of the completed reasoning summary. - The type of the item. Always `shell_call`. + - `type: "response.reasoning_summary_text.done"` + + The type of the event. Always `response.reasoning_summary_text.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_reasoning_text_delta_event: object { content_index, delta, item_id, 4 more }` - The execution context that produced this tool call. + Emitted when a delta is added to a reasoning text. - - `direct: object { type }` + - `content_index: number` - - `program: object { caller_id, type }` + The index of the reasoning content part this delta is associated with. - - `caller_id: string` + - `delta: string` - The call ID of the program item that produced this tool call. + The text delta that was added to the reasoning content. - - `type: "program"` + - `item_id: string` - - `created_by: optional string` + The ID of the item this reasoning text delta is associated with. - The ID of the entity that created this tool call. + - `output_index: number` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + The index of the output item this reasoning text delta is associated with. - The output of a shell tool call that was emitted. + - `sequence_number: number` - - `id: string` + The sequence number of this event. - The unique ID of the shell call output. Populated when this item is returned via API. + - `type: "response.reasoning_text.delta"` - - `call_id: string` + The type of the event. Always `response.reasoning_text.delta`. - The unique ID of the shell tool call generated by the model. + - `agent: optional object { agent_name }` - - `max_output_length: number` + The agent that owns this multi-agent streaming event. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `agent_name: string` - - `output: array of object { outcome, stderr, stdout, created_by }` + The canonical name of the agent that produced this item. - An array of shell call output contents + - `beta_response_reasoning_text_done_event: object { content_index, item_id, output_index, 4 more }` - - `outcome: object { type } or object { exit_code, type }` + Emitted when a reasoning text is completed. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `content_index: number` - - `timeout: object { type }` + The index of the reasoning content part. - Indicates that the shell call exceeded its configured time limit. + - `item_id: string` - - `exit: object { exit_code, type }` + The ID of the item this reasoning text is associated with. - Indicates that the shell commands finished and returned an exit code. + - `output_index: number` - - `exit_code: number` + The index of the output item this reasoning text is associated with. - Exit code from the shell process. + - `sequence_number: number` - - `type: "exit"` + The sequence number of this event. - The outcome type. Always `exit`. + - `text: string` - - `stderr: string` + The full text of the completed reasoning content. - The standard error output that was captured. + - `type: "response.reasoning_text.done"` - - `stdout: string` + The type of the event. Always `response.reasoning_text.done`. - The standard output that was captured. + - `agent: optional object { agent_name }` - - `created_by: optional string` + The agent that owns this multi-agent streaming event. - The identifier of the actor that created the item. + - `agent_name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The canonical name of the agent that produced this item. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `beta_response_refusal_delta_event: object { content_index, delta, item_id, 4 more }` - - `"in_progress"` + Emitted when there is a partial refusal text. - - `"completed"` + - `content_index: number` - - `"incomplete"` + The index of the content part that the refusal text is added to. - - `type: "shell_call_output"` + - `delta: string` - The type of the shell call output. Always `shell_call_output`. + The refusal text that is added. + + - `item_id: string` + + The ID of the output item that the refusal text is added to. + + - `output_index: number` + + The index of the output item that the refusal text is added to. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.refusal.delta"` + + The type of the event. Always `response.refusal.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. + - `beta_response_refusal_done_event: object { content_index, item_id, output_index, 4 more }` - - `direct: object { type }` + Emitted when refusal text is finalized. - - `program: object { caller_id, type }` + - `content_index: number` - - `caller_id: string` + The index of the content part that the refusal text is finalized. - The call ID of the program item that produced this tool call. + - `item_id: string` - - `type: "program"` + The ID of the output item that the refusal text is finalized. - - `created_by: optional string` + - `output_index: number` - The identifier of the actor that created the item. + The index of the output item that the refusal text is finalized. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `refusal: string` - A tool call that applies file diffs by creating, deleting, or updating files. + The refusal text that is finalized. - - `id: string` + - `sequence_number: number` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The sequence number of this event. - - `call_id: string` + - `type: "response.refusal.done"` - The unique ID of the apply patch tool call generated by the model. + The type of the event. Always `response.refusal.done`. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `agent: optional object { agent_name }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The agent that owns this multi-agent streaming event. - - `create_file: object { diff, path, type }` + - `agent_name: string` - Instruction describing how to create a file via the apply_patch tool. + The canonical name of the agent that produced this item. - - `diff: string` + - `beta_response_text_delta_event: object { content_index, delta, item_id, 5 more }` - Diff to apply. + Emitted when there is an additional text delta. - - `path: string` + - `content_index: number` - Path of the file to create. + The index of the content part that the text delta was added to. - - `type: "create_file"` + - `delta: string` - Create a new file with the provided diff. + The text delta that was added. - - `delete_file: object { path, type }` + - `item_id: string` - Instruction describing how to delete a file via the apply_patch tool. + The ID of the output item that the text delta was added to. - - `path: string` + - `logprobs: array of object { token, logprob, top_logprobs }` - Path of the file to delete. + The log probabilities of the tokens in the delta. - - `type: "delete_file"` + - `token: string` - Delete the specified file. + A possible text token. - - `update_file: object { diff, path, type }` + - `logprob: number` - Instruction describing how to update a file via the apply_patch tool. + The log probability of this token. - - `diff: string` + - `top_logprobs: optional array of object { token, logprob }` - Diff to apply. + The log probabilities of up to 20 of the most likely tokens. - - `path: string` + - `token: optional string` - Path of the file to update. + A possible text token. - - `type: "update_file"` + - `logprob: optional number` - Update an existing file with the provided diff. + The log probability of this token. - - `status: "in_progress" or "completed"` + - `output_index: number` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The index of the output item that the text delta was added to. - - `"in_progress"` + - `sequence_number: number` - - `"completed"` + The sequence number for this event. - - `type: "apply_patch_call"` + - `type: "response.output_text.delta"` - The type of the item. Always `apply_patch_call`. + The type of the event. Always `response.output_text.delta`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_text_done_event: object { content_index, item_id, logprobs, 5 more }` - The execution context that produced this tool call. + Emitted when text content is finalized. - - `direct: object { type }` + - `content_index: number` - - `program: object { caller_id, type }` + The index of the content part that the text content is finalized. - - `caller_id: string` + - `item_id: string` - The call ID of the program item that produced this tool call. + The ID of the output item that the text content is finalized. - - `type: "program"` + - `logprobs: array of object { token, logprob, top_logprobs }` - - `created_by: optional string` + The log probabilities of the tokens in the delta. - The ID of the entity that created this tool call. + - `token: string` + + A possible text token. + + - `logprob: number` + + The log probability of this token. + + - `top_logprobs: optional array of object { token, logprob }` + + The log probabilities of up to 20 of the most likely tokens. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `token: optional string` - The output emitted by an apply patch tool call. + A possible text token. - - `id: string` + - `logprob: optional number` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The log probability of this token. - - `call_id: string` + - `output_index: number` - The unique ID of the apply patch tool call generated by the model. + The index of the output item that the text content is finalized. - - `status: "completed" or "failed"` + - `sequence_number: number` - The status of the apply patch tool call output. One of `completed` or `failed`. + The sequence number for this event. - - `"completed"` + - `text: string` - - `"failed"` + The text content that is finalized. - - `type: "apply_patch_call_output"` + - `type: "response.output_text.done"` - The type of the item. Always `apply_patch_call_output`. + The type of the event. Always `response.output_text.done`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `beta_response_web_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - The execution context that produced this tool call. + Emitted when a web search call is completed. - - `direct: object { type }` + - `item_id: string` - - `program: object { caller_id, type }` + Unique ID for the output item associated with the web search call. - - `caller_id: string` + - `output_index: number` - The call ID of the program item that produced this tool call. + The index of the output item that the web search call is associated with. - - `type: "program"` + - `sequence_number: number` - - `created_by: optional string` + The sequence number of the web search call being processed. - The ID of the entity that created this tool call output. + - `type: "response.web_search_call.completed"` - - `output: optional string` + The type of the event. Always `response.web_search_call.completed`. - Optional textual output returned by the apply patch tool. + - `agent: optional object { agent_name }` - - `mcp_call: object { id, arguments, name, 7 more }` + The agent that owns this multi-agent streaming event. - An invocation of a tool on an MCP server. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The unique ID of the tool call. + - `beta_response_web_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `arguments: string` + Emitted when a web search call is initiated. - A JSON string of the arguments passed to the tool. + - `item_id: string` - - `name: string` + Unique ID for the output item associated with the web search call. - The name of the tool that was run. + - `output_index: number` - - `server_label: string` + The index of the output item that the web search call is associated with. - The label of the MCP server running the tool. + - `sequence_number: number` - - `type: "mcp_call"` + The sequence number of the web search call being processed. - The type of the item. Always `mcp_call`. + - `type: "response.web_search_call.in_progress"` + + The type of the event. Always `response.web_search_call.in_progress`. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. - - - `output: optional string` - - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `beta_response_web_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` - - `"in_progress"` + Emitted when a web search call is executing. - - `"completed"` + - `item_id: string` - - `"incomplete"` + Unique ID for the output item associated with the web search call. - - `"calling"` + - `output_index: number` - - `"failed"` + The index of the output item that the web search call is associated with. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `sequence_number: number` - A list of tools available on an MCP server. + The sequence number of the web search call being processed. - - `id: string` + - `type: "response.web_search_call.searching"` - The unique ID of the list. + The type of the event. Always `response.web_search_call.searching`. - - `server_label: string` + - `agent: optional object { agent_name }` - The label of the MCP server. + The agent that owns this multi-agent streaming event. - - `tools: array of object { input_schema, name, annotations, description }` + - `agent_name: string` - The tools available on the server. + The canonical name of the agent that produced this item. - - `input_schema: unknown` + - `beta_response_image_gen_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - The JSON schema describing the tool's input. + Emitted when an image generation tool call has completed and the final image is available. - - `name: string` + - `item_id: string` - The name of the tool. + The unique identifier of the image generation item being processed. - - `annotations: optional unknown` + - `output_index: number` - Additional annotations about the tool. + The index of the output item in the response's output array. - - `description: optional string` + - `sequence_number: number` - The description of the tool. + The sequence number of this event. - - `type: "mcp_list_tools"` + - `type: "response.image_generation_call.completed"` - The type of the item. Always `mcp_list_tools`. + The type of the event. Always 'response.image_generation_call.completed'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `error: optional string` - - Error message if the server could not list tools. - - - `mcp_approval_request: object { id, arguments, name, 3 more }` - - A request for human approval of a tool invocation. - - - `id: string` + - `beta_response_image_gen_call_generating_event: object { item_id, output_index, sequence_number, 2 more }` - The unique ID of the approval request. + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `arguments: string` + - `item_id: string` - A JSON string of arguments for the tool. + The unique identifier of the image generation item being processed. - - `name: string` + - `output_index: number` - The name of the tool to run. + The index of the output item in the response's output array. - - `server_label: string` + - `sequence_number: number` - The label of the MCP server making the request. + The sequence number of the image generation item being processed. - - `type: "mcp_approval_request"` + - `type: "response.image_generation_call.generating"` - The type of the item. Always `mcp_approval_request`. + The type of the event. Always 'response.image_generation_call.generating'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `beta_response_image_gen_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - A response to an MCP approval request. + Emitted when an image generation tool call is in progress. - - `id: string` + - `item_id: string` - The unique ID of the approval response + The unique identifier of the image generation item being processed. - - `approval_request_id: string` + - `output_index: number` - The ID of the approval request being answered. + The index of the output item in the response's output array. - - `approve: boolean` + - `sequence_number: number` - Whether the request was approved. + The sequence number of the image generation item being processed. - - `type: "mcp_approval_response"` + - `type: "response.image_generation_call.in_progress"` - The type of the item. Always `mcp_approval_response`. + The type of the event. Always 'response.image_generation_call.in_progress'. - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `reason: optional string` + - `beta_response_image_gen_call_partial_image_event: object { item_id, output_index, partial_image_b64, 4 more }` - Optional reason for the decision. + Emitted when a partial image is available during image generation streaming. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `item_id: string` - A call to a custom tool created by the model. + The unique identifier of the image generation item being processed. - - `call_id: string` + - `output_index: number` - An identifier used to map this custom tool call to a tool call output. + The index of the output item in the response's output array. - - `input: string` + - `partial_image_b64: string` - The input for the custom tool call generated by the model. + Base64-encoded partial image data, suitable for rendering as an image. - - `name: string` + - `partial_image_index: number` - The name of the custom tool being called. + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `type: "custom_tool_call"` + - `sequence_number: number` - The type of the custom tool call. Always `custom_tool_call`. + The sequence number of the image generation item being processed. - - `id: optional string` + - `type: "response.image_generation_call.partial_image"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the event. Always 'response.image_generation_call.partial_image'. - `agent: optional object { agent_name }` - The agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. + The agent that owns this multi-agent streaming event. - - `namespace: optional string` + - `agent_name: string` - The namespace of the custom tool being called. + The canonical name of the agent that produced this item. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `beta_response_mcp_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` - The output of a custom tool call from your code, being sent back to the model. + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `id: string` + - `delta: string` - The unique ID of the custom tool call output item. + A JSON string containing the partial update to the arguments for the MCP tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `item_id: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The unique identifier of the MCP tool call item being processed. - - `"in_progress"` + - `output_index: number` - - `"completed"` + The index of the output item in the response's output array. - - `"incomplete"` + - `sequence_number: number` - - `created_by: optional string` + The sequence number of this event. - The identifier of the actor that created the item. + - `type: "response.mcp_call_arguments.delta"` - - `parallel_tool_calls: boolean` + The type of the event. Always 'response.mcp_call_arguments.delta'. - Whether to allow the model to run tool calls in parallel. + - `agent: optional object { agent_name }` - - `temperature: number` + The agent that owns this multi-agent streaming event. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `agent_name: string` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The canonical name of the agent that produced this item. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `beta_response_mcp_call_arguments_done_event: object { arguments, item_id, output_index, 3 more }` - - `beta_tool_choice_options: "none" or "auto" or "required"` + Emitted when the arguments for an MCP tool call are finalized. - Controls which (if any) tool is called by the model. + - `arguments: string` - `none` means the model will not call any tool and instead generates a message. + A JSON string containing the finalized arguments for the MCP tool call. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `item_id: string` - `required` means the model must call one or more tools. + The unique identifier of the MCP tool call item being processed. - - `"none"` + - `output_index: number` - - `"auto"` + The index of the output item in the response's output array. - - `"required"` + - `sequence_number: number` - - `beta_tool_choice_allowed: object { mode, tools, type }` + The sequence number of this event. - Constrains the tools available to the model to a pre-defined set. + - `type: "response.mcp_call_arguments.done"` - - `mode: "auto" or "required"` + The type of the event. Always 'response.mcp_call_arguments.done'. - Constrains the tools available to the model to a pre-defined set. + - `agent: optional object { agent_name }` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The agent that owns this multi-agent streaming event. - `required` requires the model to call one or more of the allowed tools. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"required"` + - `beta_response_mcp_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` - - `tools: array of map[unknown]` + Emitted when an MCP tool call has completed successfully. - A list of tool definitions that the model should be allowed to call. + - `item_id: string` - For the Responses API, the list of tool definitions might look like: + The ID of the MCP tool call item that completed. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `output_index: number` - - `type: "allowed_tools"` + The index of the output item that completed. - Allowed tool configuration type. Always `allowed_tools`. + - `sequence_number: number` - - `beta_tool_choice_types: object { type }` + The sequence number of this event. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `type: "response.mcp_call.completed"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + The type of the event. Always 'response.mcp_call.completed'. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `agent: optional object { agent_name }` - Allowed values are: + The agent that owns this multi-agent streaming event. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `agent_name: string` - - `"file_search"` + The canonical name of the agent that produced this item. - - `"web_search_preview"` + - `beta_response_mcp_call_failed_event: object { item_id, output_index, sequence_number, 2 more }` - - `"computer"` + Emitted when an MCP tool call has failed. - - `"computer_use_preview"` + - `item_id: string` - - `"computer_use"` + The ID of the MCP tool call item that failed. - - `"web_search_preview_2025_03_11"` + - `output_index: number` - - `"image_generation"` + The index of the output item that failed. - - `"code_interpreter"` + - `sequence_number: number` - - `beta_tool_choice_function: object { name, type }` + The sequence number of this event. - Use this option to force the model to call a specific function. + - `type: "response.mcp_call.failed"` - - `name: string` + The type of the event. Always 'response.mcp_call.failed'. - The name of the function to call. + - `agent: optional object { agent_name }` - - `type: "function"` + The agent that owns this multi-agent streaming event. - For function calling, the type is always `function`. + - `agent_name: string` - - `beta_tool_choice_mcp: object { server_label, type, name }` + The canonical name of the agent that produced this item. - Use this option to force the model to call a specific tool on a remote MCP server. + - `beta_response_mcp_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `server_label: string` + Emitted when an MCP tool call is in progress. - The label of the MCP server to use. + - `item_id: string` - - `type: "mcp"` + The unique identifier of the MCP tool call item being processed. - For MCP tools, the type is always `mcp`. + - `output_index: number` - - `name: optional string` + The index of the output item in the response's output array. - The name of the tool to call on the server. + - `sequence_number: number` - - `beta_tool_choice_custom: object { name, type }` + The sequence number of this event. - Use this option to force the model to call a specific custom tool. + - `type: "response.mcp_call.in_progress"` - - `name: string` + The type of the event. Always 'response.mcp_call.in_progress'. - The name of the custom tool to call. + - `agent: optional object { agent_name }` - - `type: "custom"` + The agent that owns this multi-agent streaming event. - For custom tool calling, the type is always `custom`. + - `agent_name: string` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + The canonical name of the agent that produced this item. - - `beta_tool_choice_apply_patch: object { type }` + - `beta_response_mcp_list_tools_completed_event: object { item_id, output_index, sequence_number, 2 more }` - Forces the model to call the apply_patch tool when executing a tool call. + Emitted when the list of available MCP tools has been successfully retrieved. - - `type: "apply_patch"` + - `item_id: string` - The tool to call. Always `apply_patch`. + The ID of the MCP tool call item that produced this output. - - `beta_tool_choice_shell: object { type }` + - `output_index: number` - Forces the model to call the shell tool when a tool call is required. + The index of the output item that was processed. - - `type: "shell"` + - `sequence_number: number` - The tool to call. Always `shell`. + The sequence number of this event. - - `tools: array of BetaTool` + - `type: "response.mcp_list_tools.completed"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The type of the event. Always 'response.mcp_list_tools.completed'. - We support the following categories of tools: + - `agent: optional object { agent_name }` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + The agent that owns this multi-agent streaming event. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `agent_name: string` - 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). + The canonical name of the agent that produced this item. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `beta_response_mcp_list_tools_failed_event: object { item_id, output_index, sequence_number, 2 more }` - 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). + Emitted when the attempt to list available MCP tools has failed. - - `beta_computer_tool: object { type }` + - `item_id: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The ID of the MCP tool call item that failed. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `output_index: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the output item that failed. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `sequence_number: number` - 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). + The sequence number of this event. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `type: "response.mcp_list_tools.failed"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The type of the event. Always 'response.mcp_list_tools.failed'. - - `code_interpreter: object { container, type, allowed_callers }` + - `agent: optional object { agent_name }` - A tool that runs Python code to help generate a response to a prompt. + The agent that owns this multi-agent streaming event. - - `programmatic_tool_calling: object { type }` + - `agent_name: string` - - `image_generation: object { type, action, background, 9 more }` + The canonical name of the agent that produced this item. - A tool that generates images using the GPT image models. + - `beta_response_mcp_list_tools_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - `local_shell: object { type }` + Emitted when the system is in the process of retrieving the list of available MCP tools. - A tool that allows the model to execute shell commands in a local environment. + - `item_id: string` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The ID of the MCP tool call item that is being processed. - A tool that allows the model to execute shell commands. + - `output_index: number` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The index of the output item that is being processed. - 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) + - `sequence_number: number` - - `beta_namespace_tool: object { description, name, tools, type }` + The sequence number of this event. - Groups function/custom tools under a shared namespace. + - `type: "response.mcp_list_tools.in_progress"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - Hosted or BYOT tool search configuration for deferred tools. + - `agent: optional object { agent_name }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The agent that owns this multi-agent streaming event. - 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). + - `agent_name: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The canonical name of the agent that produced this item. - Allows the assistant to create, delete, or update files using unified diffs. + - `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` - - `top_p: number` + Emitted when an annotation is added to output text content. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `annotation: unknown` - We generally recommend altering this or `temperature` but not both. + The annotation object being added. (See annotation schema for details.) - - `background: optional boolean` + - `annotation_index: number` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The index of the annotation within the content part. - - `completed_at: optional number` + - `content_index: number` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The index of the content part within the output item. - - `conversation: optional object { id }` + - `item_id: string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The unique identifier of the item to which the annotation is being added. - - `id: string` + - `output_index: number` - The unique ID of the conversation that this response was associated with. + The index of the output item in the response's output array. - - `max_output_tokens: optional number` + - `sequence_number: number` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The sequence number of this event. - - `max_tool_calls: optional number` + - `type: "response.output_text.annotation.added"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The type of the event. Always 'response.output_text.annotation.added'. - - `moderation: optional object { input, output }` + - `agent: optional object { agent_name }` - Moderation results for the response input and output, if moderated completions were requested. + The agent that owns this multi-agent streaming event. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `agent_name: string` - Moderation for the response input. + The canonical name of the agent that produced this item. - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `beta_response_queued_event: object { response, sequence_number, type, agent }` - A moderation result produced for the response input or output. + Emitted when a response is queued and waiting to be processed. - - `categories: map[boolean]` + - `response: object { id, created_at, error, 31 more }` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The full response object that is queued. - - `category_applied_input_types: map[array of "text" or "image"]` + - `id: string` - Which modalities of input are reflected by the score for each category. + Unique identifier for this Response. - - `"text"` + - `created_at: number` - - `"image"` + Unix timestamp (in seconds) of when this Response was created. - - `category_scores: map[number]` + - `error: object { code, message }` - A dictionary of moderation categories to scores. + An error object returned when the model fails to generate a Response. - - `flagged: boolean` + - `incomplete_details: object { reason }` - A boolean indicating whether the content was flagged by any category. + Details about why the response is incomplete. - - `model: string` + - `instructions: string or array of BetaResponseInputItem` - The moderation model that produced this result. + A system (or developer) message inserted into the model's context. - - `type: "moderation_result"` + When using 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. - The object type, which was always `moderation_result` for successful moderation results. + - `metadata: map[string]` - - `error: object { code, message, type }` + 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. - An error produced while attempting moderation for the response input or output. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `code: string` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The error code. + Model ID used to generate the response, like `gpt-4o` 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. - - `message: string` + - `object: "response"` - The error message. + The object type of this resource - always set to `response`. - - `type: "error"` + - `output: array of BetaResponseOutputItem` - The object type, which was always `error` for moderation failures. + An array of content items generated by the model. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - Moderation for the response output. + - `parallel_tool_calls: boolean` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + Whether to allow the model to run tool calls in parallel. - A moderation result produced for the response input or output. + - `temperature: number` - - `categories: map[boolean]` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `category_applied_input_types: map[array of "text" or "image"]` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - Which modalities of input are reflected by the score for each category. + - `tools: array of BetaTool` - - `"text"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"image"` + We support the following categories of tools: - - `category_scores: map[number]` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) + or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use + custom tools to call your own code. - A dictionary of moderation categories to scores. + - `top_p: number` - - `flagged: boolean` + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - A boolean indicating whether the content was flagged by any category. + We generally recommend altering this or `temperature` but not both. - - `model: string` + - `background: optional boolean` - The moderation model that produced this result. + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). - - `type: "moderation_result"` + - `completed_at: optional number` - The object type, which was always `moderation_result` for successful moderation results. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `error: object { code, message, type }` + - `conversation: optional object { id }` - An error produced while attempting moderation for the response input or output. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `code: string` + - `max_output_tokens: optional number` - The error code. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - `message: string` + - `max_tool_calls: optional number` - The error message. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `type: "error"` + - `moderation: optional object { input, output }` - The object type, which was always `error` for moderation failures. + Moderation results for the response input and output, if moderated completions were requested. - `previous_response_id: optional string` @@ -118738,34 +131401,6 @@ openai beta:responses compact \ Reference to a prompt template and its variables. [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). - - `id: string` - - The unique identifier of the prompt template to use. - - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. - - - `union_member_0: string` - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `version: optional string` - - Optional version of the prompt template. - - `prompt_cache_key: optional string` Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). @@ -118774,20 +131409,6 @@ openai beta:responses compact \ The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `mode: "implicit" or "explicit"` - - Whether implicit prompt-cache breakpoints were enabled. - - - `"implicit"` - - - `"explicit"` - - - `ttl: "30m"` - - The minimum lifetime applied to each cache breakpoint. - - - `"30m"` - - `prompt_cache_retention: optional "in_memory" or "24h"` Deprecated. Use `prompt_cache_options.ttl` instead. @@ -118803,10 +131424,6 @@ openai beta:responses compact \ - Organizations without ZDR enabled default to `24h`. - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `"in_memory"` - - - `"24h"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` **gpt-5 and o-series models only** @@ -118814,80 +131431,6 @@ openai beta:responses compact \ Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `context: optional "auto" or "current_turn" or "all_turns"` - - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. - - - `"auto"` - - - `"current_turn"` - - - `"all_turns"` - - - `effort: optional "none" or "minimal" or "low" or 4 more` - - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. - - - `"none"` - - - `"minimal"` - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"xhigh"` - - - `"max"` - - - `generate_summary: optional "auto" or "concise" or "detailed"` - - **Deprecated:** use `summary` instead. - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - - `"auto"` - - - `"concise"` - - - `"detailed"` - - - `mode: optional string or "standard" or "pro"` - - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - - - `"standard"` - - - `"pro"` - - - `summary: optional "auto" or "concise" or "detailed"` - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - - `"auto"` - - - `"concise"` - - - `"detailed"` - - `safety_identifier: optional string` A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. @@ -118904,3179 +131447,2963 @@ openai beta:responses compact \ When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - - `"auto"` + - `status: optional "completed" or "failed" or "in_progress" or 3 more` - - `"default"` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"flex"` + - `text: optional object { format, verbosity }` - - `"scale"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"priority"` + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `top_logprobs: optional number` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `"completed"` + - `truncation: optional "auto" or "disabled"` - - `"failed"` + The truncation strategy to use for the model response. - - `"in_progress"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `"cancelled"` + - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `"queued"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `"incomplete"` + - `user: optional string` - - `text: optional object { format, verbosity }` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `sequence_number: number` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The sequence number for this event. - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `type: "response.queued"` - An object specifying the format that the model must output. + The type of the event. Always 'response.queued'. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `agent: optional object { agent_name }` - The default format is `{ "type": "text" }` with no additional options. + The agent that owns this multi-agent streaming event. - **Not recommended for gpt-4o and newer models:** + - `agent_name: string` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The canonical name of the agent that produced this item. - - `text: object { type }` + - `beta_response_custom_tool_call_input_delta_event: object { delta, item_id, output_index, 3 more }` - Default response format. Used to generate text responses. + Event representing a delta (partial update) to the input of a custom tool call. - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + - `delta: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + The incremental input data (delta) for the custom tool call. - - `name: string` + - `item_id: string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + Unique identifier for the API item associated with this event. - - `schema: map[unknown]` + - `output_index: number` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The index of the output this delta applies to. - - `type: "json_schema"` + - `sequence_number: number` - The type of response format being defined. Always `json_schema`. + The sequence number of this event. - - `description: optional string` + - `type: "response.custom_tool_call_input.delta"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The event type identifier. - - `strict: optional boolean` + - `agent: optional object { agent_name }` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + The agent that owns this multi-agent streaming event. - - `json_object: object { type }` + - `agent_name: string` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + The canonical name of the agent that produced this item. - - `verbosity: optional "low" or "medium" or "high"` + - `beta_response_custom_tool_call_input_done_event: object { input, item_id, output_index, 3 more }` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + Event indicating that input for a custom tool call is complete. - - `"low"` + - `input: string` - - `"medium"` + The complete input data for the custom tool call. - - `"high"` + - `item_id: string` - - `top_logprobs: optional number` + Unique identifier for the API item associated with this event. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `output_index: number` - - `truncation: optional "auto" or "disabled"` + The index of the output this event applies to. - The truncation strategy to use for the model response. + - `sequence_number: number` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The sequence number of this event. - - `"auto"` + - `type: "response.custom_tool_call_input.done"` - - `"disabled"` + The event type identifier. - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `agent: optional object { agent_name }` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The agent that owns this multi-agent streaming event. - - `input_tokens: number` + - `agent_name: string` - The number of input tokens. + The canonical name of the agent that produced this item. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `beta_response_inject_created_event: object { response_id, sequence_number, type, stream_id }` - A detailed breakdown of the input tokens. + Emitted when all injected input items were validated and committed to the + active response. - - `cache_write_tokens: number` + - `response_id: string` - The number of input tokens that were written to the cache. + The ID of the response that accepted the input. - - `cached_tokens: number` + - `sequence_number: number` - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + The sequence number for this event. - - `output_tokens: number` + - `type: "response.inject.created"` - The number of output tokens. + The event discriminator. Always `response.inject.created`. - - `output_tokens_details: object { reasoning_tokens }` + - `stream_id: optional string` - A detailed breakdown of the output tokens. + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `reasoning_tokens: number` + - `beta_response_inject_failed_event: object { error, input, response_id, 3 more }` - The number of reasoning tokens. + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - - `total_tokens: number` + - `error: object { code, message }` - The total number of tokens used. + Information about why the input was not committed. - - `user: optional string` + - `code: "response_already_completed" or "response_not_found"` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + A machine-readable error code. - - `sequence_number: number` + - `"response_already_completed"` - The sequence number for this event. + - `"response_not_found"` - - `type: "response.completed"` + - `message: string` - The type of the event. Always `response.completed`. + A human-readable description of the error. - - `agent: optional object { agent_name }` + - `input: array of BetaResponseInputItem` - The agent that owns this multi-agent streaming event. + The raw input items that were not committed. - - `agent_name: string` + - `beta_easy_input_message: object { content, role, phase, type }` - The canonical name of the agent that produced this item. + 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. + + - `message: object { content, role, agent, 2 more }` + + 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. + + - `beta_response_output_message: object { id, content, role, 4 more }` + + An output message from the model. + + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + + 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. + + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + + 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. + + - `computer_call_output: object { call_id, output, type, 4 more }` + + The output of a computer tool call. - - `beta_response_content_part_added_event: object { content_index, item_id, output_index, 4 more }` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - Emitted when a new content part is added. + 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. - - `content_index: number` + - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` - The index of the content part that was added. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `item_id: string` + - `function_call_output: object { call_id, output, type, 4 more }` - The ID of the output item that the content part was added to. + The output of a function tool call. - - `output_index: number` + - `agent_message: object { author, content, recipient, 3 more }` - The index of the output item that the content part was added to. + A message routed between agents. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `multi_agent_call: object { action, arguments, call_id, 3 more }` - The content part that was added. + - `multi_agent_call_output: object { action, call_id, output, 3 more }` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `tool_search_call: object { arguments, type, id, 4 more }` - A text output from the model. + - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `beta_response_output_refusal: object { refusal, type }` + - `additional_tools: object { role, tools, type, 2 more }` - A refusal from the model. + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `reasoning_text: object { text, type }` + 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). - Reasoning text from the model. + - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` - - `text: string` + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - The reasoning text from the model. + - `image_generation_call: object { id, result, status, 2 more }` - - `type: "reasoning_text"` + An image generation request made by the model. - The type of the reasoning text. Always `reasoning_text`. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - - `sequence_number: number` + A tool call to run code. - The sequence number of this event. + - `local_shell_call: object { id, action, call_id, 3 more }` - - `type: "response.content_part.added"` + A tool call to run a command on the local shell. - The type of the event. Always `response.content_part.added`. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `agent: optional object { agent_name }` + The output of a local shell tool call. - The agent that owns this multi-agent streaming event. + - `shell_call: object { action, call_id, type, 5 more }` - - `agent_name: string` + A tool representing a request to execute one or more shell commands. - The canonical name of the agent that produced this item. + - `shell_call_output: object { call_id, output, type, 5 more }` - - `beta_response_content_part_done_event: object { content_index, item_id, output_index, 4 more }` + The streamed output items emitted by a shell tool call. - Emitted when a content part is done. + - `apply_patch_call: object { call_id, operation, status, 4 more }` - - `content_index: number` + A tool call representing a request to create, delete, or update files using diff patches. - The index of the content part that is done. + - `apply_patch_call_output: object { call_id, status, type, 4 more }` - - `item_id: string` + The streamed output emitted by an apply patch tool call. - The ID of the output item that the content part was added to. + - `mcp_list_tools: object { id, server_label, tools, 3 more }` - - `output_index: number` + A list of tools available on an MCP server. - The index of the output item that the content part was added to. + - `mcp_approval_request: object { id, arguments, name, 3 more }` - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + A request for human approval of a tool invocation. - The content part that is done. + - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + A response to an MCP approval request. - A text output from the model. + - `mcp_call: object { id, arguments, name, 7 more }` - - `beta_response_output_refusal: object { refusal, type }` + An invocation of a tool on an MCP server. - A refusal from the model. + - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - `reasoning_text: object { text, type }` + The output of a custom tool call from your code, being sent back to the model. - Reasoning text from the model. + - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` - - `text: string` + A call to a custom tool created by the model. - The reasoning text from the model. + - `compaction_trigger: object { type, agent }` - - `type: "reasoning_text"` + Compacts the current context. Must be the final input item. - The type of the reasoning text. Always `reasoning_text`. + - `item_reference: object { id, agent, type }` - - `sequence_number: number` + An internal identifier for an item to reference. - The sequence number of this event. + - `program: object { id, call_id, code, 3 more }` - - `type: "response.content_part.done"` + - `program_output: object { id, call_id, result, 3 more }` - The type of the event. Always `response.content_part.done`. + - `response_id: string` - - `agent: optional object { agent_name }` + The ID of the response that rejected the input. - The agent that owns this multi-agent streaming event. + - `sequence_number: number` - - `agent_name: string` + The sequence number for this event. - The canonical name of the agent that produced this item. + - `type: "response.inject.failed"` - - `beta_response_created_event: object { response, sequence_number, type, agent }` + The event discriminator. Always `response.inject.failed`. - An event that is emitted when a response is created. + - `stream_id: optional string` - - `response: object { id, created_at, error, 31 more }` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - The response that was created. +### Beta Skill Reference - - `id: string` +- `beta_skill_reference: object { skill_id, type, version }` - Unique identifier for this Response. + - `skill_id: string` - - `created_at: number` + The ID of the referenced skill. - Unix timestamp (in seconds) of when this Response was created. + - `type: "skill_reference"` - - `error: object { code, message }` + References a skill created with the /v1/skills endpoint. - An error object returned when the model fails to generate a Response. + - `version: optional string` - - `incomplete_details: object { reason }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Details about why the response is incomplete. +### Beta Tool - - `instructions: string or array of BetaResponseInputItem` +- `beta_tool: BetaFunctionTool or BetaFileSearchTool or BetaComputerTool or 13 more` - A system (or developer) message inserted into the model's context. + A tool that can be used to generate a response. - When using 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. + - `beta_function_tool: object { name, parameters, strict, 5 more }` - - `metadata: map[string]` + 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). - 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. + - `name: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the function to call. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `parameters: map[unknown]` - Model ID used to generate the response, like `gpt-4o` 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. + A JSON schema object describing the parameters of the function. - - `object: "response"` + - `strict: boolean` - The object type of this resource - always set to `response`. + Whether strict parameter validation is enforced for this function tool. - - `output: array of BetaResponseOutputItem` + - `type: "function"` - An array of content items generated by the model. + The type of the function tool. Always `function`. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `parallel_tool_calls: boolean` + The tool invocation context(s). - Whether to allow the model to run tool calls in parallel. + - `"direct"` - - `temperature: number` + - `"programmatic"` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `defer_loading: optional boolean` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + Whether this function is deferred and loaded via tool search. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `description: optional string` - - `tools: array of BetaTool` + A description of the function. Used by the model to determine whether or not to call the function. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `output_schema: optional map[unknown]` - We support the following categories of tools: + A JSON schema object describing the JSON value encoded in string outputs for this function. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` - - `top_p: number` + 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). - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `type: "file_search"` - We generally recommend altering this or `temperature` but not both. + The type of the file search tool. Always `file_search`. - - `background: optional boolean` + - `vector_store_ids: array of string` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + The IDs of the vector stores to search. - - `completed_at: optional number` + - `filters: optional object { key, type, value } or object { filters, type }` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + A filter to apply. - - `conversation: optional object { id }` + - `Comparison Filter: object { key, type, value }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `max_output_tokens: optional number` + - `key: string` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The key to compare against the value. - - `max_tool_calls: optional number` + - `type: "eq" or "ne" or "gt" or 5 more` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `moderation: optional object { input, output }` + - `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 - Moderation results for the response input and output, if moderated completions were requested. + - `"eq"` - - `previous_response_id: optional string` + - `"ne"` - 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`. + - `"gt"` - - `prompt: optional object { id, variables, version }` + - `"gte"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `"lt"` - - `prompt_cache_key: optional string` + - `"lte"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"in"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"nin"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `value: string or number or boolean or array of string or number` - - `prompt_cache_retention: optional "in_memory" or "24h"` + The value to compare against the attribute key; supports string, number, or boolean types. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `union_member_0: string` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `union_member_1: number` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `union_member_2: boolean` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `union_member_3: array of string or number` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `union_member_0: string` - **gpt-5 and o-series models only** + - `union_member_1: number` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `Compound Filter: object { filters, type }` - - `safety_identifier: optional string` + Combine multiple filters using `and` or `or`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `filters: array of object { key, type, value } or unknown` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Specifies the processing type used for serving the request. + - `Comparison Filter: object { key, type, value }` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `key: string` - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + The key to compare against the value. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `text: optional object { format, verbosity }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `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 - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"eq"` - - `top_logprobs: optional number` + - `"ne"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `"gt"` - - `truncation: optional "auto" or "disabled"` + - `"gte"` - The truncation strategy to use for the model response. + - `"lt"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"lte"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `"in"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `"nin"` - - `user: optional string` + - `value: string or number or boolean or array of string or number` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The value to compare against the attribute key; supports string, number, or boolean types. - - `sequence_number: number` + - `union_member_0: string` - The sequence number for this event. + - `union_member_1: number` - - `type: "response.created"` + - `union_member_2: boolean` - The type of the event. Always `response.created`. + - `union_member_3: array of string or number` - - `agent: optional object { agent_name }` + - `union_member_0: string` - The agent that owns this multi-agent streaming event. + - `union_member_1: number` - - `agent_name: string` + - `union_member_1: unknown` - The canonical name of the agent that produced this item. + - `type: "and" or "or"` - - `beta_response_error_event: object { code, message, param, 3 more }` + Type of operation: `and` or `or`. - Emitted when an error occurs. + - `"and"` - - `code: string` + - `"or"` - The error code. + - `max_num_results: optional number` - - `message: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The error message. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `param: string` + Ranking options for search. - The error parameter. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `sequence_number: number` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The sequence number of this event. + - `embedding_weight: number` - - `type: "error"` + The weight of the embedding in the reciprocal ranking fusion. - The type of the event. Always `error`. + - `text_weight: number` - - `agent: optional object { agent_name }` + The weight of the text in the reciprocal ranking fusion. - The agent that owns this multi-agent streaming event. + - `ranker: optional "auto" or "default-2024-11-15"` - - `agent_name: string` + The ranker to use for the file search. - The canonical name of the agent that produced this item. + - `"auto"` - - `beta_response_file_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `"default-2024-11-15"` - Emitted when a file search call is completed (results found). + - `score_threshold: optional number` - - `item_id: string` + 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. - The ID of the output item that the file search call is initiated. + - `beta_computer_tool: object { type }` - - `output_index: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The index of the output item that the file search call is initiated. + - `type: "computer"` - - `sequence_number: number` + The type of the computer tool. Always `computer`. - The sequence number of this event. + - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` - - `type: "response.file_search_call.completed"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the event. Always `response.file_search_call.completed`. + - `display_height: number` - - `agent: optional object { agent_name }` + The height of the computer display. - The agent that owns this multi-agent streaming event. + - `display_width: number` - - `agent_name: string` + The width of the computer display. - The canonical name of the agent that produced this item. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `beta_response_file_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + The type of computer environment to control. - Emitted when a file search call is initiated. + - `"windows"` - - `item_id: string` + - `"mac"` - The ID of the output item that the file search call is initiated. + - `"linux"` - - `output_index: number` + - `"ubuntu"` - The index of the output item that the file search call is initiated. + - `"browser"` - - `sequence_number: number` + - `type: "computer_use_preview"` - The sequence number of this event. + The type of the computer use tool. Always `computer_use_preview`. - - `type: "response.file_search_call.in_progress"` + - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The type of the event. Always `response.file_search_call.in_progress`. + 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). - - `agent: optional object { agent_name }` + - `type: "web_search" or "web_search_2025_08_26"` - The agent that owns this multi-agent streaming event. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `agent_name: string` + - `"web_search"` - The canonical name of the agent that produced this item. + - `"web_search_2025_08_26"` - - `beta_response_file_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` + - `filters: optional object { allowed_domains }` - Emitted when a file search is currently searching. + Filters for the search. - - `item_id: string` + - `allowed_domains: optional array of string` - The ID of the output item that the file search call is initiated. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `output_index: number` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The index of the output item that the file search call is searching. + - `search_context_size: optional "low" or "medium" or "high"` - - `sequence_number: number` + 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. - The sequence number of this event. + - `"low"` - - `type: "response.file_search_call.searching"` + - `"medium"` - The type of the event. Always `response.file_search_call.searching`. + - `"high"` - - `agent: optional object { agent_name }` + - `user_location: optional object { city, country, region, 2 more }` - The agent that owns this multi-agent streaming event. + The approximate location of the user. - - `agent_name: string` + - `city: optional string` - The canonical name of the agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `beta_response_function_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` + - `country: optional string` - Emitted when there is a partial function-call arguments delta. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `delta: string` + - `region: optional string` - The function-call arguments delta that is added. + Free text input for the region of the user, e.g. `California`. - - `item_id: string` + - `timezone: optional string` - The ID of the output item that the function-call arguments delta is added to. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `output_index: number` + - `type: optional "approximate"` - The index of the output item that the function-call arguments delta is added to. + The type of location approximation. Always `approximate`. - - `sequence_number: number` + - `"approximate"` - The sequence number of this event. + - `mcp: object { server_label, type, allowed_callers, 9 more }` - - `type: "response.function_call_arguments.delta"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - The type of the event. Always `response.function_call_arguments.delta`. + - `server_label: string` - - `agent: optional object { agent_name }` + A label for this MCP server, used to identify it in tool calls. - The agent that owns this multi-agent streaming event. + - `type: "mcp"` - - `agent_name: string` + The type of the MCP tool. Always `mcp`. - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `beta_response_function_call_arguments_done_event: object { arguments, item_id, name, 4 more }` + The tool invocation context(s). - Emitted when function-call arguments are finalized. + - `"direct"` - - `arguments: string` + - `"programmatic"` - The function-call arguments. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `item_id: string` + List of allowed tool names or a filter object. - The ID of the item. + - `MCP allowed tools: array of string` - - `name: string` + A string array of allowed tool names - The name of the function that was called. + - `MCP tool filter: object { read_only, tool_names }` - - `output_index: number` + A filter object to specify which tools are allowed. - The index of the output item. + - `read_only: optional boolean` - - `sequence_number: number` + 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. - The sequence number of this event. + - `tool_names: optional array of string` - - `type: "response.function_call_arguments.done"` + List of allowed tool names. - - `agent: optional object { agent_name }` + - `authorization: optional string` - The agent that owns this multi-agent streaming event. + 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. - - `agent_name: string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The canonical name of the agent that produced this item. + 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). - - `beta_response_in_progress_event: object { response, sequence_number, type, agent }` + Currently supported `connector_id` values are: - Emitted when the response is in progress. + - 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` - - `response: object { id, created_at, error, 31 more }` + - `"connector_dropbox"` - The response that is in progress. + - `"connector_gmail"` - - `id: string` + - `"connector_googlecalendar"` - Unique identifier for this Response. + - `"connector_googledrive"` - - `created_at: number` + - `"connector_microsoftteams"` - Unix timestamp (in seconds) of when this Response was created. + - `"connector_outlookcalendar"` - - `error: object { code, message }` + - `"connector_outlookemail"` - An error object returned when the model fails to generate a Response. + - `"connector_sharepoint"` - - `incomplete_details: object { reason }` + - `defer_loading: optional boolean` - Details about why the response is incomplete. + Whether this MCP tool is deferred and discovered via tool search. - - `instructions: string or array of BetaResponseInputItem` + - `headers: optional map[string]` - A system (or developer) message inserted into the model's context. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - When using 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. + - `require_approval: optional object { always, never } or "always" or "never"` - - `metadata: map[string]` + Specify which of the MCP server's tools require approval. - 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. + - `MCP tool approval filter: object { always, never }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `always: optional object { read_only, tool_names }` - Model ID used to generate the response, like `gpt-4o` 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. + A filter object to specify which tools are allowed. - - `object: "response"` + - `read_only: optional boolean` - The object type of this resource - always set to `response`. + 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. - - `output: array of BetaResponseOutputItem` + - `tool_names: optional array of string` - An array of content items generated by the model. + List of allowed tool names. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `never: optional object { read_only, tool_names }` - - `parallel_tool_calls: boolean` + A filter object to specify which tools are allowed. - Whether to allow the model to run tool calls in parallel. + - `read_only: optional boolean` - - `temperature: number` + 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. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `tool_names: optional array of string` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + List of allowed tool names. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `MCP tool approval setting: "always" or "never"` - - `tools: array of BetaTool` + 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. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `"always"` - We support the following categories of tools: + - `"never"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `server_description: optional string` - - `top_p: number` + Optional description of the MCP server, used to provide more context. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `server_url: optional string` - We generally recommend altering this or `temperature` but not both. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `background: optional boolean` + - `tunnel_id: optional string` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + 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. - - `completed_at: optional number` + - `code_interpreter: object { container, type, allowed_callers }` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + A tool that runs Python code to help generate a response to a prompt. - - `conversation: optional object { id }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + 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. - - `max_output_tokens: optional number` + - `union_member_0: string` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The container ID. - - `max_tool_calls: optional number` + - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `moderation: optional object { input, output }` + - `type: "auto"` - Moderation results for the response input and output, if moderated completions were requested. + Always `auto`. - - `previous_response_id: optional string` + - `file_ids: optional array of string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + An optional list of uploaded files to make available to your code. - - `prompt: optional object { id, variables, version }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The memory limit for the code interpreter container. - - `prompt_cache_key: optional string` + - `"1g"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"4g"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"16g"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"64g"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Deprecated. Use `prompt_cache_options.ttl` instead. + Network access policy for the container. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `beta_container_network_policy_disabled: object { type }` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `type: "disabled"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Disable outbound network access. Always `disabled`. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - **gpt-5 and o-series models only** + - `allowed_domains: array of string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + A list of allowed domains when type is `allowlist`. - - `safety_identifier: optional string` + - `type: "allowlist"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Allow outbound network access only to specified domains. Always `allowlist`. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - Specifies the processing type used for serving the request. + Optional domain-scoped secrets for allowlisted domains. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `domain: string` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The domain associated with the secret. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `name: string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The name of the secret to inject for the domain. - - `text: optional object { format, verbosity }` + - `value: string` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The secret value to inject for the domain. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `type: "code_interpreter"` - - `top_logprobs: optional number` + The type of the code interpreter tool. Always `code_interpreter`. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `truncation: optional "auto" or "disabled"` + The tool invocation context(s). - The truncation strategy to use for the model response. + - `"direct"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"programmatic"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `programmatic_tool_calling: object { type }` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `image_generation: object { type, action, background, 9 more }` - - `user: optional string` + A tool that generates images using the GPT image models. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `type: "image_generation"` - - `sequence_number: number` + The type of the image generation tool. Always `image_generation`. - The sequence number of this event. + - `action: optional "generate" or "edit" or "auto"` - - `type: "response.in_progress"` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the event. Always `response.in_progress`. + - `"generate"` - - `agent: optional object { agent_name }` + - `"edit"` - The agent that owns this multi-agent streaming event. + - `"auto"` - - `agent_name: string` + - `background: optional "transparent" or "opaque" or "auto"` - The canonical name of the agent that produced this item. + 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. - - `beta_response_failed_event: object { response, sequence_number, type, agent }` + `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. - An event that is emitted when a response fails. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `response: object { id, created_at, error, 31 more }` + - `"transparent"` - The response that failed. + - `"opaque"` - - `id: string` + - `"auto"` - Unique identifier for this Response. + - `input_fidelity: optional "high" or "low"` - - `created_at: number` + 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`. - Unix timestamp (in seconds) of when this Response was created. + - `"high"` - - `error: object { code, message }` + - `"low"` - An error object returned when the model fails to generate a Response. + - `input_image_mask: optional object { file_id, image_url }` - - `incomplete_details: object { reason }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Details about why the response is incomplete. + - `file_id: optional string` - - `instructions: string or array of BetaResponseInputItem` + File ID for the mask image. - A system (or developer) message inserted into the model's context. + - `image_url: optional string` - When using 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. + Base64-encoded mask image. - - `metadata: map[string]` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - 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. + The image generation model to use. Default: `gpt-image-1`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"gpt-image-1"` - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `"gpt-image-1-mini"` - Model ID used to generate the response, like `gpt-4o` 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-image-2"` - - `object: "response"` + - `"gpt-image-2-2026-04-21"` - The object type of this resource - always set to `response`. + - `"gpt-image-1.5"` - - `output: array of BetaResponseOutputItem` + - `"chatgpt-image-latest"` - An array of content items generated by the model. + - `moderation: optional "auto" or "low"` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + Moderation level for the generated image. Default: `auto`. - - `parallel_tool_calls: boolean` + - `"auto"` - Whether to allow the model to run tool calls in parallel. + - `"low"` - - `temperature: number` + - `output_compression: optional number` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + Compression level for the output image. Default: 100. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `output_format: optional "png" or "webp" or "jpeg"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `tools: array of BetaTool` + - `"png"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `"webp"` - We support the following categories of tools: + - `"jpeg"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `partial_images: optional number` - - `top_p: number` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `quality: optional "low" or "medium" or "high" or "auto"` - We generally recommend altering this or `temperature` but not both. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `background: optional boolean` + - `"low"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"medium"` - - `completed_at: optional number` + - `"high"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `"auto"` - - `conversation: optional object { id }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + 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`. - - `max_output_tokens: optional number` + - `"1024x1024"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `"1024x1536"` - - `max_tool_calls: optional number` + - `"1536x1024"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `"auto"` - - `moderation: optional object { input, output }` + - `local_shell: object { type }` - Moderation results for the response input and output, if moderated completions were requested. + A tool that allows the model to execute shell commands in a local environment. - - `previous_response_id: optional string` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - 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`. + A tool that allows the model to execute shell commands. - - `prompt: optional object { id, variables, version }` + - `type: "shell"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The type of the shell tool. Always `shell`. - - `prompt_cache_key: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The tool invocation context(s). - - `prompt_cache_options: optional object { mode, ttl }` + - `"direct"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"programmatic"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `type: "container_auto"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Automatically creates a container for this request - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `file_ids: optional array of string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + An optional list of uploaded files to make available to your code. - **gpt-5 and o-series models only** + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The memory limit for the container. - - `safety_identifier: optional string` + - `"1g"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"4g"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"16g"` - Specifies the processing type used for serving the request. + - `"64g"` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + Network access policy for the container. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `beta_container_network_policy_disabled: object { type }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` - - `text: optional object { format, verbosity }` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + An optional list of skills referenced by id or inline data. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `beta_skill_reference: object { skill_id, type, version }` - - `top_logprobs: optional number` + - `skill_id: string` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The ID of the referenced skill. - - `truncation: optional "auto" or "disabled"` + - `type: "skill_reference"` - The truncation strategy to use for the model response. + References a skill created with the /v1/skills endpoint. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `version: optional string` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `beta_inline_skill: object { description, name, source, type }` - - `user: optional string` + - `description: string` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The description of the skill. - - `sequence_number: number` + - `name: string` - The sequence number of this event. + The name of the skill. - - `type: "response.failed"` + - `source: object { data, media_type, type }` - The type of the event. Always `response.failed`. + Inline skill payload - - `agent: optional object { agent_name }` + - `data: string` - The agent that owns this multi-agent streaming event. + Base64-encoded skill zip bundle. - - `agent_name: string` + - `media_type: "application/zip"` - The canonical name of the agent that produced this item. + The media type of the inline skill payload. Must be `application/zip`. - - `beta_response_incomplete_event: object { response, sequence_number, type, agent }` + - `type: "base64"` - An event that is emitted when a response finishes as incomplete. + The type of the inline skill source. Must be `base64`. - - `response: object { id, created_at, error, 31 more }` + - `type: "inline"` - The response that was incomplete. + Defines an inline skill for this request. - - `id: string` + - `beta_local_environment: object { type, skills }` - Unique identifier for this Response. + - `type: "local"` - - `created_at: number` + Use a local computer environment. - Unix timestamp (in seconds) of when this Response was created. + - `skills: optional array of BetaLocalSkill` - - `error: object { code, message }` + An optional list of skills. - An error object returned when the model fails to generate a Response. + - `description: string` - - `incomplete_details: object { reason }` + The description of the skill. - Details about why the response is incomplete. + - `name: string` - - `instructions: string or array of BetaResponseInputItem` + The name of the skill. - A system (or developer) message inserted into the model's context. + - `path: string` - When using 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. + The path to the directory containing the skill. - - `metadata: map[string]` + - `beta_container_reference: object { container_id, type }` - 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. + - `container_id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The ID of the referenced container. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `type: "container_reference"` - Model ID used to generate the response, like `gpt-4o` 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. + References a container created with the /v1/containers endpoint - - `object: "response"` + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - The object type of this resource - always set to `response`. + 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) - - `output: array of BetaResponseOutputItem` + - `name: string` - An array of content items generated by the model. + The name of the custom tool, used to identify it in tool calls. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `type: "custom"` - - `parallel_tool_calls: boolean` + The type of the custom tool. Always `custom`. - Whether to allow the model to run tool calls in parallel. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `temperature: number` + The tool invocation context(s). - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `"direct"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"programmatic"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `defer_loading: optional boolean` - - `tools: array of BetaTool` + Whether this tool should be deferred and discovered via tool search. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `description: optional string` - We support the following categories of tools: + Optional description of the custom tool, used to provide more context. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `format: optional object { type } or object { definition, syntax, type }` - - `top_p: number` + The input format for the custom tool. Default is unconstrained text. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `text: object { type }` - We generally recommend altering this or `temperature` but not both. + Unconstrained free-form text. - - `background: optional boolean` + - `grammar: object { definition, syntax, type }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + A grammar defined by the user. - - `completed_at: optional number` + - `definition: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The grammar definition. - - `conversation: optional object { id }` + - `syntax: "lark" or "regex"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The syntax of the grammar definition. One of `lark` or `regex`. - - `max_output_tokens: optional number` + - `"lark"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `"regex"` - - `max_tool_calls: optional number` + - `type: "grammar"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + Grammar format. Always `grammar`. - - `moderation: optional object { input, output }` + - `beta_namespace_tool: object { description, name, tools, type }` - Moderation results for the response input and output, if moderated completions were requested. + Groups function/custom tools under a shared namespace. - - `previous_response_id: optional string` + - `description: string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + A description of the namespace shown to the model. - - `prompt: optional object { id, variables, version }` + - `name: string` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The namespace name used in tool calls (for example, `crm`). - - `prompt_cache_key: optional string` + - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The function/custom tools available inside this namespace. - - `prompt_cache_options: optional object { mode, ttl }` + - `function: object { name, type, allowed_callers, 5 more }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `name: string` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `type: "function"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `allowed_callers: optional array of "direct" or "programmatic"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The tool invocation context(s). - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"direct"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"programmatic"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `defer_loading: optional boolean` - **gpt-5 and o-series models only** + Whether this function should be deferred and discovered via tool search. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `description: optional string` - - `safety_identifier: optional string` + - `output_schema: optional map[unknown]` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `parameters: optional unknown` - Specifies the processing type used for serving the request. + - `strict: optional boolean` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + 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. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + 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) - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `name: string` - - `text: optional object { format, verbosity }` + The name of the custom tool, used to identify it in tool calls. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `type: "custom"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + The type of the custom tool. Always `custom`. - - `top_logprobs: optional number` + - `allowed_callers: optional array of "direct" or "programmatic"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + The tool invocation context(s). - - `truncation: optional "auto" or "disabled"` + - `defer_loading: optional boolean` - The truncation strategy to use for the model response. + Whether this tool should be deferred and discovered via tool search. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `description: optional string` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + Optional description of the custom tool, used to provide more context. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `format: optional object { type } or object { definition, syntax, type }` - - `user: optional string` + The input format for the custom tool. Default is unconstrained text. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `type: "namespace"` - - `sequence_number: number` + The type of the tool. Always `namespace`. - The sequence number of this event. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `type: "response.incomplete"` + Hosted or BYOT tool search configuration for deferred tools. - The type of the event. Always `response.incomplete`. + - `type: "tool_search"` - - `agent: optional object { agent_name }` + The type of the tool. Always `tool_search`. - The agent that owns this multi-agent streaming event. + - `description: optional string` - - `agent_name: string` + Description shown to the model for a client-executed tool search tool. - The canonical name of the agent that produced this item. + - `execution: optional "server" or "client"` - - `beta_response_output_item_added_event: object { item, output_index, sequence_number, 2 more }` + Whether tool search is executed by the server or by the client. - Emitted when a new output item is added. + - `"server"` - - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` + - `"client"` - The output item that was added. + - `parameters: optional unknown` - - `beta_response_output_message: object { id, content, role, 4 more }` + Parameter schema for a client-executed tool search tool. - An output message from the model. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + 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). - 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. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"web_search_preview"` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `"web_search_preview_2025_03_11"` - - `agent_message: object { id, author, content, 3 more }` + - `search_content_types: optional array of "text" or "image"` - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `"text"` - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `"image"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `search_context_size: optional "low" or "medium" or "high"` - 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. + 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. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `"low"` - 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. + - `"medium"` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `"high"` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `user_location: optional object { type, city, country, 2 more }` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](https://platform.openai.com/docs/guides/conversation-state). + The user's location. - - `program: object { id, call_id, code, 3 more }` + - `type: "approximate"` - - `program_output: object { id, call_id, result, 3 more }` + The type of location approximation. Always `approximate`. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `city: optional string` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + Free text input for the city of the user, e.g. `San Francisco`. - - `additional_tools: object { id, role, tools, 2 more }` + - `country: optional string` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `region: optional string` - - `image_generation_call: object { id, result, status, 2 more }` + Free text input for the region of the user, e.g. `California`. - An image generation request made by the model. + - `timezone: optional string` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A tool call to run code. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `local_shell_call: object { id, action, call_id, 3 more }` + Allows the assistant to create, delete, or update files using unified diffs. - A tool call to run a command on the local shell. + - `type: "apply_patch"` - - `local_shell_call_output: object { id, output, type, 2 more }` + The type of the tool. Always `apply_patch`. - The output of a local shell tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + The tool invocation context(s). - A tool call that executes one or more shell commands in a managed environment. + - `"direct"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `"programmatic"` - The output of a shell tool call that was emitted. +### Beta Tool Choice Allowed - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` +- `beta_tool_choice_allowed: object { mode, tools, type }` - A tool call that applies file diffs by creating, deleting, or updating files. + Constrains the tools available to the model to a pre-defined set. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `mode: "auto" or "required"` - The output emitted by an apply patch tool call. + Constrains the tools available to the model to a pre-defined set. - - `mcp_call: object { id, arguments, name, 7 more }` + `auto` allows the model to pick from among the allowed tools and generate a + message. - An invocation of a tool on an MCP server. + `required` requires the model to call one or more of the allowed tools. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `"auto"` - A list of tools available on an MCP server. + - `"required"` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `tools: array of map[unknown]` - A request for human approval of a tool invocation. + A list of tool definitions that the model should be allowed to call. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + For the Responses API, the list of tool definitions might look like: - A response to an MCP approval request. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `type: "allowed_tools"` - A call to a custom tool created by the model. + Allowed tool configuration type. Always `allowed_tools`. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` +### Beta Tool Choice Apply Patch - The output of a custom tool call from your code, being sent back to the model. +- `beta_tool_choice_apply_patch: object { type }` - - `output_index: number` + Forces the model to call the apply_patch tool when executing a tool call. - The index of the output item that was added. + - `type: "apply_patch"` - - `sequence_number: number` + The tool to call. Always `apply_patch`. - The sequence number of this event. +### Beta Tool Choice Custom - - `type: "response.output_item.added"` +- `beta_tool_choice_custom: object { name, type }` - The type of the event. Always `response.output_item.added`. + Use this option to force the model to call a specific custom tool. - - `agent: optional object { agent_name }` + - `name: string` - The agent that owns this multi-agent streaming event. + The name of the custom tool to call. - - `agent_name: string` + - `type: "custom"` - The canonical name of the agent that produced this item. + For custom tool calling, the type is always `custom`. - - `beta_response_output_item_done_event: object { item, output_index, sequence_number, 2 more }` +### Beta Tool Choice Function - Emitted when an output item is marked done. +- `beta_tool_choice_function: object { name, type }` - - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` + Use this option to force the model to call a specific function. - The output item that was marked done. + - `name: string` - - `beta_response_output_message: object { id, content, role, 4 more }` + The name of the function to call. - An output message from the model. + - `type: "function"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + For function calling, the type is always `function`. - 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. +### Beta Tool Choice Mcp - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` +- `beta_tool_choice_mcp: object { server_label, type, name }` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + Use this option to force the model to call a specific tool on a remote MCP server. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `server_label: string` - - `agent_message: object { id, author, content, 3 more }` + The label of the MCP server to use. - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `type: "mcp"` - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + For MCP tools, the type is always `mcp`. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `name: optional string` - 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. + The name of the tool to call on the server. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` +### Beta Tool Choice Options - 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. +- `beta_tool_choice_options: "none" or "auto" or "required"` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + Controls which (if any) tool is called by the model. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + `none` means the model will not call any tool and instead generates a message. - 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). + `auto` means the model can pick between generating a message or calling one or + more tools. - - `program: object { id, call_id, code, 3 more }` + `required` means the model must call one or more tools. - - `program_output: object { id, call_id, result, 3 more }` + - `"none"` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `"auto"` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `"required"` - - `additional_tools: object { id, role, tools, 2 more }` +### Beta Tool Choice Shell - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` +- `beta_tool_choice_shell: object { type }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Forces the model to call the shell tool when a tool call is required. - - `image_generation_call: object { id, result, status, 2 more }` + - `type: "shell"` - An image generation request made by the model. + The tool to call. Always `shell`. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` +### Beta Tool Choice Types - A tool call to run code. +- `beta_tool_choice_types: object { type }` - - `local_shell_call: object { id, action, call_id, 3 more }` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). - A tool call to run a command on the local shell. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `local_shell_call_output: object { id, output, type, 2 more }` + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). - The output of a local shell tool call. + Allowed values are: - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - A tool call that executes one or more shell commands in a managed environment. + - `"file_search"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `"web_search_preview"` - The output of a shell tool call that was emitted. + - `"computer"` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `"computer_use_preview"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `"computer_use"` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `"web_search_preview_2025_03_11"` - The output emitted by an apply patch tool call. + - `"image_generation"` - - `mcp_call: object { id, arguments, name, 7 more }` + - `"code_interpreter"` - An invocation of a tool on an MCP server. +### Beta Tool Search Tool - - `mcp_list_tools: object { id, server_label, tools, 3 more }` +- `beta_tool_search_tool: object { type, description, execution, parameters }` - A list of tools available on an MCP server. + Hosted or BYOT tool search configuration for deferred tools. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `type: "tool_search"` - A request for human approval of a tool invocation. + The type of the tool. Always `tool_search`. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `description: optional string` - A response to an MCP approval request. + Description shown to the model for a client-executed tool search tool. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `execution: optional "server" or "client"` - A call to a custom tool created by the model. + Whether tool search is executed by the server or by the client. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `"server"` - The output of a custom tool call from your code, being sent back to the model. + - `"client"` - - `output_index: number` + - `parameters: optional unknown` - The index of the output item that was marked done. + Parameter schema for a client-executed tool search tool. - - `sequence_number: number` +### Beta Web Search Preview Tool - The sequence number of this event. +- `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `type: "response.output_item.done"` + 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). - The type of the event. Always `response.output_item.done`. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `agent: optional object { agent_name }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The agent that owns this multi-agent streaming event. + - `"web_search_preview"` - - `agent_name: string` + - `"web_search_preview_2025_03_11"` - The canonical name of the agent that produced this item. + - `search_content_types: optional array of "text" or "image"` - - `beta_response_reasoning_summary_part_added_event: object { item_id, output_index, part, 4 more }` + - `"text"` - Emitted when a new reasoning summary part is added. + - `"image"` - - `item_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The ID of the item this summary part is associated with. + 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. - - `output_index: number` + - `"low"` - The index of the output item this summary part is associated with. + - `"medium"` - - `part: object { text, type }` + - `"high"` - The summary part that was added. + - `user_location: optional object { type, city, country, 2 more }` - - `text: string` + The user's location. - The text of the summary part. + - `type: "approximate"` - - `type: "summary_text"` + The type of location approximation. Always `approximate`. - The type of the summary part. Always `summary_text`. + - `city: optional string` - - `sequence_number: number` + Free text input for the city of the user, e.g. `San Francisco`. - The sequence number of this event. + - `country: optional string` - - `summary_index: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The index of the summary part within the reasoning summary. + - `region: optional string` - - `type: "response.reasoning_summary_part.added"` + Free text input for the region of the user, e.g. `California`. - The type of the event. Always `response.reasoning_summary_part.added`. + - `timezone: optional string` - - `agent: optional object { agent_name }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The agent that owns this multi-agent streaming event. +### Beta Web Search Tool - - `agent_name: string` +- `beta_web_search_tool: object { type, filters, search_context_size, user_location }` - The canonical name of the agent that produced this item. + 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). - - `beta_response_reasoning_summary_part_done_event: object { item_id, output_index, part, 5 more }` + - `type: "web_search" or "web_search_2025_08_26"` - Emitted when a reasoning summary part is completed. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `item_id: string` + - `"web_search"` - The ID of the item this summary part is associated with. + - `"web_search_2025_08_26"` - - `output_index: number` + - `filters: optional object { allowed_domains }` - The index of the output item this summary part is associated with. + Filters for the search. - - `part: object { text, type }` + - `allowed_domains: optional array of string` - The completed summary part. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `text: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The text of the summary part. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "summary_text"` + 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. - The type of the summary part. Always `summary_text`. + - `"low"` - - `sequence_number: number` + - `"medium"` - The sequence number of this event. + - `"high"` - - `summary_index: number` + - `user_location: optional object { city, country, region, 2 more }` - The index of the summary part within the reasoning summary. + The approximate location of the user. - - `type: "response.reasoning_summary_part.done"` + - `city: optional string` - The type of the event. Always `response.reasoning_summary_part.done`. + Free text input for the city of the user, e.g. `San Francisco`. - - `agent: optional object { agent_name }` + - `country: optional string` - The agent that owns this multi-agent streaming event. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `agent_name: string` + - `region: optional string` - The canonical name of the agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `status: optional "incomplete"` + - `timezone: optional string` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"incomplete"` + - `type: optional "approximate"` - - `beta_response_reasoning_summary_text_delta_event: object { delta, item_id, output_index, 4 more }` + The type of location approximation. Always `approximate`. - Emitted when a delta is added to a reasoning summary text. + - `"approximate"` - - `delta: string` +# Input Items - The text delta that was added to the summary. +## List input items - - `item_id: string` +`$ openai beta:responses:input-items list` - The ID of the item this summary text delta is associated with. +**get** `/responses/{response_id}/input_items?beta=true` - - `output_index: number` +Returns a list of input items for a given response. - The index of the output item this summary text delta is associated with. +### Parameters - - `sequence_number: number` +- `--response-id: string` - The sequence number of this event. + Path param: The ID of the response to retrieve input items for. - - `summary_index: number` +- `--after: optional string` - The index of the summary part within the reasoning summary. + Query param: An item ID to list items after, used in pagination. - - `type: "response.reasoning_summary_text.delta"` +- `--include: optional array of BetaResponseIncludable` - The type of the event. Always `response.reasoning_summary_text.delta`. + Query param: Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - - `agent: optional object { agent_name }` +- `--limit: optional number` - The agent that owns this multi-agent streaming event. + Query param: A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. - - `agent_name: string` +- `--order: optional "asc" or "desc"` - The canonical name of the agent that produced this item. + Query param: The order to return the input items in. Default is `desc`. - - `beta_response_reasoning_summary_text_done_event: object { item_id, output_index, sequence_number, 4 more }` + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. - Emitted when a reasoning summary text is completed. +- `--beta: optional array of "responses_multi_agent=v1"` - - `item_id: string` + Header param: Optional beta features to enable for this request. - The ID of the item this summary text is associated with. +### Returns - - `output_index: number` +- `beta_responseItemList: object { data, first_id, has_more, 2 more }` - The index of the output item this summary text is associated with. + A list of Response items. - - `sequence_number: number` + - `data: array of BetaResponseItem` - The sequence number of this event. + A list of items used to generate this response. - - `summary_index: number` + - `beta_response_input_message_item: object { id, content, role, 3 more }` - The index of the summary part within the reasoning summary. + - `id: string` - - `text: string` + The unique ID of the message input. - The full text of the completed reasoning summary. + - `content: array of BetaResponseInputContent` - - `type: "response.reasoning_summary_text.done"` + A list of one or many input items to the model, containing different content + types. - The type of the event. Always `response.reasoning_summary_text.done`. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that owns this multi-agent streaming event. + - `text: string` - - `agent_name: string` + The text input to the model. - The canonical name of the agent that produced this item. + - `type: "input_text"` - - `beta_response_reasoning_text_delta_event: object { content_index, delta, item_id, 4 more }` + The type of the input item. Always `input_text`. - Emitted when a delta is added to a reasoning text. + - `prompt_cache_breakpoint: optional object { mode }` - - `content_index: number` + 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. - The index of the reasoning content part this delta is associated with. + - `mode: "explicit"` - - `delta: string` + The breakpoint mode. Always `explicit`. - The text delta that was added to the reasoning content. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - `item_id: string` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The ID of the item this reasoning text delta is associated with. + - `detail: "low" or "high" or "auto" or "original"` - - `output_index: number` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The index of the output item this reasoning text delta is associated with. + - `"low"` - - `sequence_number: number` + - `"high"` - The sequence number of this event. + - `"auto"` - - `type: "response.reasoning_text.delta"` + - `"original"` - The type of the event. Always `response.reasoning_text.delta`. + - `type: "input_image"` - - `agent: optional object { agent_name }` + The type of the input item. Always `input_image`. - The agent that owns this multi-agent streaming event. + - `file_id: optional string` - - `agent_name: string` + The ID of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `image_url: optional string` - - `beta_response_reasoning_text_done_event: object { content_index, item_id, output_index, 4 more }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Emitted when a reasoning text is completed. + - `prompt_cache_breakpoint: optional object { mode }` - - `content_index: number` + 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. - The index of the reasoning content part. + - `mode: "explicit"` - - `item_id: string` + The breakpoint mode. Always `explicit`. - The ID of the item this reasoning text is associated with. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `output_index: number` + A file input to the model. - The index of the output item this reasoning text is associated with. + - `type: "input_file"` - - `sequence_number: number` + The type of the input item. Always `input_file`. - The sequence number of this event. + - `detail: optional "auto" or "low" or "high"` - - `text: string` + 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`. - The full text of the completed reasoning content. + - `"auto"` - - `type: "response.reasoning_text.done"` + - `"low"` - The type of the event. Always `response.reasoning_text.done`. + - `"high"` - - `agent: optional object { agent_name }` + - `file_data: optional string` - The agent that owns this multi-agent streaming event. + The content of the file to be sent to the model. - - `agent_name: string` + - `file_id: optional string` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. - - `beta_response_refusal_delta_event: object { content_index, delta, item_id, 4 more }` + - `file_url: optional string` - Emitted when there is a partial refusal text. + The URL of the file to be sent to the model. - - `content_index: number` + - `filename: optional string` - The index of the content part that the refusal text is added to. + The name of the file to be sent to the model. - - `delta: string` + - `prompt_cache_breakpoint: optional object { mode }` - The refusal text that is added. + 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. - - `item_id: string` + - `mode: "explicit"` - The ID of the output item that the refusal text is added to. + The breakpoint mode. Always `explicit`. - - `output_index: number` + - `role: "user" or "system" or "developer"` - The index of the output item that the refusal text is added to. + The role of the message input. One of `user`, `system`, or `developer`. - - `sequence_number: number` + - `"user"` - The sequence number of this event. + - `"system"` - - `type: "response.refusal.delta"` + - `"developer"` - The type of the event. Always `response.refusal.delta`. + - `type: "message"` + + The type of the message input. Always set to `message`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_refusal_done_event: object { content_index, item_id, output_index, 4 more }` - - Emitted when refusal text is finalized. - - - `content_index: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The index of the content part that the refusal text is finalized. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `item_id: string` + - `"in_progress"` - The ID of the output item that the refusal text is finalized. + - `"completed"` - - `output_index: number` + - `"incomplete"` - The index of the output item that the refusal text is finalized. + - `beta_response_output_message: object { id, content, role, 4 more }` - - `refusal: string` + An output message from the model. - The refusal text that is finalized. + - `id: string` - - `sequence_number: number` + The unique ID of the output message. - The sequence number of this event. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `type: "response.refusal.done"` + The content of the output message. - The type of the event. Always `response.refusal.done`. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `agent: optional object { agent_name }` + A text output from the model. - The agent that owns this multi-agent streaming event. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `agent_name: string` + The annotations of the text output. - The canonical name of the agent that produced this item. + - `file_citation: object { file_id, filename, index, type }` - - `beta_response_text_delta_event: object { content_index, delta, item_id, 5 more }` + A citation to a file. - Emitted when there is an additional text delta. + - `file_id: string` - - `content_index: number` + The ID of the file. - The index of the content part that the text delta was added to. + - `filename: string` - - `delta: string` + The filename of the file cited. - The text delta that was added. + - `index: number` - - `item_id: string` + The index of the file in the list of files. - The ID of the output item that the text delta was added to. + - `type: "file_citation"` - - `logprobs: array of object { token, logprob, top_logprobs }` + The type of the file citation. Always `file_citation`. - The log probabilities of the tokens in the delta. + - `url_citation: object { end_index, start_index, title, 2 more }` - - `token: string` + A citation for a web resource used to generate a model response. - A possible text token. + - `end_index: number` - - `logprob: number` + The index of the last character of the URL citation in the message. - The log probability of this token. + - `start_index: number` - - `top_logprobs: optional array of object { token, logprob }` + The index of the first character of the URL citation in the message. - The log probabilities of up to 20 of the most likely tokens. + - `title: string` - - `token: optional string` + The title of the web resource. - A possible text token. + - `type: "url_citation"` - - `logprob: optional number` + The type of the URL citation. Always `url_citation`. - The log probability of this token. + - `url: string` - - `output_index: number` + The URL of the web resource. - The index of the output item that the text delta was added to. + - `container_file_citation: object { container_id, end_index, file_id, 3 more }` - - `sequence_number: number` + A citation for a container file used to generate a model response. - The sequence number for this event. + - `container_id: string` - - `type: "response.output_text.delta"` + The ID of the container file. - The type of the event. Always `response.output_text.delta`. + - `end_index: number` - - `agent: optional object { agent_name }` + The index of the last character of the container file citation in the message. - The agent that owns this multi-agent streaming event. + - `file_id: string` - - `agent_name: string` + The ID of the file. - The canonical name of the agent that produced this item. + - `filename: string` - - `beta_response_text_done_event: object { content_index, item_id, logprobs, 5 more }` + The filename of the container file cited. - Emitted when text content is finalized. + - `start_index: number` - - `content_index: number` + The index of the first character of the container file citation in the message. - The index of the content part that the text content is finalized. + - `type: "container_file_citation"` - - `item_id: string` + The type of the container file citation. Always `container_file_citation`. - The ID of the output item that the text content is finalized. + - `file_path: object { file_id, index, type }` - - `logprobs: array of object { token, logprob, top_logprobs }` + A path to a file. - The log probabilities of the tokens in the delta. + - `file_id: string` - - `token: string` + The ID of the file. - A possible text token. + - `index: number` - - `logprob: number` + The index of the file in the list of files. - The log probability of this token. + - `type: "file_path"` - - `top_logprobs: optional array of object { token, logprob }` + The type of the file path. Always `file_path`. - The log probabilities of up to 20 of the most likely tokens. + - `text: string` - - `token: optional string` + The text output from the model. - A possible text token. + - `type: "output_text"` - - `logprob: optional number` + The type of the output text. Always `output_text`. - The log probability of this token. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `output_index: number` + - `token: string` - The index of the output item that the text content is finalized. + - `bytes: array of number` - - `sequence_number: number` + - `logprob: number` - The sequence number for this event. + - `top_logprobs: array of object { token, bytes, logprob }` - - `text: string` + - `token: string` - The text content that is finalized. + - `bytes: array of number` - - `type: "response.output_text.done"` + - `logprob: number` - The type of the event. Always `response.output_text.done`. + - `beta_response_output_refusal: object { refusal, type }` - - `agent: optional object { agent_name }` + A refusal from the model. - The agent that owns this multi-agent streaming event. + - `refusal: string` - - `agent_name: string` + The refusal explanation from the model. - The canonical name of the agent that produced this item. + - `type: "refusal"` - - `beta_response_web_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + The type of the refusal. Always `refusal`. - Emitted when a web search call is completed. + - `role: "assistant"` - - `item_id: string` + The role of the output message. Always `assistant`. - Unique ID for the output item associated with the web search call. + - `status: "in_progress" or "completed" or "incomplete"` - - `output_index: number` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The index of the output item that the web search call is associated with. + - `"in_progress"` - - `sequence_number: number` + - `"completed"` - The sequence number of the web search call being processed. + - `"incomplete"` - - `type: "response.web_search_call.completed"` + - `type: "message"` - The type of the event. Always `response.web_search_call.completed`. + The type of the output message. Always `message`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_web_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a web search call is initiated. - - - `item_id: string` - - Unique ID for the output item associated with the web search call. - - - `output_index: number` - - The index of the output item that the web search call is associated with. + - `phase: optional "commentary" or "final_answer"` - - `sequence_number: number` + 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. - The sequence number of the web search call being processed. + - `"commentary"` - - `type: "response.web_search_call.in_progress"` + - `"final_answer"` - The type of the event. Always `response.web_search_call.in_progress`. + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` - - `agent: optional object { agent_name }` + 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. - The agent that owns this multi-agent streaming event. + - `id: string` - - `agent_name: string` + The unique ID of the file search tool call. - The canonical name of the agent that produced this item. + - `queries: array of string` - - `beta_response_web_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` + The queries used to search for files. - Emitted when a web search call is executing. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `item_id: string` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Unique ID for the output item associated with the web search call. + - `"in_progress"` - - `output_index: number` + - `"searching"` - The index of the output item that the web search call is associated with. + - `"completed"` - - `sequence_number: number` + - `"incomplete"` - The sequence number of the web search call being processed. + - `"failed"` - - `type: "response.web_search_call.searching"` + - `type: "file_search_call"` - The type of the event. Always `response.web_search_call.searching`. + The type of the file search tool call. Always `file_search_call`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_image_gen_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Emitted when an image generation tool call has completed and the final image is available. + The results of the file search tool call. - - `item_id: string` + - `attributes: optional map[string or number or boolean]` - The unique identifier of the image generation item being processed. + 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. - - `output_index: number` + - `union_member_0: string` - The index of the output item in the response's output array. + - `union_member_1: number` - - `sequence_number: number` + - `union_member_2: boolean` - The sequence number of this event. + - `file_id: optional string` - - `type: "response.image_generation_call.completed"` + The unique ID of the file. - The type of the event. Always 'response.image_generation_call.completed'. + - `filename: optional string` - - `agent: optional object { agent_name }` + The name of the file. - The agent that owns this multi-agent streaming event. + - `score: optional number` - - `agent_name: string` + The relevance score of the file - a value between 0 and 1. - The canonical name of the agent that produced this item. + - `text: optional string` - - `beta_response_image_gen_call_generating_event: object { item_id, output_index, sequence_number, 2 more }` + The text that was retrieved from the file. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` - - `item_id: string` + 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. - The unique identifier of the image generation item being processed. + - `id: string` - - `output_index: number` + The unique ID of the computer call. - The index of the output item in the response's output array. + - `call_id: string` - - `sequence_number: number` + An identifier used when responding to the tool call with output. - The sequence number of the image generation item being processed. + - `pending_safety_checks: array of object { id, code, message }` - - `type: "response.image_generation_call.generating"` + The pending safety checks for the computer call. - The type of the event. Always 'response.image_generation_call.generating'. + - `id: string` - - `agent: optional object { agent_name }` + The ID of the pending safety check. - The agent that owns this multi-agent streaming event. + - `code: optional string` - - `agent_name: string` + The type of the pending safety check. - The canonical name of the agent that produced this item. + - `message: optional string` - - `beta_response_image_gen_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + Details about the pending safety check. - Emitted when an image generation tool call is in progress. + - `status: "in_progress" or "completed" or "incomplete"` - - `item_id: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The unique identifier of the image generation item being processed. + - `"in_progress"` - - `output_index: number` + - `"completed"` - The index of the output item in the response's output array. + - `"incomplete"` - - `sequence_number: number` + - `type: "computer_call"` - The sequence number of the image generation item being processed. + The type of the computer call. Always `computer_call`. - - `type: "response.image_generation_call.in_progress"` + - `"computer_call"` - The type of the event. Always 'response.image_generation_call.in_progress'. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `agent: optional object { agent_name }` + A click action. - The agent that owns this multi-agent streaming event. + - `click: object { button, type, x, 2 more }` - - `agent_name: string` + A click action. - The canonical name of the agent that produced this item. + - `button: "left" or "right" or "wheel" or 2 more` - - `beta_response_image_gen_call_partial_image_event: object { item_id, output_index, partial_image_b64, 4 more }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Emitted when a partial image is available during image generation streaming. + - `"left"` - - `item_id: string` + - `"right"` - The unique identifier of the image generation item being processed. + - `"wheel"` - - `output_index: number` + - `"back"` - The index of the output item in the response's output array. + - `"forward"` - - `partial_image_b64: string` + - `type: "click"` - Base64-encoded partial image data, suitable for rendering as an image. + Specifies the event type. For a click action, this property is always `click`. - - `partial_image_index: number` + - `x: number` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + The x-coordinate where the click occurred. - - `sequence_number: number` + - `y: number` - The sequence number of the image generation item being processed. + The y-coordinate where the click occurred. - - `type: "response.image_generation_call.partial_image"` + - `keys: optional array of string` - The type of the event. Always 'response.image_generation_call.partial_image'. + The keys being held while clicking. - - `agent: optional object { agent_name }` + - `double_click: object { keys, type, x, y }` - The agent that owns this multi-agent streaming event. + A double click action. - - `agent_name: string` + - `keys: array of string` - The canonical name of the agent that produced this item. + The keys being held while double-clicking. - - `beta_response_mcp_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` + - `type: "double_click"` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `delta: string` + - `x: number` - A JSON string containing the partial update to the arguments for the MCP tool call. + The x-coordinate where the double click occurred. - - `item_id: string` + - `y: number` - The unique identifier of the MCP tool call item being processed. + The y-coordinate where the double click occurred. - - `output_index: number` + - `drag: object { path, type, keys }` - The index of the output item in the response's output array. + A drag action. - - `sequence_number: number` + - `path: array of object { x, y }` - The sequence number of this event. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `type: "response.mcp_call_arguments.delta"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `x: number` - - `agent: optional object { agent_name }` + The x-coordinate. - The agent that owns this multi-agent streaming event. + - `y: number` - - `agent_name: string` + The y-coordinate. - The canonical name of the agent that produced this item. + - `type: "drag"` - - `beta_response_mcp_call_arguments_done_event: object { arguments, item_id, output_index, 3 more }` + Specifies the event type. For a drag action, this property is always set to `drag`. - Emitted when the arguments for an MCP tool call are finalized. + - `keys: optional array of string` - - `arguments: string` + The keys being held while dragging the mouse. - A JSON string containing the finalized arguments for the MCP tool call. + - `keypress: object { keys, type }` - - `item_id: string` + A collection of keypresses the model would like to perform. - The unique identifier of the MCP tool call item being processed. + - `keys: array of string` - - `output_index: number` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The index of the output item in the response's output array. + - `type: "keypress"` - - `sequence_number: number` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The sequence number of this event. + - `move: object { type, x, y, keys }` - - `type: "response.mcp_call_arguments.done"` + A mouse move action. - The type of the event. Always 'response.mcp_call_arguments.done'. + - `type: "move"` - - `agent: optional object { agent_name }` + Specifies the event type. For a move action, this property is always set to `move`. - The agent that owns this multi-agent streaming event. + - `x: number` - - `agent_name: string` + The x-coordinate to move to. - The canonical name of the agent that produced this item. + - `y: number` - - `beta_response_mcp_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + The y-coordinate to move to. - Emitted when an MCP tool call has completed successfully. + - `keys: optional array of string` - - `item_id: string` + The keys being held while moving the mouse. - The ID of the MCP tool call item that completed. + - `screenshot: object { type }` - - `output_index: number` + A screenshot action. - The index of the output item that completed. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `sequence_number: number` + A scroll action. - The sequence number of this event. + - `scroll_x: number` - - `type: "response.mcp_call.completed"` + The horizontal scroll distance. - The type of the event. Always 'response.mcp_call.completed'. + - `scroll_y: number` - - `agent: optional object { agent_name }` + The vertical scroll distance. - The agent that owns this multi-agent streaming event. + - `type: "scroll"` - - `agent_name: string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The canonical name of the agent that produced this item. + - `x: number` - - `beta_response_mcp_call_failed_event: object { item_id, output_index, sequence_number, 2 more }` + The x-coordinate where the scroll occurred. - Emitted when an MCP tool call has failed. + - `y: number` - - `item_id: string` + The y-coordinate where the scroll occurred. - The ID of the MCP tool call item that failed. + - `keys: optional array of string` - - `output_index: number` + The keys being held while scrolling. - The index of the output item that failed. + - `type: object { text, type }` - - `sequence_number: number` + An action to type in text. - The sequence number of this event. + - `text: string` - - `type: "response.mcp_call.failed"` + The text to type. - The type of the event. Always 'response.mcp_call.failed'. + - `type: "type"` - - `agent: optional object { agent_name }` + Specifies the event type. For a type action, this property is always set to `type`. - The agent that owns this multi-agent streaming event. + - `wait: object { type }` - - `agent_name: string` + A wait action. - The canonical name of the agent that produced this item. + - `actions: optional array of BetaComputerAction` - - `beta_response_mcp_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Emitted when an MCP tool call is in progress. + - `click: object { button, type, x, 2 more }` - - `item_id: string` + A click action. - The unique identifier of the MCP tool call item being processed. + - `double_click: object { keys, type, x, y }` - - `output_index: number` + A double click action. - The index of the output item in the response's output array. + - `drag: object { path, type, keys }` - - `sequence_number: number` + A drag action. - The sequence number of this event. + - `keypress: object { keys, type }` - - `type: "response.mcp_call.in_progress"` + A collection of keypresses the model would like to perform. - The type of the event. Always 'response.mcp_call.in_progress'. + - `move: object { type, x, y, keys }` - - `agent: optional object { agent_name }` + A mouse move action. - The agent that owns this multi-agent streaming event. + - `screenshot: object { type }` - - `agent_name: string` + A screenshot action. - The canonical name of the agent that produced this item. + - `scroll: object { scroll_x, scroll_y, type, 3 more }` - - `beta_response_mcp_list_tools_completed_event: object { item_id, output_index, sequence_number, 2 more }` + A scroll action. - Emitted when the list of available MCP tools has been successfully retrieved. + - `type: object { text, type }` - - `item_id: string` + An action to type in text. - The ID of the MCP tool call item that produced this output. + - `wait: object { type }` - - `output_index: number` + A wait action. - The index of the output item that was processed. + - `agent: optional object { agent_name }` - - `sequence_number: number` + The agent that produced this item. - The sequence number of this event. + - `agent_name: string` - - `type: "response.mcp_list_tools.completed"` + The canonical name of the agent that produced this item. - The type of the event. Always 'response.mcp_list_tools.completed'. + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - - `agent: optional object { agent_name }` + - `id: string` - The agent that owns this multi-agent streaming event. + The unique ID of the computer call tool output. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + The ID of the computer tool call that produced the output. - - `beta_response_mcp_list_tools_failed_event: object { item_id, output_index, sequence_number, 2 more }` + - `output: object { type, file_id, image_url }` - Emitted when the attempt to list available MCP tools has failed. + A computer screenshot image used with the computer use tool. - - `item_id: string` + - `type: "computer_screenshot"` - The ID of the MCP tool call item that failed. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `output_index: number` + - `file_id: optional string` - The index of the output item that failed. + The identifier of an uploaded file that contains the screenshot. - - `sequence_number: number` + - `image_url: optional string` - The sequence number of this event. + The URL of the screenshot image. - - `type: "response.mcp_list_tools.failed"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The type of the event. Always 'response.mcp_list_tools.failed'. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `agent: optional object { agent_name }` + - `"completed"` - The agent that owns this multi-agent streaming event. + - `"incomplete"` - - `agent_name: string` + - `"failed"` - The canonical name of the agent that produced this item. + - `"in_progress"` - - `beta_response_mcp_list_tools_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + - `type: "computer_call_output"` - Emitted when the system is in the process of retrieving the list of available MCP tools. + The type of the computer tool call output. Always `computer_call_output`. - - `item_id: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The ID of the MCP tool call item that is being processed. + The safety checks reported by the API that have been acknowledged by the + developer. - - `output_index: number` + - `id: string` - The index of the output item that is being processed. + The ID of the pending safety check. - - `sequence_number: number` + - `code: optional string` - The sequence number of this event. + The type of the pending safety check. - - `type: "response.mcp_list_tools.in_progress"` + - `message: optional string` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + Details about the pending safety check. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` + - `created_by: optional string` - Emitted when an annotation is added to output text content. + The identifier of the actor that created the item. - - `annotation: unknown` + - `beta_response_function_web_search: object { id, action, status, 2 more }` - The annotation object being added. (See annotation schema for details.) + 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. - - `annotation_index: number` + - `id: string` - The index of the annotation within the content part. + The unique ID of the web search tool call. - - `content_index: number` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The index of the content part within the output item. + 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). - - `item_id: string` + - `search: object { type, queries, query, sources }` - The unique identifier of the item to which the annotation is being added. + Action type "search" - Performs a web search query. - - `output_index: number` + - `type: "search"` - The index of the output item in the response's output array. + The action type. - - `sequence_number: number` + - `queries: optional array of string` - The sequence number of this event. + The search queries. - - `type: "response.output_text.annotation.added"` + - `query: optional string` - The type of the event. Always 'response.output_text.annotation.added'. + The search query. - - `agent: optional object { agent_name }` + - `sources: optional array of object { type, url }` - The agent that owns this multi-agent streaming event. + The sources used in the search. - - `agent_name: string` + - `type: "url"` - The canonical name of the agent that produced this item. + The type of source. Always `url`. - - `beta_response_queued_event: object { response, sequence_number, type, agent }` + - `url: string` - Emitted when a response is queued and waiting to be processed. + The URL of the source. - - `response: object { id, created_at, error, 31 more }` + - `open_page: object { type, url }` - The full response object that is queued. + Action type "open_page" - Opens a specific URL from search results. - - `id: string` + - `type: "open_page"` - Unique identifier for this Response. + The action type. - - `created_at: number` + - `url: optional string` - Unix timestamp (in seconds) of when this Response was created. + The URL opened by the model. - - `error: object { code, message }` + - `find_in_page: object { pattern, type, url }` - An error object returned when the model fails to generate a Response. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `incomplete_details: object { reason }` + - `pattern: string` - Details about why the response is incomplete. + The pattern or text to search for within the page. - - `instructions: string or array of BetaResponseInputItem` + - `type: "find_in_page"` - A system (or developer) message inserted into the model's context. + The action type. - When using 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. + - `url: string` - - `metadata: map[string]` + The URL of the page searched for the pattern. - 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. + - `status: "in_progress" or "searching" or "completed" or "failed"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The status of the web search tool call. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `"in_progress"` - Model ID used to generate the response, like `gpt-4o` 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. + - `"searching"` - - `object: "response"` + - `"completed"` - The object type of this resource - always set to `response`. + - `"failed"` - - `output: array of BetaResponseOutputItem` + - `type: "web_search_call"` - An array of content items generated by the model. + The type of the web search tool call. Always `web_search_call`. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `agent: optional object { agent_name }` - - `parallel_tool_calls: boolean` + The agent that produced this item. - Whether to allow the model to run tool calls in parallel. + - `agent_name: string` - - `temperature: number` + The canonical name of the agent that produced this item. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `id: string` - - `tools: array of BetaTool` + The unique ID of the function tool call. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `status: "in_progress" or "completed" or "incomplete"` - We support the following categories of tools: + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `"in_progress"` - - `top_p: number` + - `"completed"` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `"incomplete"` - We generally recommend altering this or `temperature` but not both. + - `created_by: optional string` - - `background: optional boolean` + The identifier of the actor that created the item. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` - - `completed_at: optional number` + - `id: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The unique ID of the function call tool output. - - `conversation: optional object { id }` + - `call_id: string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The unique ID of the function tool call generated by the model. - - `max_output_tokens: optional number` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The output from the function call generated by your code. + Can be a string or an list of output content. - - `max_tool_calls: optional number` + - `string output: string` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + A string of the output of the function call. - - `moderation: optional object { input, output }` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Moderation results for the response input and output, if moderated completions were requested. + Text, image, or file output of the function call. - - `previous_response_id: optional string` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - 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`. + A text input to the model. - - `prompt: optional object { id, variables, version }` + - `text: string` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + The text input to the model. - - `prompt_cache_key: optional string` + - `type: "input_text"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + The type of the input item. Always `input_text`. - - `prompt_cache_options: optional object { mode, ttl }` + - `prompt_cache_breakpoint: optional object { mode }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + 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. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - Deprecated. Use `prompt_cache_options.ttl` instead. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `detail: "low" or "high" or "auto" or "original"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: "input_image"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The type of the input item. Always `input_image`. - **gpt-5 and o-series models only** + - `file_id: optional string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The ID of the file to be sent to the model. - - `safety_identifier: optional string` + - `image_url: optional string` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `prompt_cache_breakpoint: optional object { mode }` - Specifies the processing type used for serving the request. + 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. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + A file input to the model. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `type: "input_file"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The type of the input item. Always `input_file`. - - `text: optional object { format, verbosity }` + - `detail: optional "auto" or "low" or "high"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + 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`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `file_data: optional string` - - `top_logprobs: optional number` + The content of the file to be sent to the model. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `file_id: optional string` - - `truncation: optional "auto" or "disabled"` + The ID of the file to be sent to the model. - The truncation strategy to use for the model response. + - `file_url: optional string` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The URL of the file to be sent to the model. - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `filename: optional string` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The name of the file to be sent to the model. - - `user: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + 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. - - `sequence_number: number` + - `status: "in_progress" or "completed" or "incomplete"` - The sequence number for this event. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "response.queued"` + - `"in_progress"` - The type of the event. Always 'response.queued'. + - `"completed"` + + - `"incomplete"` + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `beta_response_custom_tool_call_input_delta_event: object { delta, item_id, output_index, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - Event representing a delta (partial update) to the input of a custom tool call. + The execution context that produced this tool call. - - `delta: string` + - `direct: object { type }` - The incremental input data (delta) for the custom tool call. + - `program: object { caller_id, type }` - - `item_id: string` + - `caller_id: string` - Unique identifier for the API item associated with this event. + The call ID of the program item that produced this tool call. - - `output_index: number` + - `type: "program"` - The index of the output this delta applies to. + The caller type. Always `program`. - - `sequence_number: number` + - `created_by: optional string` - The sequence number of this event. + The identifier of the actor that created the item. - - `type: "response.custom_tool_call_input.delta"` + - `agent_message: object { id, author, content, 3 more }` - The event type identifier. + - `id: string` - - `agent: optional object { agent_name }` + The unique ID of the agent message. - The agent that owns this multi-agent streaming event. + - `author: string` - - `agent_name: string` + The sending agent identity. - The canonical name of the agent that produced this item. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `beta_response_custom_tool_call_input_done_event: object { input, item_id, output_index, 3 more }` + Encrypted content sent between agents. - Event indicating that input for a custom tool call is complete. + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - `input: string` + A text input to the model. - The complete input data for the custom tool call. + - `beta_response_output_text: object { annotations, text, type, logprobs }` - - `item_id: string` + A text output from the model. - Unique identifier for the API item associated with this event. + - `text: object { text, type }` - - `output_index: number` + A text content. - The index of the output this event applies to. + - `text: string` - - `sequence_number: number` + - `type: "text"` - The sequence number of this event. + - `summary_text: object { text, type }` - - `type: "response.custom_tool_call_input.done"` + A summary text from the model. - The event type identifier. + - `text: string` - - `agent: optional object { agent_name }` + A summary of the reasoning output from the model so far. - The agent that owns this multi-agent streaming event. + - `type: "summary_text"` - - `agent_name: string` + The type of the object. Always `summary_text`. - The canonical name of the agent that produced this item. + - `reasoning_text: object { text, type }` -### Beta Response Text Config + Reasoning text from the model. -- `beta_response_text_config: object { format, verbosity }` + - `text: string` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The reasoning text from the model. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `type: "reasoning_text"` - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + The type of the reasoning text. Always `reasoning_text`. - An object specifying the format that the model must output. + - `beta_response_output_refusal: object { refusal, type }` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + A refusal from the model. - The default format is `{ "type": "text" }` with no additional options. + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - **Not recommended for gpt-4o and newer models:** + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` - - `text: object { type }` + A screenshot of a computer. - Default response format. Used to generate text responses. + - `detail: "low" or "high" or "auto" or "original"` - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `"low"` - - `name: string` + - `"high"` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `"auto"` - - `schema: map[unknown]` + - `"original"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `file_id: string` - - `type: "json_schema"` + The identifier of an uploaded file that contains the screenshot. - The type of response format being defined. Always `json_schema`. + - `image_url: string` - - `description: optional string` + The URL of the screenshot image. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `type: "computer_screenshot"` - - `strict: optional boolean` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `prompt_cache_breakpoint: optional object { mode }` - - `json_object: object { type }` + 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. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `mode: "explicit"` - - `verbosity: optional "low" or "medium" or "high"` + The breakpoint mode. Always `explicit`. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - `"low"` + A file input to the model. - - `"medium"` + - `encrypted_content: object { encrypted_content, type }` - - `"high"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. -### Beta Response Text Delta Event + - `encrypted_content: string` -- `beta_response_text_delta_event: object { content_index, delta, item_id, 5 more }` + Opaque encrypted content. - Emitted when there is an additional text delta. + - `type: "encrypted_content"` - - `content_index: number` + The type of the input item. Always `encrypted_content`. - The index of the content part that the text delta was added to. + - `recipient: string` - - `delta: string` + The destination agent identity. - The text delta that was added. + - `type: "agent_message"` - - `item_id: string` + The type of the item. Always `agent_message`. - The ID of the output item that the text delta was added to. + - `agent: optional object { agent_name }` - - `logprobs: array of object { token, logprob, top_logprobs }` + The agent that produced this item. - The log probabilities of the tokens in the delta. + - `agent_name: string` - - `token: string` + The canonical name of the agent that produced this item. - A possible text token. + - `multi_agent_call: object { id, action, arguments, 3 more }` - - `logprob: number` + - `id: string` - The log probability of this token. + The unique ID of the multi-agent call item. - - `top_logprobs: optional array of object { token, logprob }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The log probabilities of up to 20 of the most likely tokens. + The multi-agent action to execute. - - `token: optional string` + - `"spawn_agent"` - A possible text token. + - `"interrupt_agent"` - - `logprob: optional number` + - `"list_agents"` - The log probability of this token. + - `"send_message"` - - `output_index: number` + - `"followup_task"` - The index of the output item that the text delta was added to. + - `"wait_agent"` - - `sequence_number: number` + - `arguments: string` - The sequence number for this event. + The JSON string of arguments generated for the action. - - `type: "response.output_text.delta"` + - `call_id: string` - The type of the event. Always `response.output_text.delta`. + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Text Done Event - -- `beta_response_text_done_event: object { content_index, item_id, logprobs, 5 more }` - - Emitted when text content is finalized. - - - `content_index: number` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` - The index of the content part that the text content is finalized. + - `id: string` - - `item_id: string` + The unique ID of the multi-agent call output item. - The ID of the output item that the text content is finalized. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `logprobs: array of object { token, logprob, top_logprobs }` + The multi-agent action that produced this result. - The log probabilities of the tokens in the delta. + - `"spawn_agent"` - - `token: string` + - `"interrupt_agent"` - A possible text token. + - `"list_agents"` - - `logprob: number` + - `"send_message"` - The log probability of this token. + - `"followup_task"` - - `top_logprobs: optional array of object { token, logprob }` + - `"wait_agent"` - The log probabilities of up to 20 of the most likely tokens. + - `call_id: string` - - `token: optional string` + The unique ID of the multi-agent call. - A possible text token. + - `output: array of BetaResponseOutputText` - - `logprob: optional number` + Text output returned by the multi-agent action. - The log probability of this token. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `output_index: number` + The annotations of the text output. - The index of the output item that the text content is finalized. + - `text: string` - - `sequence_number: number` + The text output from the model. - The sequence number for this event. + - `type: "output_text"` - - `text: string` + The type of the output text. Always `output_text`. - The text content that is finalized. + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - - `type: "response.output_text.done"` + - `type: "multi_agent_call_output"` - The type of the event. Always `response.output_text.done`. + The type of the multi-agent result. Always `multi_agent_call_output`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Tool Search Call - -- `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - `id: string` @@ -122124,9 +134451,7 @@ openai beta:responses compact \ The identifier of the actor that created the item. -### Beta Response Tool Search Output Item - -- `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - `id: string` @@ -122251,7 +134576,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -122261,7 +134586,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -122308,7 +134637,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -122318,7 +134647,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -123204,1051 +135537,771 @@ openai beta:responses compact \ The identifier of the actor that created the item. -### Beta Response Tool Search Output Item Param - -- `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - - `tools: array of BetaTool` - - The loaded tool definitions returned by the tool search output. - - - `beta_function_tool: object { name, parameters, strict, 5 more }` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `name: string` - - The name of the function to call. + - `additional_tools: object { id, role, tools, 2 more }` - - `parameters: map[unknown]` + - `id: string` - A JSON schema object describing the parameters of the function. + The unique ID of the additional tools item. - - `strict: boolean` + - `role: "unknown" or "user" or "assistant" or 5 more` - Whether strict parameter validation is enforced for this function tool. + The role that provided the additional tools. - - `type: "function"` + - `"unknown"` - The type of the function tool. Always `function`. + - `"user"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"assistant"` - The tool invocation context(s). + - `"system"` - - `"direct"` + - `"critic"` - - `"programmatic"` + - `"discriminator"` - - `defer_loading: optional boolean` + - `"developer"` - Whether this function is deferred and loaded via tool search. + - `"tool"` - - `description: optional string` + - `tools: array of BetaTool` - A description of the function. Used by the model to determine whether or not to call the function. + The additional tool definitions made available at this item. - - `output_schema: optional map[unknown]` + - `beta_function_tool: object { name, parameters, strict, 5 more }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + 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). - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "file_search"` - - The type of the file search tool. Always `file_search`. - - - `vector_store_ids: array of string` - - The IDs of the vector stores to search. - - - `filters: optional object { key, type, value } or object { filters, type }` - - A filter to apply. - - - `Comparison Filter: object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of unknown` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `union_member_3: array of unknown` - - - `Compound Filter: object { filters, type }` - - Combine multiple filters using `and` or `or`. - - - `filters: array of object { key, type, value } or unknown` - - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - - `Comparison Filter: object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of unknown` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `union_member_0: string` - - - `union_member_1: number` - - - `union_member_2: boolean` - - - `union_member_3: array of unknown` - - - `union_member_1: unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - - `max_num_results: optional number` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - Ranking options for search. - - - `hybrid_search: optional object { embedding_weight, text_weight }` - - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - - `embedding_weight: number` - - The weight of the embedding in the reciprocal ranking fusion. - - - `text_weight: number` - - The weight of the text in the reciprocal ranking fusion. - - - `ranker: optional "auto" or "default-2024-11-15"` - - The ranker to use for the file search. - - - `"auto"` - - - `"default-2024-11-15"` - - - `score_threshold: optional number` - - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `beta_computer_tool: object { type }` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "computer"` - - The type of the computer tool. Always `computer`. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `display_height: number` - - The height of the computer display. - - - `display_width: number` - - The width of the computer display. - - - `environment: "windows" or "mac" or "linux" or 2 more` - - The type of computer environment to control. - - - `"windows"` - - - `"mac"` - - - `"linux"` - - - `"ubuntu"` - - - `"browser"` - - - `type: "computer_use_preview"` - - The type of the computer use tool. Always `computer_use_preview`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `type: "web_search" or "web_search_2025_08_26"` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - - `"web_search"` - - - `"web_search_2025_08_26"` - - - `filters: optional object { allowed_domains }` - - Filters for the search. - - - `allowed_domains: optional array of string` - - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - - - `search_context_size: optional "low" or "medium" or "high"` - - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` - - Free text input for the city of the user, e.g. `San Francisco`. - - - `country: optional string` - - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - - `region: optional string` - - Free text input for the region of the user, e.g. `California`. - - - `timezone: optional string` - - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - - `type: optional "approximate"` - - The type of location approximation. Always `approximate`. - - - `"approximate"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - `server_label: string` + - `code_interpreter: object { container, type, allowed_callers }` - A label for this MCP server, used to identify it in tool calls. + A tool that runs Python code to help generate a response to a prompt. - - `type: "mcp"` + - `programmatic_tool_calling: object { type }` - The type of the MCP tool. Always `mcp`. + - `image_generation: object { type, action, background, 9 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A tool that generates images using the GPT image models. - The tool invocation context(s). + - `local_shell: object { type }` - - `"direct"` + A tool that allows the model to execute shell commands in a local environment. - - `"programmatic"` + - `beta_function_shell_tool: object { type, allowed_callers, environment }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + A tool that allows the model to execute shell commands. - List of allowed tool names or a filter object. + - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` - - `MCP allowed tools: array of string` + 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) - A string array of allowed tool names + - `beta_namespace_tool: object { description, name, tools, type }` - - `MCP tool filter: object { read_only, tool_names }` + Groups function/custom tools under a shared namespace. - A filter object to specify which tools are allowed. + - `beta_tool_search_tool: object { type, description, execution, parameters }` - - `read_only: optional boolean` + Hosted or BYOT tool search configuration for deferred tools. - 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. + - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` - - `tool_names: optional array of string` + 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). - List of allowed tool names. + - `beta_apply_patch_tool: object { type, allowed_callers }` - - `authorization: optional string` + Allows the assistant to create, delete, or update files using unified diffs. - 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. + - `type: "additional_tools"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The type of the item. Always `additional_tools`. - 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). + - `agent: optional object { agent_name }` - Currently supported `connector_id` values are: + The agent that produced this item. - - 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` + - `agent_name: string` - - `"connector_dropbox"` + The canonical name of the agent that produced this item. - - `"connector_gmail"` + - `beta_response_reasoning_item: object { id, summary, type, 4 more }` - - `"connector_googlecalendar"` + 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). - - `"connector_googledrive"` + - `id: string` - - `"connector_microsoftteams"` + The unique identifier of the reasoning content. - - `"connector_outlookcalendar"` + - `summary: array of object { text, type }` - - `"connector_outlookemail"` + Reasoning summary content. - - `"connector_sharepoint"` + - `text: string` - - `defer_loading: optional boolean` + A summary of the reasoning output from the model so far. - Whether this MCP tool is deferred and discovered via tool search. + - `type: "summary_text"` - - `headers: optional map[string]` + The type of the object. Always `summary_text`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "reasoning"` - - `require_approval: optional object { always, never } or "always" or "never"` + The type of the object. Always `reasoning`. - Specify which of the MCP server's tools require approval. + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - - `MCP tool approval filter: object { always, never }` + - `content: optional array of object { text, type }` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Reasoning text content. - - `always: optional object { read_only, tool_names }` + - `text: string` - A filter object to specify which tools are allowed. + The reasoning text from the model. - - `read_only: optional boolean` + - `type: "reasoning_text"` - 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. + The type of the reasoning text. Always `reasoning_text`. - - `tool_names: optional array of string` + - `encrypted_content: optional string` - List of allowed tool names. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `never: optional object { read_only, tool_names }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A filter object to specify which tools are allowed. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `read_only: optional boolean` + - `"in_progress"` - 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. + - `"completed"` - - `tool_names: optional array of string` + - `"incomplete"` - List of allowed tool names. + - `program: object { id, call_id, code, 3 more }` - - `MCP tool approval setting: "always" or "never"` + - `id: string` - 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. + The unique ID of the program item. - - `"always"` + - `call_id: string` - - `"never"` + The stable call ID of the program item. - - `server_description: optional string` + - `code: string` - Optional description of the MCP server, used to provide more context. + The JavaScript source executed by programmatic tool calling. - - `server_url: optional string` + - `fingerprint: string` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Opaque program replay fingerprint that must be round-tripped. - - `tunnel_id: optional string` + - `type: "program"` - 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. + The type of the item. Always `program`. - - `code_interpreter: object { container, type, allowed_callers }` + - `agent: optional object { agent_name }` - A tool that runs Python code to help generate a response to a prompt. + The agent that produced this item. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - - `union_member_0: string` + - `program_output: object { id, call_id, result, 3 more }` - The container ID. + - `id: string` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + The unique ID of the program output item. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `call_id: string` - - `type: "auto"` + The call ID of the program item. - Always `auto`. + - `result: string` - - `file_ids: optional array of string` + The result produced by the program item. - An optional list of uploaded files to make available to your code. + - `status: "completed" or "incomplete"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The terminal status of the program output item. - The memory limit for the code interpreter container. + - `"completed"` - - `"1g"` + - `"incomplete"` - - `"4g"` + - `type: "program_output"` - - `"16g"` + The type of the item. Always `program_output`. - - `"64g"` + - `agent: optional object { agent_name }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The agent that produced this item. - Network access policy for the container. + - `agent_name: string` - - `beta_container_network_policy_disabled: object { type }` + The canonical name of the agent that produced this item. - - `type: "disabled"` + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` - Disable outbound network access. Always `disabled`. + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `id: string` - - `allowed_domains: array of string` + The unique ID of the compaction item. - A list of allowed domains when type is `allowlist`. + - `encrypted_content: string` - - `type: "allowlist"` + The encrypted content that was produced by compaction. - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: "compaction"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The type of the item. Always `compaction`. - Optional domain-scoped secrets for allowlisted domains. + - `agent: optional object { agent_name }` - - `domain: string` + The agent that produced this item. - The domain associated with the secret. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the secret to inject for the domain. + - `created_by: optional string` - - `value: string` + The identifier of the actor that created the item. - The secret value to inject for the domain. + - `image_generation_call: object { id, result, status, 2 more }` - - `type: "code_interpreter"` + An image generation request made by the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the image generation call. - The tool invocation context(s). + - `result: string` - - `"direct"` + The generated image encoded in base64. - - `"programmatic"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `programmatic_tool_calling: object { type }` + The status of the image generation call. - - `image_generation: object { type, action, background, 9 more }` + - `"in_progress"` - A tool that generates images using the GPT image models. + - `"completed"` - - `type: "image_generation"` + - `"generating"` - The type of the image generation tool. Always `image_generation`. + - `"failed"` - - `action: optional "generate" or "edit" or "auto"` + - `type: "image_generation_call"` - Whether to generate a new image or edit an existing image. Default: `auto`. + The type of the image generation call. Always `image_generation_call`. - - `"generate"` + - `agent: optional object { agent_name }` - - `"edit"` + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `background: optional "transparent" or "opaque" or "auto"` + The canonical name of the agent that produced this item. - 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. + - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` - `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. + A tool call to run code. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `id: string` - - `"transparent"` + The unique ID of the code interpreter tool call. - - `"opaque"` + - `code: string` - - `"auto"` + The code to run, or null if not available. - - `input_fidelity: optional "high" or "low"` + - `container_id: string` - 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`. + The ID of the container used to run the code. - - `"high"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"low"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `input_image_mask: optional object { file_id, image_url }` + - `logs: object { logs, type }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The logs output from the code interpreter. - - `file_id: optional string` + - `logs: string` - File ID for the mask image. + The logs output from the code interpreter. - - `image_url: optional string` + - `type: "logs"` - Base64-encoded mask image. + The type of the output. Always `logs`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `image: object { type, url }` - The image generation model to use. Default: `gpt-image-1`. + The image output from the code interpreter. - - `"gpt-image-1"` + - `type: "image"` - - `"gpt-image-1-mini"` + The type of the output. Always `image`. - - `"gpt-image-2"` + - `url: string` - - `"gpt-image-2-2026-04-21"` + The URL of the image output from the code interpreter. - - `"gpt-image-1.5"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"chatgpt-image-latest"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `moderation: optional "auto" or "low"` + - `"in_progress"` - Moderation level for the generated image. Default: `auto`. + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"low"` + - `"interpreting"` - - `output_compression: optional number` + - `"failed"` - Compression level for the output image. Default: 100. + - `type: "code_interpreter_call"` - - `output_format: optional "png" or "webp" or "jpeg"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `agent: optional object { agent_name }` - - `"png"` + The agent that produced this item. - - `"webp"` + - `agent_name: string` - - `"jpeg"` + The canonical name of the agent that produced this item. - - `partial_images: optional number` + - `local_shell_call: object { id, action, call_id, 3 more }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A tool call to run a command on the local shell. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `id: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The unique ID of the local shell call. - - `"low"` + - `action: object { command, env, type, 3 more }` - - `"medium"` + Execute a shell command on the server. - - `"high"` + - `command: array of string` - - `"auto"` + The command to run. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `env: map[string]` - 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`. + Environment variables to set for the command. - - `"1024x1024"` + - `type: "exec"` - - `"1024x1536"` + The type of the local shell action. Always `exec`. - - `"1536x1024"` + - `timeout_ms: optional number` - - `"auto"` + Optional timeout in milliseconds for the command. - - `local_shell: object { type }` + - `user: optional string` - A tool that allows the model to execute shell commands in a local environment. + Optional user to run the command as. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `working_directory: optional string` - A tool that allows the model to execute shell commands. + Optional working directory to run the command in. - - `type: "shell"` + - `call_id: string` - The type of the shell tool. Always `shell`. + The unique ID of the local shell tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: "in_progress" or "completed" or "incomplete"` - The tool invocation context(s). + The status of the local shell call. - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"completed"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"incomplete"` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `type: "local_shell_call"` - - `type: "container_auto"` + The type of the local shell call. Always `local_shell_call`. - Automatically creates a container for this request + - `agent: optional object { agent_name }` - - `file_ids: optional array of string` + The agent that produced this item. - An optional list of uploaded files to make available to your code. + - `agent_name: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The canonical name of the agent that produced this item. - The memory limit for the container. + - `local_shell_call_output: object { id, output, type, 2 more }` - - `"1g"` + The output of a local shell tool call. - - `"4g"` + - `id: string` - - `"16g"` + The unique ID of the local shell tool call generated by the model. - - `"64g"` + - `output: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A JSON string of the output of the local shell tool call. - Network access policy for the container. + - `type: "local_shell_call_output"` - - `beta_container_network_policy_disabled: object { type }` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `agent: optional object { agent_name }` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The agent that produced this item. - An optional list of skills referenced by id or inline data. + - `agent_name: string` - - `beta_skill_reference: object { skill_id, type, version }` + The canonical name of the agent that produced this item. - - `skill_id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The ID of the referenced skill. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `type: "skill_reference"` + - `"in_progress"` - References a skill created with the /v1/skills endpoint. + - `"completed"` - - `version: optional string` + - `"incomplete"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - - `beta_inline_skill: object { description, name, source, type }` + A tool call that executes one or more shell commands in a managed environment. - - `description: string` + - `id: string` - The description of the skill. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `name: string` + - `action: object { commands, max_output_length, timeout_ms }` - The name of the skill. + The shell commands and limits that describe how to run the tool call. - - `source: object { data, media_type, type }` + - `commands: array of string` - Inline skill payload + - `max_output_length: number` - - `data: string` + Optional maximum number of characters to return from each command. - Base64-encoded skill zip bundle. + - `timeout_ms: number` - - `media_type: "application/zip"` + Optional timeout in milliseconds for the commands. - The media type of the inline skill payload. Must be `application/zip`. + - `call_id: string` - - `type: "base64"` + The unique ID of the shell tool call generated by the model. - The type of the inline skill source. Must be `base64`. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `type: "inline"` + Represents the use of a local environment to perform shell actions. - Defines an inline skill for this request. + - `beta_response_local_environment: object { type }` - - `beta_local_environment: object { type, skills }` + Represents the use of a local environment to perform shell actions. - `type: "local"` - Use a local computer environment. + The environment type. Always `local`. - - `skills: optional array of BetaLocalSkill` + - `beta_response_container_reference: object { container_id, type }` - An optional list of skills. + Represents a container created with /v1/containers. - - `description: string` + - `container_id: string` - The description of the skill. + - `type: "container_reference"` - - `name: string` + The environment type. Always `container_reference`. - The name of the skill. + - `status: "in_progress" or "completed" or "incomplete"` - - `path: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The path to the directory containing the skill. + - `"in_progress"` - - `beta_container_reference: object { container_id, type }` + - `"completed"` - - `container_id: string` + - `"incomplete"` - The ID of the referenced container. + - `type: "shell_call"` - - `type: "container_reference"` + The type of the item. Always `shell_call`. - References a container created with the /v1/containers endpoint + - `agent: optional object { agent_name }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The agent that produced this item. - 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) + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the custom tool, used to identify it in tool calls. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "custom"` + The execution context that produced this tool call. - The type of the custom tool. Always `custom`. + - `direct: object { type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `program: object { caller_id, type }` - The tool invocation context(s). + - `caller_id: string` - - `"direct"` + The call ID of the program item that produced this tool call. - - `"programmatic"` + - `type: "program"` - - `defer_loading: optional boolean` + - `created_by: optional string` - Whether this tool should be deferred and discovered via tool search. + The ID of the entity that created this tool call. - - `description: optional string` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - Optional description of the custom tool, used to provide more context. + The output of a shell tool call that was emitted. - - `format: optional object { type } or object { definition, syntax, type }` + - `id: string` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the shell call output. Populated when this item is returned via API. - - `text: object { type }` + - `call_id: string` - Unconstrained free-form text. + The unique ID of the shell tool call generated by the model. - - `grammar: object { definition, syntax, type }` + - `max_output_length: number` - A grammar defined by the user. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `definition: string` + - `output: array of object { outcome, stderr, stdout, created_by }` - The grammar definition. + An array of shell call output contents - - `syntax: "lark" or "regex"` + - `outcome: object { type } or object { exit_code, type }` - The syntax of the grammar definition. One of `lark` or `regex`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"lark"` + - `timeout: object { type }` - - `"regex"` + Indicates that the shell call exceeded its configured time limit. - - `type: "grammar"` + - `exit: object { exit_code, type }` - Grammar format. Always `grammar`. + Indicates that the shell commands finished and returned an exit code. - - `beta_namespace_tool: object { description, name, tools, type }` + - `exit_code: number` - Groups function/custom tools under a shared namespace. + Exit code from the shell process. - - `description: string` + - `type: "exit"` - A description of the namespace shown to the model. + The outcome type. Always `exit`. - - `name: string` + - `stderr: string` - The namespace name used in tool calls (for example, `crm`). + The standard error output that was captured. - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `stdout: string` - The function/custom tools available inside this namespace. + The standard output that was captured. - - `function: object { name, type, allowed_callers, 5 more }` + - `created_by: optional string` - - `name: string` + The identifier of the actor that created the item. - - `type: "function"` + - `status: "in_progress" or "completed" or "incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The tool invocation context(s). + - `"in_progress"` - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `defer_loading: optional boolean` + - `type: "shell_call_output"` - Whether this function should be deferred and discovered via tool search. + The type of the shell call output. Always `shell_call_output`. - - `description: optional string` + - `agent: optional object { agent_name }` - - `output_schema: optional map[unknown]` + The agent that produced this item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `agent_name: string` - - `parameters: optional unknown` + The canonical name of the agent that produced this item. - - `strict: optional boolean` + - `caller: optional object { type } or object { caller_id, type }` - 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. + The execution context that produced this tool call. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `direct: object { type }` - 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) + - `program: object { caller_id, type }` - - `name: string` + - `caller_id: string` - The name of the custom tool, used to identify it in tool calls. + The call ID of the program item that produced this tool call. - - `type: "custom"` + - `type: "program"` - The type of the custom tool. Always `custom`. + - `created_by: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The identifier of the actor that created the item. - The tool invocation context(s). + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `defer_loading: optional boolean` + A tool call that applies file diffs by creating, deleting, or updating files. - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Optional description of the custom tool, used to provide more context. + - `call_id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The unique ID of the apply patch tool call generated by the model. - The input format for the custom tool. Default is unconstrained text. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `type: "namespace"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The type of the tool. Always `namespace`. + - `create_file: object { diff, path, type }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + Instruction describing how to create a file via the apply_patch tool. - Hosted or BYOT tool search configuration for deferred tools. + - `diff: string` - - `type: "tool_search"` + Diff to apply. - The type of the tool. Always `tool_search`. + - `path: string` - - `description: optional string` + Path of the file to create. - Description shown to the model for a client-executed tool search tool. + - `type: "create_file"` - - `execution: optional "server" or "client"` + Create a new file with the provided diff. - Whether tool search is executed by the server or by the client. + - `delete_file: object { path, type }` - - `"server"` + Instruction describing how to delete a file via the apply_patch tool. - - `"client"` + - `path: string` - - `parameters: optional unknown` + Path of the file to delete. - Parameter schema for a client-executed tool search tool. + - `type: "delete_file"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + Delete the specified file. - 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). + - `update_file: object { diff, path, type }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Instruction describing how to update a file via the apply_patch tool. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `diff: string` - - `"web_search_preview"` + Diff to apply. - - `"web_search_preview_2025_03_11"` + - `path: string` - - `search_content_types: optional array of "text" or "image"` + Path of the file to update. - - `"text"` + - `type: "update_file"` - - `"image"` + Update an existing file with the provided diff. - - `search_context_size: optional "low" or "medium" or "high"` + - `status: "in_progress" or "completed"` - 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. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"completed"` - - `"high"` + - `type: "apply_patch_call"` - - `user_location: optional object { type, city, country, 2 more }` + The type of the item. Always `apply_patch_call`. - The user's location. + - `agent: optional object { agent_name }` - - `type: "approximate"` + The agent that produced this item. - The type of location approximation. Always `approximate`. + - `agent_name: string` - - `city: optional string` + The canonical name of the agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `caller: optional object { type } or object { caller_id, type }` - - `country: optional string` + The execution context that produced this tool call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `direct: object { type }` - - `region: optional string` + - `program: object { caller_id, type }` - Free text input for the region of the user, e.g. `California`. + - `caller_id: string` - - `timezone: optional string` + The call ID of the program item that produced this tool call. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "program"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `created_by: optional string` - Allows the assistant to create, delete, or update files using unified diffs. + The ID of the entity that created this tool call. - - `type: "apply_patch"` + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` - The type of the tool. Always `apply_patch`. + The output emitted by an apply patch tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"direct"` + - `call_id: string` - - `"programmatic"` + The unique ID of the apply patch tool call generated by the model. - - `type: "tool_search_output"` + - `status: "completed" or "failed"` - The item type. Always `tool_search_output`. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `id: optional string` + - `"completed"` - The unique ID of this tool search output. + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. - `agent: optional object { agent_name }` @@ -124258,280 +136311,319 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - The unique ID of the tool search call generated by the model. + The execution context that produced this tool call. - - `execution: optional "server" or "client"` + - `direct: object { type }` - Whether tool search was executed by the server or by the client. + - `program: object { caller_id, type }` - - `"server"` + - `caller_id: string` - - `"client"` + The call ID of the program item that produced this tool call. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "program"` - The status of the tool search output. + - `created_by: optional string` - - `"in_progress"` + The ID of the entity that created this tool call output. - - `"completed"` + - `output: optional string` - - `"incomplete"` + Optional textual output returned by the apply patch tool. -### Beta Response Usage + - `mcp_list_tools: object { id, server_label, tools, 3 more }` -- `beta_response_usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }` + A list of tools available on an MCP server. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `id: string` - - `input_tokens: number` + The unique ID of the list. - The number of input tokens. + - `server_label: string` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The label of the MCP server. - A detailed breakdown of the input tokens. + - `tools: array of object { input_schema, name, annotations, description }` - - `cache_write_tokens: number` + The tools available on the server. - The number of input tokens that were written to the cache. + - `input_schema: unknown` - - `cached_tokens: number` + The JSON schema describing the tool's input. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `name: string` - - `output_tokens: number` + The name of the tool. - The number of output tokens. + - `annotations: optional unknown` - - `output_tokens_details: object { reasoning_tokens }` + Additional annotations about the tool. - A detailed breakdown of the output tokens. + - `description: optional string` - - `reasoning_tokens: number` + The description of the tool. - The number of reasoning tokens. + - `type: "mcp_list_tools"` - - `total_tokens: number` + The type of the item. Always `mcp_list_tools`. - The total number of tokens used. + - `agent: optional object { agent_name }` -### Beta Response Web Search Call Completed Event + The agent that produced this item. -- `beta_response_web_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `agent_name: string` - Emitted when a web search call is completed. + The canonical name of the agent that produced this item. - - `item_id: string` + - `error: optional string` - Unique ID for the output item associated with the web search call. + Error message if the server could not list tools. - - `output_index: number` + - `mcp_approval_request: object { id, arguments, name, 3 more }` - The index of the output item that the web search call is associated with. + A request for human approval of a tool invocation. - - `sequence_number: number` + - `id: string` - The sequence number of the web search call being processed. + The unique ID of the approval request. - - `type: "response.web_search_call.completed"` + - `arguments: string` - The type of the event. Always `response.web_search_call.completed`. + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Web Search Call In Progress Event - -- `beta_response_web_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` - Emitted when a web search call is initiated. + A response to an MCP approval request. - - `item_id: string` + - `id: string` - Unique ID for the output item associated with the web search call. + The unique ID of the approval response - - `output_index: number` + - `approval_request_id: string` - The index of the output item that the web search call is associated with. + The ID of the approval request being answered. - - `sequence_number: number` + - `approve: boolean` - The sequence number of the web search call being processed. + Whether the request was approved. - - `type: "response.web_search_call.in_progress"` + - `type: "mcp_approval_response"` - The type of the event. Always `response.web_search_call.in_progress`. + The type of the item. Always `mcp_approval_response`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Web Search Call Searching Event + - `reason: optional string` -- `beta_response_web_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` + Optional reason for the decision. - Emitted when a web search call is executing. + - `mcp_call: object { id, arguments, name, 7 more }` - - `item_id: string` + An invocation of a tool on an MCP server. - Unique ID for the output item associated with the web search call. + - `id: string` - - `output_index: number` + The unique ID of the tool call. - The index of the output item that the web search call is associated with. + - `arguments: string` - - `sequence_number: number` + A JSON string of the arguments passed to the tool. - The sequence number of the web search call being processed. + - `name: string` - - `type: "response.web_search_call.searching"` + The name of the tool that was run. - The type of the event. Always `response.web_search_call.searching`. + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Responses Client Event + - `approval_request_id: optional string` -- `beta_responses_client_event: object { type, background, context_management, 30 more } or object { input, response_id, type }` + 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. - Client events accepted by the Responses WebSocket server. + - `error: optional string` - - `response.create: object { type, background, context_management, 30 more }` + The error from the tool call, if any. - Client event for creating a response over a persistent WebSocket connection. - This payload uses the same top-level fields as `POST /v1/responses`. + - `output: optional string` - Notes: + The output from the tool call. - - `stream` is implicit over WebSocket and should not be sent. - - `background` is not supported over WebSocket. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "response.create"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of the client event. Always `response.create`. + - `"in_progress"` - - `background: optional boolean` + - `"completed"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `"incomplete"` - - `context_management: optional array of object { type, compact_threshold }` + - `"calling"` - Context management configuration for this request. + - `"failed"` - - `type: string` + - `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` - The context management entry type. Currently only 'compaction' is supported. + A call to a custom tool created by the model. - - `compact_threshold: optional number` + - `id: string` - Token threshold at which compaction should be triggered for this entry. + The unique ID of the custom tool call item. - - `conversation: optional string or BetaResponseConversationParam` + - `status: "in_progress" or "completed" or "incomplete"` - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Conversation ID: string` + - `"in_progress"` - The unique ID of the conversation. + - `"completed"` - - `beta_response_conversation_param: object { id }` + - `"incomplete"` - The conversation that this response belongs to. + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + + The output of a custom tool call from your code, being sent back to the model. - `id: string` - The unique ID of the conversation. + The unique ID of the custom tool call output item. - - `include: optional array of BetaResponseIncludable` + - `status: "in_progress" or "completed" or "incomplete"` - Specify additional output data to include in the model response. Currently supported values are: + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `"in_progress"` - - `"file_search_call.results"` + - `"completed"` - - `"web_search_call.results"` + - `"incomplete"` - - `"web_search_call.action.sources"` + - `created_by: optional string` - - `"message.input_image.image_url"` + The identifier of the actor that created the item. - - `"computer_call_output.output.image_url"` + - `first_id: string` - - `"code_interpreter_call.outputs"` + The ID of the first item in the list. - - `"reasoning.encrypted_content"` + - `has_more: boolean` - - `"message.output_text.logprobs"` + Whether there are more items available. - - `input: optional string or BetaResponseInput` + - `last_id: string` - Text, image, or file inputs to the model, used to generate a response. + The ID of the last item in the list. - Learn more: + - `object: "list"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Image inputs](https://platform.openai.com/docs/guides/images) - - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - - [Function calling](https://platform.openai.com/docs/guides/function-calling) + The type of object returned, must be `list`. - - `Text input: string` +### Example - A text input to the model, equivalent to a text input with the - `user` role. +```cli +openai beta:responses:input-items list \ + --api-key 'My API Key' \ + --response-id response_id +``` - - `beta_response_input: array of BetaResponseInputItem` +#### Response - A list of one or many input items to the model, containing - different content types. +```json +{ + "data": [ + { + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } + } + ], + "role": "user", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "status": "in_progress" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `beta_easy_input_message: object { content, role, phase, type }` +## Domain Types - 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. +### Beta Response Item List - - `content: string or BetaResponseInputMessageContentList` +- `beta_responseItemList: object { data, first_id, has_more, 2 more }` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + A list of Response items. - - `Text input: string` + - `data: array of BetaResponseItem` - A text input to the model. + A list of items used to generate this response. - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `beta_response_input_message_item: object { id, content, role, 3 more }` + + - `id: string` + + The unique ID of the message input. + + - `content: array of BetaResponseInputContent` A list of one or many input items to the model, containing different content types. @@ -124634,56 +136726,6 @@ openai beta:responses compact \ The breakpoint mode. Always `explicit`. - - `role: "user" or "assistant" or "system" or "developer"` - - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"developer"` - - - `phase: optional "commentary"` - - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - - `"commentary"` - - - `type: optional "message"` - - The type of the message input. Always `message`. - - - `"message"` - - - `message: object { content, role, agent, 2 more }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. - - - `content: array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - `role: "user" or "system" or "developer"` The role of the message input. One of `user`, `system`, or `developer`. @@ -124694,6 +136736,10 @@ openai beta:responses compact \ - `"developer"` + - `type: "message"` + + The type of the message input. Always set to `message`. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -124713,12 +136759,6 @@ openai beta:responses compact \ - `"incomplete"` - - `type: optional "message"` - - The type of the message input. Always set to `message`. - - - `"message"` - - `beta_response_output_message: object { id, content, role, 4 more }` An output message from the model. @@ -124890,7 +136930,7 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary"` + - `phase: optional "commentary" or "final_answer"` Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend @@ -124898,6 +136938,8 @@ openai beta:responses compact \ - `"commentary"` + - `"final_answer"` + - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` The results of a file search tool call. See the @@ -125236,9 +137278,11 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `computer_call_output: object { call_id, output, type, 4 more }` + - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` - The output of a computer tool call. + - `id: string` + + The unique ID of the computer call tool output. - `call_id: string` @@ -125261,17 +137305,27 @@ openai beta:responses compact \ The URL of the screenshot image. - - `type: "computer_call_output"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The type of the computer tool call output. Always `computer_call_output`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `id: optional string` + - `"completed"` - The ID of the computer tool call output. + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. - `acknowledged_safety_checks: optional array of object { id, code, message }` - The safety checks reported by the API that have been acknowledged by the developer. + The safety checks reported by the API that have been acknowledged by the + developer. - `id: string` @@ -125293,15 +137347,9 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - - `"in_progress"` - - - `"completed"` + - `created_by: optional string` - - `"incomplete"` + The identifier of the actor that created the item. - `beta_response_function_web_search: object { id, action, status, 2 more }` @@ -125397,58 +137445,16 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `arguments: string` - - A JSON string of the arguments to pass to the function. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `name: string` - - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `id: optional string` + - `id: string` The unique ID of the function tool call. - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `direct: object { type }` - - - `program: object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - - `namespace: optional string` - - The namespace of the function to run. - - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -125459,27 +137465,34 @@ openai beta:responses compact \ - `"incomplete"` - - `function_call_output: object { call_id, output, type, 4 more }` + - `created_by: optional string` - The output of a function tool call. + The identifier of the actor that created the item. + + - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the function call tool output. - `call_id: string` The unique ID of the function tool call generated by the model. - - `output: string or BetaResponseFunctionCallOutputItemList` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Text, image, or file output of the function tool call. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `union_member_0: string` + - `string output: string` - A JSON string of the output of the function tool call. + A string of the output of the function call. - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - An array of content outputs (text, image, file) for the function tool call. + Text, image, or file output of the function call. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -125495,30 +137508,18 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` + - `beta_response_input_image: object { detail, type, file_id, 2 more }` - The breakpoint mode. Always `explicit`. + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `detail: "low" or "high" or "auto" or "original"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `type: "input_image"` The type of the input item. Always `input_image`. - - `detail: optional "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - `file_id: optional string` The ID of the file to be sent to the model. @@ -125531,11 +137532,7 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `beta_response_input_file: object { type, detail, file_data, 4 more }` A file input to the model. @@ -125547,15 +137544,9 @@ openai beta:responses compact \ The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"auto"` - - - `"low"` - - - `"high"` - - `file_data: optional string` - The base64-encoded data of the file to be sent to the model. + The content of the file to be sent to the model. - `file_id: optional string` @@ -125573,17 +137564,20 @@ openai beta:responses compact \ Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `mode: "explicit"` + - `status: "in_progress" or "completed" or "incomplete"` - The breakpoint mode. Always `explicit`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "function_call_output"` + - `"in_progress"` - The type of the function tool call output. Always `function_call_output`. + - `"completed"` - - `id: optional string` + - `"incomplete"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. - `agent: optional object { agent_name }` @@ -125609,68 +137603,112 @@ openai beta:responses compact \ The caller type. Always `program`. - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `"in_progress"` + - `created_by: optional string` - - `"completed"` + The identifier of the actor that created the item. - - `"incomplete"` + - `agent_message: object { id, author, content, 3 more }` - - `agent_message: object { author, content, recipient, 3 more }` + - `id: string` - A message routed between agents. + The unique ID of the agent message. - `author: string` The sending agent identity. - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - Plaintext, image, or encrypted content sent between agents. + Encrypted content sent between agents. - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` A text input to the model. + - `beta_response_output_text: object { annotations, text, type, logprobs }` + + A text output from the model. + + - `text: object { text, type }` + + A text content. + - `text: string` - The text input to the model. + - `type: "text"` - - `type: "input_text"` + - `summary_text: object { text, type }` - The type of the input item. Always `input_text`. + A summary text from the model. - - `prompt_cache_breakpoint: optional object { mode }` + - `text: string` - 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. + A summary of the reasoning output from the model so far. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + - `type: "summary_text"` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + The type of the object. Always `summary_text`. - - `type: "input_image"` + - `reasoning_text: object { text, type }` - The type of the input item. Always `input_image`. + Reasoning text from the model. - - `detail: optional "low" or "high" or "auto" or "original"` + - `text: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The reasoning text from the model. - - `file_id: optional string` + - `type: "reasoning_text"` - The ID of the file to be sent to the model. + The type of the reasoning text. Always `reasoning_text`. - - `image_url: optional string` + - `beta_response_output_refusal: object { refusal, type }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A refusal from the model. + + - `beta_response_input_image: object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: string` + + The URL of the screenshot image. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - `prompt_cache_breakpoint: optional object { mode }` Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `beta_response_input_file: object { type, detail, file_data, 4 more }` + + A file input to the model. + - `encrypted_content: object { encrypted_content, type }` Opaque encrypted content that Responses API decrypts inside trusted model execution. @@ -125689,11 +137727,7 @@ openai beta:responses compact \ - `type: "agent_message"` - The item type. Always `agent_message`. - - - `id: optional string` - - The unique ID of this agent message item. + The type of the item. Always `agent_message`. - `agent: optional object { agent_name }` @@ -125703,11 +137737,15 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` + - `multi_agent_call: object { id, action, arguments, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call item. - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The multi-agent action that was executed. + The multi-agent action to execute. - `"spawn_agent"` @@ -125723,7 +137761,7 @@ openai beta:responses compact \ - `arguments: string` - The action arguments as a JSON string. + The JSON string of arguments generated for the action. - `call_id: string` @@ -125731,11 +137769,7 @@ openai beta:responses compact \ - `type: "multi_agent_call"` - The item type. Always `multi_agent_call`. - - - `id: optional string` - - The unique ID of this multi-agent call. + The type of the multi-agent call. Always `multi_agent_call`. - `agent: optional object { agent_name }` @@ -125745,7 +137779,11 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + - `multi_agent_call_output: object { id, action, call_id, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call output item. - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` @@ -125767,95 +137805,71 @@ openai beta:responses compact \ The unique ID of the multi-agent call. - - `output: array of object { text, type, annotations }` + - `output: array of BetaResponseOutputText` Text output returned by the multi-agent action. - - `text: string` - - The text content. - - - `type: "output_text"` - - The content type. Always `output_text`. - - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` - - Citations associated with the text content. - - - `union_member_0: array of object { file_id, filename, index, type }` - - - `file_id: string` - - The ID of the file. - - - `filename: string` - - The filename of the file cited. - - - `index: number` - - The index of the file in the list of files. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `type: "file_citation"` + The annotations of the text output. - The citation type. Always `file_citation`. + - `text: string` - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + The text output from the model. - - `end_index: number` + - `type: "output_text"` - The index of the last character of the citation in the message. + The type of the output text. Always `output_text`. - - `start_index: number` + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - The index of the first character of the citation in the message. + - `type: "multi_agent_call_output"` - - `title: string` + The type of the multi-agent result. Always `multi_agent_call_output`. - The title of the cited resource. + - `agent: optional object { agent_name }` - - `type: "url_citation"` + The agent that produced this item. - The citation type. Always `url_citation`. + - `agent_name: string` - - `url: string` + The canonical name of the agent that produced this item. - The URL of the cited resource. + - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + - `id: string` - - `container_id: string` + The unique ID of the tool search call item. - The ID of the container. + - `arguments: unknown` - - `end_index: number` + Arguments used for the tool search call. - The index of the last character of the citation in the message. + - `call_id: string` - - `file_id: string` + The unique ID of the tool search call generated by the model. - The ID of the container file. + - `execution: "server" or "client"` - - `filename: string` + Whether tool search was executed by the server or by the client. - The filename of the container file cited. + - `"server"` - - `start_index: number` + - `"client"` - The index of the first character of the citation in the message. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "container_file_citation"` + The status of the tool search call item that was recorded. - The citation type. Always `container_file_citation`. + - `"in_progress"` - - `type: "multi_agent_call_output"` + - `"completed"` - The item type. Always `multi_agent_call_output`. + - `"incomplete"` - - `id: optional string` + - `type: "tool_search_call"` - The unique ID of this multi-agent call output. + The type of the item. Always `tool_search_call`. - `agent: optional object { agent_name }` @@ -125865,33 +137879,21 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `tool_search_call: object { arguments, type, id, 4 more }` - - - `arguments: unknown` - - The arguments supplied to the tool search call. - - - `type: "tool_search_call"` - - The item type. Always `tool_search_call`. - - - `id: optional string` - - The unique ID of this tool search call. + - `created_by: optional string` - - `agent: optional object { agent_name }` + The identifier of the actor that created the item. - The agent that produced this item. + - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the tool search output item. - - `call_id: optional string` + - `call_id: string` The unique ID of the tool search call generated by the model. - - `execution: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -125899,9 +137901,9 @@ openai beta:responses compact \ - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -125909,11 +137911,9 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` - - `tools: array of BetaTool` - The loaded tool definitions returned by the tool search output. + The loaded tool definitions returned by tool search. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -126008,7 +138008,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -126018,7 +138018,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `Compound Filter: object { filters, type }` @@ -126065,7 +138069,7 @@ openai beta:responses compact \ - `"nin"` - - `value: string or number or boolean or array of unknown` + - `value: string or number or boolean or array of string or number` The value to compare against the attribute key; supports string, number, or boolean types. @@ -126075,7 +138079,11 @@ openai beta:responses compact \ - `union_member_2: boolean` - - `union_member_3: array of unknown` + - `union_member_3: array of string or number` + + - `union_member_0: string` + + - `union_member_1: number` - `union_member_1: unknown` @@ -126947,11 +138955,7 @@ openai beta:responses compact \ - `type: "tool_search_output"` - The item type. Always `tool_search_output`. - - - `id: optional string` - - The unique ID of this tool search output. + The type of the item. Always `tool_search_output`. - `agent: optional object { agent_name }` @@ -126961,37 +138965,39 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` - The unique ID of the tool search call generated by the model. + The identifier of the actor that created the item. - - `execution: optional "server" or "client"` + - `additional_tools: object { id, role, tools, 2 more }` - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the additional tools item. - - `"client"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + The role that provided the additional tools. - The status of the tool search output. + - `"unknown"` - - `"in_progress"` + - `"user"` - - `"completed"` + - `"assistant"` - - `"incomplete"` + - `"system"` - - `additional_tools: object { role, tools, type, 2 more }` + - `"critic"` - - `role: "developer"` + - `"discriminator"` - The role that provided the additional tools. Only `developer` is supported. + - `"developer"` + + - `"tool"` - `tools: array of BetaTool` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `beta_function_tool: object { name, parameters, strict, 5 more }` @@ -127059,11 +139065,7 @@ openai beta:responses compact \ - `type: "additional_tools"` - The item type. Always `additional_tools`. - - - `id: optional string` - - The unique ID of this additional tools item. + The type of the item. Always `additional_tools`. - `agent: optional object { agent_name }` @@ -127136,22 +139138,86 @@ openai beta:responses compact \ - `"incomplete"` - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `program: object { id, call_id, code, 3 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `program_output: object { id, call_id, result, 3 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `id: string` + + The unique ID of the compaction item. + - `encrypted_content: string` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: "compaction"` The type of the item. Always `compaction`. - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -127160,6 +139226,10 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `image_generation_call: object { id, result, status, 2 more }` An image generation request made by the model. @@ -127363,9 +139433,13 @@ openai beta:responses compact \ - `"incomplete"` - - `shell_call: object { action, call_id, type, 5 more }` + - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` - A tool representing a request to execute one or more shell commands. + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. - `action: object { commands, max_output_length, timeout_ms }` @@ -127373,27 +139447,53 @@ openai beta:responses compact \ - `commands: array of string` - Ordered shell commands for the execution environment to run. - - - `max_output_length: optional number` + - `max_output_length: number` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - - `timeout_ms: optional number` + - `timeout_ms: number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `type: "shell_call"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The type of the item. Always `shell_call`. + Represents the use of a local environment to perform shell actions. - - `id: optional string` + - `beta_response_local_environment: object { type }` - The unique ID of the shell tool call. Populated when this item is returned via API. + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `beta_response_container_reference: object { container_id, type }` + + Represents a container created with /v1/containers. + + - `container_id: string` + + - `type: "container_reference"` + + The environment type. Always `container_reference`. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. - `agent: optional object { agent_name }` @@ -127417,41 +139517,33 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `beta_local_environment: object { type, skills }` - - - `beta_container_reference: object { container_id, type }` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: optional string` - - `"in_progress"` + The ID of the entity that created this tool call. - - `"completed"` + - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` - - `"incomplete"` + The output of a shell tool call that was emitted. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `id: string` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `max_output_length: number` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents - `outcome: object { type } or object { exit_code, type }` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `timeout: object { type }` @@ -127463,7 +139555,7 @@ openai beta:responses compact \ - `exit_code: number` - The exit code returned by the shell process. + Exit code from the shell process. - `type: "exit"` @@ -127471,19 +139563,29 @@ openai beta:responses compact \ - `stderr: string` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: string` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: "shell_call_output"` + - `created_by: optional string` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `id: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. - `agent: optional object { agent_name }` @@ -127507,25 +139609,17 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. - - - `max_output_length: optional number` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` @@ -127533,51 +139627,51 @@ openai beta:responses compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `create_file: object { diff, path, type }` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: string` - Unified diff content to apply when creating the file. + Diff to apply. - `path: string` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: "create_file"` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `delete_file: object { path, type }` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: string` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: "delete_file"` - The operation type. Always `delete_file`. + Delete the specified file. - `update_file: object { diff, path, type }` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: string` - Unified diff content to apply to the existing file. + Diff to apply. - `path: string` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: "update_file"` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `status: "in_progress" or "completed"` @@ -127589,11 +139683,7 @@ openai beta:responses compact \ - `type: "apply_patch_call"` - The type of the item. Always `apply_patch_call`. - - - `id: optional string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of the item. Always `apply_patch_call`. - `agent: optional object { agent_name }` @@ -127617,11 +139707,17 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. + - `created_by: optional string` - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + The ID of the entity that created this tool call. - The streamed output emitted by an apply patch tool call. + - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + + The output emitted by an apply patch tool call. + + - `id: string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id: string` @@ -127639,10 +139735,6 @@ openai beta:responses compact \ The type of the item. Always `apply_patch_call_output`. - - `id: optional string` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -127665,11 +139757,13 @@ openai beta:responses compact \ - `type: "program"` - The caller type. Always `program`. + - `created_by: optional string` + + The ID of the entity that created this tool call output. - `output: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. - `mcp_list_tools: object { id, server_label, tools, 3 more }` @@ -127751,10 +139845,14 @@ openai beta:responses compact \ The canonical name of the agent that produced this item. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` A response to an MCP approval request. + - `id: string` + + The unique ID of the approval response + - `approval_request_id: string` The ID of the approval request being answered. @@ -127767,10 +139865,6 @@ openai beta:responses compact \ The type of the item. Always `mcp_approval_response`. - - `id: optional string` - - The unique ID of the approval response - - `agent: optional object { agent_name }` The agent that produced this item. @@ -127842,8012 +139936,8042 @@ openai beta:responses compact \ - `"failed"` - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` - - The output of a custom tool call from your code, being sent back to the model. - - - `call_id: string` - - The call ID, used to map this custom tool call output to a custom tool call. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - The output from the custom tool call generated by your code. - Can be a string or an list of output content. - - - `string output: string` - - A string of the output of the custom tool call. - - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - Text, image, or file output of the custom tool call. - - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: "low" or "high" or "auto" or "original"` + - `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + A call to a custom tool created by the model. - - `type: "input_image"` + - `id: string` - The type of the input item. Always `input_image`. + The unique ID of the custom tool call item. - - `file_id: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The ID of the file to be sent to the model. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `image_url: optional string` + - `"in_progress"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"completed"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"incomplete"` - 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. + - `created_by: optional string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The identifier of the actor that created the item. - A file input to the model. + - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` - - `type: "input_file"` + The output of a custom tool call from your code, being sent back to the model. - The type of the input item. Always `input_file`. + - `id: string` - - `detail: optional "auto" or "low" or "high"` + The unique ID of the custom tool call output item. - 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`. + - `status: "in_progress" or "completed" or "incomplete"` - - `file_data: optional string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The content of the file to be sent to the model. + - `"in_progress"` - - `file_id: optional string` + - `"completed"` - The ID of the file to be sent to the model. + - `"incomplete"` - - `file_url: optional string` + - `created_by: optional string` - The URL of the file to be sent to the model. + The identifier of the actor that created the item. - - `filename: optional string` + - `first_id: string` - The name of the file to be sent to the model. + The ID of the first item in the list. - - `prompt_cache_breakpoint: optional object { mode }` + - `has_more: boolean` - 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. + Whether there are more items available. - - `type: "custom_tool_call_output"` + - `last_id: string` - The type of the custom tool call output. Always `custom_tool_call_output`. + The ID of the last item in the list. - - `id: optional string` + - `object: "list"` - The unique ID of the custom tool call output in the OpenAI platform. + The type of object returned, must be `list`. - - `agent: optional object { agent_name }` +# Input Tokens - The agent that produced this item. +## Get input token counts - - `agent_name: string` +`$ openai beta:responses:input-tokens count` - The canonical name of the agent that produced this item. +**post** `/responses/input_tokens?beta=true` - - `caller: optional object { type } or object { caller_id, type }` +Returns input token counts of the request. - The execution context that produced this tool call. +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - - `direct: object { type }` +### Parameters - - `program: object { caller_id, type }` +- `--conversation: optional string or BetaResponseConversationParam` - - `caller_id: string` + Body param: The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - The call ID of the program item that produced this tool call. +- `--input: optional string or array of BetaResponseInputItem` - - `type: "program"` + Body param: Text, image, or file inputs to the model, used to generate a response - The caller type. Always `program`. +- `--instructions: optional string` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + Body param: 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. - A call to a custom tool created by the model. +- `--model: optional string` - - `call_id: string` + Body param: Model ID used to generate the response, like `gpt-4o` 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. - An identifier used to map this custom tool call to a tool call output. +- `--parallel-tool-calls: optional boolean` - - `input: string` + Body param: Whether to allow the model to run tool calls in parallel. - The input for the custom tool call generated by the model. +- `--personality: optional string or "friendly" or "pragmatic"` - - `name: string` + Body param: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - The name of the custom tool being called. +- `--previous-response-id: optional string` - - `type: "custom_tool_call"` + Body param: 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`. - The type of the custom tool call. Always `custom_tool_call`. +- `--reasoning: optional object { context, effort, generate_summary, 2 more }` - - `id: optional string` + Body param: **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The unique ID of the custom tool call in the OpenAI platform. +- `--text: optional object { format, verbosity }` - - `agent: optional object { agent_name }` + Body param: Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The agent that produced this item. + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) - - `agent_name: string` +- `--tool-choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The canonical name of the agent that produced this item. + Body param: Controls which tool the model should use, if any. - - `caller: optional object { type } or object { caller_id, type }` +- `--tool: optional array of BetaTool` - The execution context that produced this tool call. + Body param: An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. - - `direct: object { type }` +- `--truncation: optional "auto" or "disabled"` - - `program: object { caller_id, type }` + Body param: The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error. - - `caller_id: string` +- `--beta: optional array of "responses_multi_agent=v1"` - The call ID of the program item that produced this tool call. + Header param: Optional beta features to enable for this request. - - `type: "program"` +### Returns - - `namespace: optional string` +- `BetaResponseInputTokenCountResponse: object { input_tokens, object }` - The namespace of the custom tool being called. + - `input_tokens: number` - - `compaction_trigger: object { type, agent }` + - `object: "response.input_tokens"` - Compacts the current context. Must be the final input item. +### Example - - `type: "compaction_trigger"` +```cli +openai beta:responses:input-tokens count \ + --api-key 'My API Key' +``` - The type of the item. Always `compaction_trigger`. +#### Response - - `agent: optional object { agent_name }` +```json +{ + "input_tokens": 123, + "object": "response.input_tokens" +} +``` - The agent that produced this item. +# ChatKit - - `agent_name: string` +## Domain Types - The canonical name of the agent that produced this item. +### ChatKit Workflow - - `item_reference: object { id, agent, type }` +- `chatkit_workflow: object { id, state_variables, tracing, version }` - An internal identifier for an item to reference. + Workflow metadata and state returned for the session. - `id: string` - The ID of the item to reference. + Identifier of the workflow backing the session. - - `agent: optional object { agent_name }` + - `state_variables: map[string or boolean or number]` - The agent that produced this item. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `agent_name: string` + - `union_member_0: string` - The canonical name of the agent that produced this item. + - `union_member_1: boolean` - - `type: optional "item_reference"` + - `union_member_2: number` - The type of item to reference. Always `item_reference`. + - `tracing: object { enabled }` - - `"item_reference"` + Tracing settings applied to the workflow. - - `program: object { id, call_id, code, 3 more }` + - `enabled: boolean` - - `id: string` + Indicates whether tracing is enabled. - The unique ID of this program item. + - `version: string` - - `call_id: string` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - The stable call ID of the program item. +# Sessions - - `code: string` +## Cancel chat session - The JavaScript source executed by programmatic tool calling. +`$ openai beta:chatkit:sessions cancel` - - `fingerprint: string` +**post** `/chatkit/sessions/{session_id}/cancel` - Opaque program replay fingerprint that must be round-tripped. +Cancel an active ChatKit session and return its most recent metadata. - - `type: "program"` +Cancelling prevents new requests from using the issued client secret. - The item type. Always `program`. +### Parameters - - `agent: optional object { agent_name }` +- `--session-id: string` - The agent that produced this item. + Unique identifier for the ChatKit session to cancel. - - `agent_name: string` +### Returns - The canonical name of the agent that produced this item. +- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }` - - `program_output: object { id, call_id, result, 3 more }` + Represents a ChatKit session and its resolved configuration. - `id: string` - The unique ID of this program output item. - - - `call_id: string` - - The call ID of the program item. - - - `result: string` - - The result produced by the program item. - - - `status: "completed" or "incomplete"` - - The terminal status of the program output. - - - `"completed"` - - - `"incomplete"` - - - `type: "program_output"` - - The item type. Always `program_output`. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `instructions: optional string` - - A system (or developer) message inserted into the model's context. - - When using 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. - - - `max_output_tokens: optional number` - - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). - - - `max_tool_calls: optional number` - - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - - `metadata: optional map[string]` - - 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. - - - `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) - to browse and compare available models. - - - `"gpt-5.6-sol"` - - - `"gpt-5.6-terra"` - - - `"gpt-5.6-luna"` - - - `"gpt-5.4"` + Identifier for the ChatKit session. - - `"gpt-5.4-mini"` + - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }` - - `"gpt-5.4-nano"` + Resolved ChatKit feature configuration for the session. - - `"gpt-5.4-mini-2026-03-17"` + - `automatic_thread_titling: object { enabled }` - - `"gpt-5.4-nano-2026-03-17"` + Automatic thread titling preferences. - - `"gpt-5.3-chat-latest"` + - `enabled: boolean` - - `"gpt-5.2"` + Whether automatic thread titling is enabled. - - `"gpt-5.2-2025-12-11"` + - `file_upload: object { enabled, max_file_size, max_files }` - - `"gpt-5.2-chat-latest"` + Upload settings for the session. - - `"gpt-5.2-pro"` + - `enabled: boolean` - - `"gpt-5.2-pro-2025-12-11"` + Indicates if uploads are enabled for the session. - - `"gpt-5.1"` + - `max_file_size: number` - - `"gpt-5.1-2025-11-13"` + Maximum upload size in megabytes. - - `"gpt-5.1-codex"` + - `max_files: number` - - `"gpt-5.1-mini"` + Maximum number of uploads allowed during the session. - - `"gpt-5.1-chat-latest"` + - `history: object { enabled, recent_threads }` - - `"gpt-5"` + History retention configuration. - - `"gpt-5-mini"` + - `enabled: boolean` - - `"gpt-5-nano"` + Indicates if chat history is persisted for the session. - - `"gpt-5-2025-08-07"` + - `recent_threads: number` - - `"gpt-5-mini-2025-08-07"` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `"gpt-5-nano-2025-08-07"` + - `client_secret: string` - - `"gpt-5-chat-latest"` + Ephemeral client secret that authenticates session requests. - - `"gpt-4.1"` + - `expires_at: number` - - `"gpt-4.1-mini"` + Unix timestamp (in seconds) for when the session expires. - - `"gpt-4.1-nano"` + - `max_requests_per_1_minute: number` - - `"gpt-4.1-2025-04-14"` + Convenience copy of the per-minute request limit. - - `"gpt-4.1-mini-2025-04-14"` + - `object: "chatkit.session"` - - `"gpt-4.1-nano-2025-04-14"` + Type discriminator that is always `chatkit.session`. - - `"o4-mini"` + - `rate_limits: object { max_requests_per_1_minute }` - - `"o4-mini-2025-04-16"` + Resolved rate limit values. - - `"o3"` + - `max_requests_per_1_minute: number` - - `"o3-2025-04-16"` + Maximum allowed requests per one-minute window. - - `"o3-mini"` + - `status: "active" or "expired" or "cancelled"` - - `"o3-mini-2025-01-31"` + Current lifecycle state of the session. - - `"o1"` + - `"active"` - - `"o1-2024-12-17"` + - `"expired"` - - `"o1-preview"` + - `"cancelled"` - - `"o1-preview-2024-09-12"` + - `user: string` - - `"o1-mini"` + User identifier associated with the session. - - `"o1-mini-2024-09-12"` + - `workflow: object { id, state_variables, tracing, version }` - - `"gpt-4o"` + Workflow metadata for the session. - - `"gpt-4o-2024-11-20"` + - `id: string` - - `"gpt-4o-2024-08-06"` + Identifier of the workflow backing the session. - - `"gpt-4o-2024-05-13"` + - `state_variables: map[string or boolean or number]` - - `"gpt-4o-audio-preview"` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `"gpt-4o-audio-preview-2024-10-01"` + - `union_member_0: string` - - `"gpt-4o-audio-preview-2024-12-17"` + - `union_member_1: boolean` - - `"gpt-4o-audio-preview-2025-06-03"` + - `union_member_2: number` - - `"gpt-4o-mini-audio-preview"` + - `tracing: object { enabled }` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + Tracing settings applied to the workflow. - - `"gpt-4o-search-preview"` + - `enabled: boolean` - - `"gpt-4o-mini-search-preview"` + Indicates whether tracing is enabled. - - `"gpt-4o-search-preview-2025-03-11"` + - `version: string` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"chatgpt-4o-latest"` +### Example - - `"codex-mini-latest"` +```cli +openai beta:chatkit:sessions cancel \ + --api-key 'My API Key' \ + --session-id cksess_123 +``` - - `"gpt-4o-mini"` +#### Response - - `"gpt-4o-mini-2024-07-18"` +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - - `"gpt-4-turbo"` +## Create ChatKit session - - `"gpt-4-turbo-2024-04-09"` +`$ openai beta:chatkit:sessions create` - - `"gpt-4-0125-preview"` +**post** `/chatkit/sessions` - - `"gpt-4-turbo-preview"` +Create a ChatKit session. - - `"gpt-4-1106-preview"` +### Parameters - - `"gpt-4-vision-preview"` +- `--user: string` - - `"gpt-4"` + A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - - `"gpt-4-0314"` +- `--workflow: object { id, state_variables, tracing, version }` - - `"gpt-4-0613"` + Workflow that powers the session. - - `"gpt-4-32k"` +- `--chatkit-configuration: optional object { automatic_thread_titling, file_upload, history }` - - `"gpt-4-32k-0314"` + Optional overrides for ChatKit runtime configuration features - - `"gpt-4-32k-0613"` +- `--expires-after: optional object { anchor, seconds }` - - `"gpt-3.5-turbo"` + Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. - - `"gpt-3.5-turbo-16k"` +- `--rate-limits: optional object { max_requests_per_1_minute }` - - `"gpt-3.5-turbo-0301"` + Optional override for per-minute request limits. When omitted, defaults to 10. - - `"gpt-3.5-turbo-0613"` +### Returns - - `"gpt-3.5-turbo-1106"` +- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }` - - `"gpt-3.5-turbo-0125"` + Represents a ChatKit session and its resolved configuration. - - `"gpt-3.5-turbo-16k-0613"` + - `id: string` - - `"o1-pro"` + Identifier for the ChatKit session. - - `"o1-pro-2025-03-19"` + - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }` - - `"o3-pro"` + Resolved ChatKit feature configuration for the session. - - `"o3-pro-2025-06-10"` + - `automatic_thread_titling: object { enabled }` - - `"o3-deep-research"` + Automatic thread titling preferences. - - `"o3-deep-research-2025-06-26"` + - `enabled: boolean` - - `"o4-mini-deep-research"` + Whether automatic thread titling is enabled. - - `"o4-mini-deep-research-2025-06-26"` + - `file_upload: object { enabled, max_file_size, max_files }` - - `"computer-use-preview"` + Upload settings for the session. - - `"computer-use-preview-2025-03-11"` + - `enabled: boolean` - - `"gpt-5-codex"` + Indicates if uploads are enabled for the session. - - `"gpt-5-pro"` + - `max_file_size: number` - - `"gpt-5-pro-2025-10-06"` + Maximum upload size in megabytes. - - `"gpt-5.1-codex-max"` + - `max_files: number` - - `moderation: optional object { model, policy }` + Maximum number of uploads allowed during the session. - Configuration for running moderation on the input and output of this response. + - `history: object { enabled, recent_threads }` - - `model: string` + History retention configuration. - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `enabled: boolean` - - `policy: optional object { input, output }` + Indicates if chat history is persisted for the session. - The policy to apply to moderated response input and output. + - `recent_threads: number` - - `input: optional object { mode }` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - The moderation policy for the response input. + - `client_secret: string` - - `mode: "score" or "block"` + Ephemeral client secret that authenticates session requests. - - `"score"` + - `expires_at: number` - - `"block"` + Unix timestamp (in seconds) for when the session expires. - - `output: optional object { mode }` + - `max_requests_per_1_minute: number` - The moderation policy for the response output. + Convenience copy of the per-minute request limit. - - `mode: "score" or "block"` + - `object: "chatkit.session"` - - `"score"` + Type discriminator that is always `chatkit.session`. - - `"block"` + - `rate_limits: object { max_requests_per_1_minute }` - - `multi_agent: optional object { enabled, max_concurrent_subagents }` + Resolved rate limit values. - Configuration for server-hosted multi-agent execution. + - `max_requests_per_1_minute: number` - - `enabled: boolean` + Maximum allowed requests per one-minute window. - Whether to enable server-hosted multi-agent execution for this response. + - `status: "active" or "expired" or "cancelled"` - - `max_concurrent_subagents: optional number` + Current lifecycle state of the session. - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + - `"active"` - - `parallel_tool_calls: optional boolean` + - `"expired"` - Whether to allow the model to run tool calls in parallel. + - `"cancelled"` - - `previous_response_id: optional string` + - `user: string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + User identifier associated with the session. - - `prompt: optional object { id, variables, version }` + - `workflow: object { id, state_variables, tracing, version }` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Workflow metadata for the session. - `id: string` - The unique identifier of the prompt template to use. + Identifier of the workflow backing the session. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `state_variables: map[string or boolean or number]` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - `union_member_0: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `beta_response_input_image: object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `beta_response_input_file: object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `version: optional string` - - Optional version of the prompt template. - - - `prompt_cache_key: optional string` - - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). - - - `prompt_cache_options: optional object { mode, ttl }` - - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://platform.openai.com/docs/guides/prompt-caching) for current details. - - - `mode: optional "implicit" or "explicit"` - - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - - - `"implicit"` - - - `"explicit"` - - - `ttl: optional "30m"` - - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - - - `"30m"` - - - `prompt_cache_retention: optional "in_memory" or "24h"` - - Deprecated. Use `prompt_cache_options.ttl` instead. - - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - - `"in_memory"` - - - `"24h"` - - - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - **gpt-5 and o-series models only** - - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - - `context: optional "auto" or "current_turn" or "all_turns"` - - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. - - - `"auto"` - - - `"current_turn"` - - - `"all_turns"` - - - `effort: optional "none" or "minimal" or "low" or 4 more` - - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. - - - `"none"` - - - `"minimal"` - - - `"low"` - - - `"medium"` - - - `"high"` + - `union_member_1: boolean` - - `"xhigh"` + - `union_member_2: number` - - `"max"` + - `tracing: object { enabled }` - - `generate_summary: optional "auto" or "concise" or "detailed"` + Tracing settings applied to the workflow. - **Deprecated:** use `summary` instead. + - `enabled: boolean` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + Indicates whether tracing is enabled. - - `"auto"` + - `version: string` - - `"concise"` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"detailed"` +### Example - - `mode: optional string or "standard" or "pro"` +```cli +openai beta:chatkit:sessions create \ + --api-key 'My API Key' \ + --user x \ + --workflow '{id: id}' +``` - Controls the reasoning execution mode for the request. +#### Response - When returned on a response, this is the effective execution mode. +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - - `"standard"` +# Threads - - `"pro"` +## List ChatKit thread items - - `summary: optional "auto" or "concise" or "detailed"` +`$ openai beta:chatkit:threads list-items` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. +**get** `/chatkit/threads/{thread_id}/items` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. +List items that belong to a ChatKit thread. - - `"auto"` +### Parameters - - `"concise"` +- `--thread-id: string` - - `"detailed"` + Identifier of the ChatKit thread whose items are requested. - - `safety_identifier: optional string` +- `--after: optional string` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + List items created after this thread item ID. Defaults to null for the first page. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` +- `--before: optional string` - Specifies the processing type used for serving the request. + List items created before this thread item ID. Defaults to null for the newest results. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. +- `--limit: optional number` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + Maximum number of thread items to return. Defaults to 20. - - `"auto"` +- `--order: optional "asc" or "desc"` - - `"default"` + Sort order for results by creation time. Defaults to `desc`. - - `"flex"` +### Returns - - `"scale"` +- `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }` - - `"priority"` + A paginated list of thread items rendered for the ChatKit API. - - `store: optional boolean` + - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - Whether to store the generated model response for later retrieval via - API. + A list of items - - `stream: optional boolean` + - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) - for more information. + User-authored messages within a thread. - - `stream_options: optional object { include_obfuscation }` + - `id: string` - Options for streaming responses. Only set this when you set `stream: true`. + Identifier of the thread item. - - `include_obfuscation: optional boolean` + - `attachments: array of ChatKitAttachment` - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. + Attachments associated with the user message. Defaults to an empty list. - - `temperature: optional number` + - `id: string` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + Identifier for the attachment. - - `text: optional object { format, verbosity }` + - `mime_type: string` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + MIME type of the attachment. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `name: string` - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + Original display name for the attachment. - An object specifying the format that the model must output. + - `preview_url: string` - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + Preview URL for rendering the attachment inline. - The default format is `{ "type": "text" }` with no additional options. + - `type: "image" or "file"` - **Not recommended for gpt-4o and newer models:** + Attachment discriminator. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `"image"` - - `text: object { type }` + - `"file"` - Default response format. Used to generate text responses. + - `content: array of object { text, type } or object { text, type }` - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + Ordered content elements supplied by the user. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `input_text: object { text, type }` - - `name: string` + Text block that a user contributed to the thread. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `text: string` - - `schema: map[unknown]` + Plain-text content supplied by the user. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: "input_text"` - - `type: "json_schema"` + Type discriminator that is always `input_text`. - The type of response format being defined. Always `json_schema`. + - `quoted_text: object { text, type }` - - `description: optional string` + Quoted snippet that the user referenced in their message. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `text: string` - - `strict: optional boolean` + Quoted text content. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + - `type: "quoted_text"` - - `json_object: object { type }` + Type discriminator that is always `quoted_text`. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `created_at: number` - - `verbosity: optional "low" or "medium" or "high"` + Unix timestamp (in seconds) for when the item was created. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `inference_options: object { model, tool_choice }` - - `"low"` + Inference overrides applied to the message. Defaults to null when unset. - - `"medium"` + - `model: string` - - `"high"` + Model name that generated the response. Defaults to null when using the session default. - - `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `tool_choice: object { id }` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `beta_tool_choice_options: "none" or "auto" or "required"` + - `id: string` - Controls which (if any) tool is called by the model. + Identifier of the requested tool. - `none` means the model will not call any tool and instead generates a message. + - `object: "chatkit.thread_item"` - `auto` means the model can pick between generating a message or calling one or - more tools. + Type discriminator that is always `chatkit.thread_item`. - `required` means the model must call one or more tools. + - `thread_id: string` - - `"none"` + Identifier of the parent thread. - - `"auto"` + - `type: "chatkit.user_message"` - - `"required"` + - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` - - `beta_tool_choice_allowed: object { mode, tools, type }` + Assistant-authored message within a thread. - Constrains the tools available to the model to a pre-defined set. + - `id: string` - - `mode: "auto" or "required"` + Identifier of the thread item. - Constrains the tools available to the model to a pre-defined set. + - `content: array of ChatKitResponseOutputText` - `auto` allows the model to pick from among the allowed tools and generate a - message. + Ordered assistant response segments. - `required` requires the model to call one or more of the allowed tools. + - `annotations: array of object { source, type } or object { source, type }` - - `"auto"` + Ordered list of annotations attached to the response text. - - `"required"` + - `file: object { source, type }` - - `tools: array of map[unknown]` + Annotation that references an uploaded file. - A list of tool definitions that the model should be allowed to call. + - `source: object { filename, type }` - For the Responses API, the list of tool definitions might look like: + File attachment referenced by the annotation. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `filename: string` - - `type: "allowed_tools"` + Filename referenced by the annotation. - Allowed tool configuration type. Always `allowed_tools`. + - `type: "file"` - - `beta_tool_choice_types: object { type }` + Type discriminator that is always `file`. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `type: "file"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + Type discriminator that is always `file` for this annotation. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `url: object { source, type }` - Allowed values are: + Annotation that references a URL. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `source: object { type, url }` - - `"file_search"` + URL referenced by the annotation. - - `"web_search_preview"` + - `type: "url"` - - `"computer"` + Type discriminator that is always `url`. - - `"computer_use_preview"` + - `url: string` - - `"computer_use"` + URL referenced by the annotation. - - `"web_search_preview_2025_03_11"` + - `type: "url"` - - `"image_generation"` + Type discriminator that is always `url` for this annotation. - - `"code_interpreter"` + - `text: string` - - `beta_tool_choice_function: object { name, type }` + Assistant generated text. - Use this option to force the model to call a specific function. + - `type: "output_text"` - - `name: string` + Type discriminator that is always `output_text`. - The name of the function to call. + - `created_at: number` - - `type: "function"` + Unix timestamp (in seconds) for when the item was created. - For function calling, the type is always `function`. + - `object: "chatkit.thread_item"` - - `beta_tool_choice_mcp: object { server_label, type, name }` + Type discriminator that is always `chatkit.thread_item`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `thread_id: string` - - `server_label: string` + Identifier of the parent thread. - The label of the MCP server to use. + - `type: "chatkit.assistant_message"` - - `type: "mcp"` + Type discriminator that is always `chatkit.assistant_message`. - For MCP tools, the type is always `mcp`. + - `chatkit_widget_item: object { id, created_at, object, 3 more }` - - `name: optional string` + Thread item that renders a widget payload. - The name of the tool to call on the server. + - `id: string` - - `beta_tool_choice_custom: object { name, type }` + Identifier of the thread item. - Use this option to force the model to call a specific custom tool. + - `created_at: number` - - `name: string` + Unix timestamp (in seconds) for when the item was created. - The name of the custom tool to call. + - `object: "chatkit.thread_item"` - - `type: "custom"` + Type discriminator that is always `chatkit.thread_item`. - For custom tool calling, the type is always `custom`. + - `thread_id: string` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + Identifier of the parent thread. - - `beta_tool_choice_apply_patch: object { type }` + - `type: "chatkit.widget"` - Forces the model to call the apply_patch tool when executing a tool call. + Type discriminator that is always `chatkit.widget`. - - `type: "apply_patch"` + - `widget: string` - The tool to call. Always `apply_patch`. + Serialized widget payload rendered in the UI. - - `beta_tool_choice_shell: object { type }` + - `chatkit.client_tool_call: object { id, arguments, call_id, 7 more }` - Forces the model to call the shell tool when a tool call is required. + Record of a client side tool invocation initiated by the assistant. - - `type: "shell"` + - `id: string` - The tool to call. Always `shell`. + Identifier of the thread item. - - `tools: optional array of BetaTool` + - `arguments: string` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + JSON-encoded arguments that were sent to the tool. - We support the following categories of tools: + - `call_id: string` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + Identifier for the client tool call. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `created_at: number` - 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). + Unix timestamp (in seconds) for when the item was created. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `name: string` - 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). + Tool name that was invoked. - - `beta_computer_tool: object { type }` + - `object: "chatkit.thread_item"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Type discriminator that is always `chatkit.thread_item`. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `output: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `status: "in_progress" or "completed"` - 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). + Execution status for the tool call. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `"in_progress"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"completed"` - - `code_interpreter: object { container, type, allowed_callers }` + - `thread_id: string` - A tool that runs Python code to help generate a response to a prompt. + Identifier of the parent thread. - - `programmatic_tool_calling: object { type }` + - `type: "chatkit.client_tool_call"` - - `image_generation: object { type, action, background, 9 more }` + Type discriminator that is always `chatkit.client_tool_call`. - A tool that generates images using the GPT image models. + - `chatkit.task: object { id, created_at, heading, 5 more }` - - `local_shell: object { type }` + Task emitted by the workflow to show progress and status updates. - A tool that allows the model to execute shell commands in a local environment. + - `id: string` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + Identifier of the thread item. - A tool that allows the model to execute shell commands. + - `created_at: number` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Unix timestamp (in seconds) for when the item was created. - 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) + - `heading: string` - - `beta_namespace_tool: object { description, name, tools, type }` + Optional heading for the task. Defaults to null when not provided. - Groups function/custom tools under a shared namespace. + - `object: "chatkit.thread_item"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + Type discriminator that is always `chatkit.thread_item`. - Hosted or BYOT tool search configuration for deferred tools. + - `summary: string` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + Optional summary that describes the task. Defaults to null when omitted. - 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). + - `task_type: "custom" or "thought"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + Subtype for the task. - Allows the assistant to create, delete, or update files using unified diffs. + - `"custom"` - - `top_logprobs: optional number` + - `"thought"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `thread_id: string` - - `top_p: optional number` + Identifier of the parent thread. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `type: "chatkit.task"` - We generally recommend altering this or `temperature` but not both. + Type discriminator that is always `chatkit.task`. - - `truncation: optional "auto" or "disabled"` + - `chatkit.task_group: object { id, created_at, object, 3 more }` - The truncation strategy to use for the model response. + Collection of workflow tasks grouped together in the thread. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `id: string` - - `"auto"` + Identifier of the thread item. - - `"disabled"` + - `created_at: number` - - `user: optional string` + Unix timestamp (in seconds) for when the item was created. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `object: "chatkit.thread_item"` - - `response.inject: object { input, response_id, type }` + Type discriminator that is always `chatkit.thread_item`. - Injects input items into an active response over a WebSocket connection. - The items are validated and committed atomically. Currently, the server - accepts client-owned tool outputs that resume a waiting agent. + - `tasks: array of object { heading, summary, type }` - - `input: array of BetaResponseInputItem` + Tasks included in the group. - Input items to inject into the active response. + - `heading: string` - - `beta_easy_input_message: object { content, role, phase, type }` + Optional heading for the grouped task. Defaults to null when not provided. - 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. + - `summary: string` - - `message: object { content, role, agent, 2 more }` + Optional summary that describes the grouped task. Defaults to null when omitted. - 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. + - `type: "custom" or "thought"` - - `beta_response_output_message: object { id, content, role, 4 more }` + Subtype for the grouped task. - An output message from the model. + - `"custom"` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `"thought"` - 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. + - `thread_id: string` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + Identifier of the parent thread. - 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. + - `type: "chatkit.task_group"` - - `computer_call_output: object { call_id, output, type, 4 more }` + Type discriminator that is always `chatkit.task_group`. - The output of a computer tool call. + - `first_id: string` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + The ID of the first item in the list. - 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. + - `has_more: boolean` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + Whether there are more items available. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `last_id: string` - - `function_call_output: object { call_id, output, type, 4 more }` + The ID of the last item in the list. - The output of a function tool call. + - `object: "list"` - - `agent_message: object { author, content, recipient, 3 more }` + The type of object returned, must be `list`. - A message routed between agents. +### Example - - `multi_agent_call: object { action, arguments, call_id, 3 more }` +```cli +openai beta:chatkit:threads list-items \ + --api-key 'My API Key' \ + --thread-id cthr_123 +``` - - `multi_agent_call_output: object { action, call_id, output, 3 more }` +#### Response - - `tool_search_call: object { arguments, type, id, 4 more }` +```json +{ + "data": [ + { + "id": "id", + "attachments": [ + { + "id": "id", + "mime_type": "mime_type", + "name": "name", + "preview_url": "https://example.com", + "type": "image" + } + ], + "content": [ + { + "text": "text", + "type": "input_text" + } + ], + "created_at": 0, + "inference_options": { + "model": "model", + "tool_choice": { + "id": "id" + } + }, + "object": "chatkit.thread_item", + "thread_id": "thread_id", + "type": "chatkit.user_message" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` +## Retrieve ChatKit thread - - `additional_tools: object { role, tools, type, 2 more }` +`$ openai beta:chatkit:threads retrieve` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` +**get** `/chatkit/threads/{thread_id}` - 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). +Retrieve a ChatKit thread by its identifier. - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` +### Parameters - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). +- `--thread-id: string` - - `image_generation_call: object { id, result, status, 2 more }` + Identifier of the ChatKit thread to retrieve. - An image generation request made by the model. +### Returns - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` +- `chatkit_thread: object { id, created_at, object, 3 more }` - A tool call to run code. + Represents a ChatKit thread and its current status. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `id: string` - A tool call to run a command on the local shell. + Identifier of the thread. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `created_at: number` - The output of a local shell tool call. + Unix timestamp (in seconds) for when the thread was created. - - `shell_call: object { action, call_id, type, 5 more }` + - `object: "chatkit.thread"` - A tool representing a request to execute one or more shell commands. + Type discriminator that is always `chatkit.thread`. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `status: object { type } or object { reason, type } or object { reason, type }` - The streamed output items emitted by a shell tool call. + Current status for the thread. Defaults to `active` for newly created threads. - - `apply_patch_call: object { call_id, operation, status, 4 more }` + - `active: object { type }` - A tool call representing a request to create, delete, or update files using diff patches. + Indicates that a thread is active. - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `locked: object { reason, type }` - The streamed output emitted by an apply patch tool call. + Indicates that a thread is locked and cannot accept new input. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `reason: string` - A list of tools available on an MCP server. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `type: "locked"` - A request for human approval of a tool invocation. + Status discriminator that is always `locked`. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + - `closed: object { reason, type }` - A response to an MCP approval request. + Indicates that a thread has been closed. - - `mcp_call: object { id, arguments, name, 7 more }` + - `reason: string` - An invocation of a tool on an MCP server. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `type: "closed"` - The output of a custom tool call from your code, being sent back to the model. + Status discriminator that is always `closed`. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `title: string` - A call to a custom tool created by the model. + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `compaction_trigger: object { type, agent }` + - `user: string` - Compacts the current context. Must be the final input item. + Free-form string that identifies your end user who owns the thread. - - `item_reference: object { id, agent, type }` +### Example - An internal identifier for an item to reference. +```cli +openai beta:chatkit:threads retrieve \ + --api-key 'My API Key' \ + --thread-id cthr_123 +``` - - `program: object { id, call_id, code, 3 more }` +#### Response - - `program_output: object { id, call_id, result, 3 more }` +```json +{ + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" +} +``` - - `response_id: string` +## Delete ChatKit thread - The ID of the active response that should receive the input. +`$ openai beta:chatkit:threads delete` - - `type: "response.inject"` +**delete** `/chatkit/threads/{thread_id}` - The event discriminator. Always `response.inject`. +Delete a ChatKit thread along with its items and stored attachments. -### Beta Responses Server Event +### Parameters -- `beta_responses_server_event: BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 52 more` +- `--thread-id: string` - Server events emitted by the Responses WebSocket server. + Identifier of the ChatKit thread to delete. - - `beta_response_audio_delta_event: object { delta, sequence_number, type, agent }` +### Returns - Emitted when there is a partial audio response. +- `BetaChatKitThreadDeleteResponse: object { id, deleted, object }` - - `delta: string` + Confirmation payload returned after deleting a thread. - A chunk of Base64 encoded response audio bytes. + - `id: string` - - `sequence_number: number` + Identifier of the deleted thread. - A sequence number for this chunk of the stream response. + - `deleted: boolean` - - `type: "response.audio.delta"` + Indicates that the thread has been deleted. - The type of the event. Always `response.audio.delta`. + - `object: "chatkit.thread.deleted"` - - `agent: optional object { agent_name }` + Type discriminator that is always `chatkit.thread.deleted`. - The agent that owns this multi-agent streaming event. +### Example - - `agent_name: string` +```cli +openai beta:chatkit:threads delete \ + --api-key 'My API Key' \ + --thread-id cthr_123 +``` - The canonical name of the agent that produced this item. +#### Response - - `beta_response_audio_done_event: object { sequence_number, type, agent }` +```json +{ + "id": "id", + "deleted": true, + "object": "chatkit.thread.deleted" +} +``` - Emitted when the audio response is complete. +## List ChatKit threads - - `sequence_number: number` +`$ openai beta:chatkit:threads list` - The sequence number of the delta. +**get** `/chatkit/threads` - - `type: "response.audio.done"` +List ChatKit threads with optional pagination and user filters. - The type of the event. Always `response.audio.done`. +### Parameters - - `agent: optional object { agent_name }` +- `--after: optional string` - The agent that owns this multi-agent streaming event. + List items created after this thread item ID. Defaults to null for the first page. - - `agent_name: string` +- `--before: optional string` - The canonical name of the agent that produced this item. + List items created before this thread item ID. Defaults to null for the newest results. - - `beta_response_audio_transcript_delta_event: object { delta, sequence_number, type, agent }` +- `--limit: optional number` - Emitted when there is a partial transcript of audio. + Maximum number of thread items to return. Defaults to 20. - - `delta: string` +- `--order: optional "asc" or "desc"` - The partial transcript of the audio response. + Sort order for results by creation time. Defaults to `desc`. - - `sequence_number: number` +- `--user: optional string` - The sequence number of this event. + Filter threads that belong to this user identifier. Defaults to null to return all users. - - `type: "response.audio.transcript.delta"` +### Returns - The type of the event. Always `response.audio.transcript.delta`. +- `Threads: object { data, first_id, has_more, 2 more }` - - `agent: optional object { agent_name }` + A paginated list of ChatKit threads. - The agent that owns this multi-agent streaming event. + - `data: array of ChatKitThread` - - `agent_name: string` + A list of items - The canonical name of the agent that produced this item. + - `id: string` - - `beta_response_audio_transcript_done_event: object { sequence_number, type, agent }` + Identifier of the thread. - Emitted when the full audio transcript is completed. + - `created_at: number` - - `sequence_number: number` + Unix timestamp (in seconds) for when the thread was created. - The sequence number of this event. + - `object: "chatkit.thread"` - - `type: "response.audio.transcript.done"` + Type discriminator that is always `chatkit.thread`. - The type of the event. Always `response.audio.transcript.done`. + - `status: object { type } or object { reason, type } or object { reason, type }` - - `agent: optional object { agent_name }` + Current status for the thread. Defaults to `active` for newly created threads. - The agent that owns this multi-agent streaming event. + - `active: object { type }` - - `agent_name: string` + Indicates that a thread is active. - The canonical name of the agent that produced this item. + - `locked: object { reason, type }` - - `beta_response_code_interpreter_call_code_delta_event: object { delta, item_id, output_index, 3 more }` + Indicates that a thread is locked and cannot accept new input. - Emitted when a partial code snippet is streamed by the code interpreter. + - `reason: string` - - `delta: string` + Reason that the thread was locked. Defaults to null when no reason is recorded. - The partial code snippet being streamed by the code interpreter. + - `type: "locked"` - - `item_id: string` + Status discriminator that is always `locked`. - The unique identifier of the code interpreter tool call item. + - `closed: object { reason, type }` - - `output_index: number` + Indicates that a thread has been closed. - The index of the output item in the response for which the code is being streamed. + - `reason: string` - - `sequence_number: number` + Reason that the thread was closed. Defaults to null when no reason is recorded. - The sequence number of this event, used to order streaming events. + - `type: "closed"` - - `type: "response.code_interpreter_call_code.delta"` + Status discriminator that is always `closed`. - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `title: string` - - `agent: optional object { agent_name }` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - The agent that owns this multi-agent streaming event. + - `user: string` - - `agent_name: string` + Free-form string that identifies your end user who owns the thread. - The canonical name of the agent that produced this item. + - `first_id: string` - - `beta_response_code_interpreter_call_code_done_event: object { code, item_id, output_index, 3 more }` + The ID of the first item in the list. - Emitted when the code snippet is finalized by the code interpreter. + - `has_more: boolean` - - `code: string` + Whether there are more items available. - The final code snippet output by the code interpreter. + - `last_id: string` - - `item_id: string` + The ID of the last item in the list. - The unique identifier of the code interpreter tool call item. + - `object: "list"` - - `output_index: number` + The type of object returned, must be `list`. - The index of the output item in the response for which the code is finalized. +### Example - - `sequence_number: number` +```cli +openai beta:chatkit:threads list \ + --api-key 'My API Key' +``` - The sequence number of this event, used to order streaming events. +#### Response - - `type: "response.code_interpreter_call_code.done"` +```json +{ + "data": [ + { + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - The type of the event. Always `response.code_interpreter_call_code.done`. +## Domain Types - - `agent: optional object { agent_name }` +### Chat Session - The agent that owns this multi-agent streaming event. +- `chat_session: object { id, chatkit_configuration, client_secret, 7 more }` - - `agent_name: string` + Represents a ChatKit session and its resolved configuration. - The canonical name of the agent that produced this item. + - `id: string` - - `beta_response_code_interpreter_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + Identifier for the ChatKit session. - Emitted when the code interpreter call is completed. + - `chatkit_configuration: object { automatic_thread_titling, file_upload, history }` - - `item_id: string` + Resolved ChatKit feature configuration for the session. - The unique identifier of the code interpreter tool call item. + - `automatic_thread_titling: object { enabled }` - - `output_index: number` + Automatic thread titling preferences. - The index of the output item in the response for which the code interpreter call is completed. + - `enabled: boolean` - - `sequence_number: number` + Whether automatic thread titling is enabled. - The sequence number of this event, used to order streaming events. + - `file_upload: object { enabled, max_file_size, max_files }` - - `type: "response.code_interpreter_call.completed"` + Upload settings for the session. - The type of the event. Always `response.code_interpreter_call.completed`. + - `enabled: boolean` - - `agent: optional object { agent_name }` + Indicates if uploads are enabled for the session. - The agent that owns this multi-agent streaming event. + - `max_file_size: number` - - `agent_name: string` + Maximum upload size in megabytes. - The canonical name of the agent that produced this item. + - `max_files: number` - - `beta_response_code_interpreter_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + Maximum number of uploads allowed during the session. - Emitted when a code interpreter call is in progress. + - `history: object { enabled, recent_threads }` - - `item_id: string` + History retention configuration. - The unique identifier of the code interpreter tool call item. + - `enabled: boolean` - - `output_index: number` + Indicates if chat history is persisted for the session. - The index of the output item in the response for which the code interpreter call is in progress. + - `recent_threads: number` - - `sequence_number: number` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - The sequence number of this event, used to order streaming events. + - `client_secret: string` - - `type: "response.code_interpreter_call.in_progress"` + Ephemeral client secret that authenticates session requests. - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `expires_at: number` - - `agent: optional object { agent_name }` + Unix timestamp (in seconds) for when the session expires. - The agent that owns this multi-agent streaming event. + - `max_requests_per_1_minute: number` - - `agent_name: string` + Convenience copy of the per-minute request limit. - The canonical name of the agent that produced this item. + - `object: "chatkit.session"` - - `beta_response_code_interpreter_call_interpreting_event: object { item_id, output_index, sequence_number, 2 more }` + Type discriminator that is always `chatkit.session`. - Emitted when the code interpreter is actively interpreting the code snippet. + - `rate_limits: object { max_requests_per_1_minute }` - - `item_id: string` + Resolved rate limit values. - The unique identifier of the code interpreter tool call item. + - `max_requests_per_1_minute: number` - - `output_index: number` + Maximum allowed requests per one-minute window. - The index of the output item in the response for which the code interpreter is interpreting code. + - `status: "active" or "expired" or "cancelled"` - - `sequence_number: number` + Current lifecycle state of the session. - The sequence number of this event, used to order streaming events. + - `"active"` - - `type: "response.code_interpreter_call.interpreting"` + - `"expired"` - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `"cancelled"` - - `agent: optional object { agent_name }` + - `user: string` - The agent that owns this multi-agent streaming event. + User identifier associated with the session. - - `agent_name: string` + - `workflow: object { id, state_variables, tracing, version }` - The canonical name of the agent that produced this item. + Workflow metadata for the session. - - `beta_response_completed_event: object { response, sequence_number, type, agent }` + - `id: string` - Emitted when the model response is complete. + Identifier of the workflow backing the session. - - `response: object { id, created_at, error, 31 more }` + - `state_variables: map[string or boolean or number]` - Properties of the completed response. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `id: string` + - `union_member_0: string` - Unique identifier for this Response. + - `union_member_1: boolean` - - `created_at: number` + - `union_member_2: number` - Unix timestamp (in seconds) of when this Response was created. + - `tracing: object { enabled }` - - `error: object { code, message }` + Tracing settings applied to the workflow. - An error object returned when the model fails to generate a Response. + - `enabled: boolean` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 16 more` + Indicates whether tracing is enabled. - The error code for the response. + - `version: string` - - `"server_error"` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"rate_limit_exceeded"` +### Chat Session Automatic Thread Titling - - `"invalid_prompt"` +- `chat_session_automatic_thread_titling: object { enabled }` - - `"bio_policy"` + Automatic thread title preferences for the session. - - `"vector_store_timeout"` + - `enabled: boolean` - - `"invalid_image"` + Whether automatic thread titling is enabled. - - `"invalid_image_format"` +### Chat Session ChatKit Configuration - - `"invalid_base64_image"` +- `chat_session_chatkit_configuration: object { automatic_thread_titling, file_upload, history }` - - `"invalid_image_url"` + ChatKit configuration for the session. - - `"image_too_large"` + - `automatic_thread_titling: object { enabled }` - - `"image_too_small"` + Automatic thread titling preferences. - - `"image_parse_error"` + - `enabled: boolean` - - `"image_content_policy_violation"` + Whether automatic thread titling is enabled. - - `"invalid_image_mode"` + - `file_upload: object { enabled, max_file_size, max_files }` - - `"image_file_too_large"` + Upload settings for the session. - - `"unsupported_image_media_type"` + - `enabled: boolean` - - `"empty_image_file"` + Indicates if uploads are enabled for the session. - - `"failed_to_download_image"` + - `max_file_size: number` - - `"image_file_not_found"` + Maximum upload size in megabytes. - - `message: string` + - `max_files: number` - A human-readable description of the error. + Maximum number of uploads allowed during the session. - - `incomplete_details: object { reason }` + - `history: object { enabled, recent_threads }` - Details about why the response is incomplete. + History retention configuration. - - `reason: optional "max_output_tokens" or "content_filter"` + - `enabled: boolean` - The reason why the response is incomplete. + Indicates if chat history is persisted for the session. - - `"max_output_tokens"` + - `recent_threads: number` - - `"content_filter"` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `instructions: string or array of BetaResponseInputItem` +### Chat Session ChatKit Configuration Param - A system (or developer) message inserted into the model's context. +- `chat_session_chatkit_configuration_param: object { automatic_thread_titling, file_upload, history }` - When using 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 per-session configuration settings for ChatKit behavior. - - `union_member_0: string` + - `automatic_thread_titling: optional object { enabled }` - A text input to the model, equivalent to a text input with the - `developer` role. + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `Input item list: array of BetaResponseInputItem` + - `enabled: optional boolean` - A list of one or many input items to the model, containing - different content types. + Enable automatic thread title generation. Defaults to true. - - `beta_easy_input_message: object { content, role, phase, type }` + - `file_upload: optional object { enabled, max_file_size, max_files }` - 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. + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - - `content: string or BetaResponseInputMessageContentList` + - `enabled: optional boolean` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + Enable uploads for this session. Defaults to false. - - `Text input: string` + - `max_file_size: optional number` - A text input to the model. + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `beta_response_input_message_content_list: array of BetaResponseInputContent` + - `max_files: optional number` - A list of one or many input items to the model, containing different content - types. + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `history: optional object { enabled, recent_threads }` - A text input to the model. + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - - `text: string` + - `enabled: optional boolean` - The text input to the model. + Enables chat users to access previous ChatKit threads. Defaults to true. - - `type: "input_text"` + - `recent_threads: optional number` - The type of the input item. Always `input_text`. + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `prompt_cache_breakpoint: optional object { mode }` +### Chat Session Expires After Param - 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. +- `chat_session_expires_after_param: object { anchor, seconds }` - - `mode: "explicit"` + Controls when the session expires relative to an anchor timestamp. - The breakpoint mode. Always `explicit`. + - `anchor: "created_at"` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `seconds: number` - - `detail: "low" or "high" or "auto" or "original"` + Number of seconds after the anchor when the session expires. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +### Chat Session File Upload - - `"low"` +- `chat_session_file_upload: object { enabled, max_file_size, max_files }` - - `"high"` + Upload permissions and limits applied to the session. - - `"auto"` + - `enabled: boolean` - - `"original"` + Indicates if uploads are enabled for the session. - - `type: "input_image"` + - `max_file_size: number` - The type of the input item. Always `input_image`. + Maximum upload size in megabytes. - - `file_id: optional string` + - `max_files: number` - The ID of the file to be sent to the model. + Maximum number of uploads allowed during the session. - - `image_url: optional string` +### Chat Session History - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. +- `chat_session_history: object { enabled, recent_threads }` - - `prompt_cache_breakpoint: optional object { mode }` + History retention preferences returned for the session. - 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. + - `enabled: boolean` - - `mode: "explicit"` + Indicates if chat history is persisted for the session. - The breakpoint mode. Always `explicit`. + - `recent_threads: number` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - A file input to the model. +### Chat Session Rate Limits - - `type: "input_file"` +- `chat_session_rate_limits: object { max_requests_per_1_minute }` - The type of the input item. Always `input_file`. + Active per-minute request limit for the session. - - `detail: optional "auto" or "low" or "high"` + - `max_requests_per_1_minute: number` - 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`. + Maximum allowed requests per one-minute window. - - `"auto"` +### Chat Session Rate Limits Param - - `"low"` +- `chat_session_rate_limits_param: object { max_requests_per_1_minute }` - - `"high"` + Controls request rate limits for the session. - - `file_data: optional string` + - `max_requests_per_1_minute: optional number` - The content of the file to be sent to the model. + Maximum number of requests allowed per minute for the session. Defaults to 10. - - `file_id: optional string` +### Chat Session Status - The ID of the file to be sent to the model. +- `chat_session_status: "active" or "expired" or "cancelled"` - - `file_url: optional string` + - `"active"` - The URL of the file to be sent to the model. + - `"expired"` - - `filename: optional string` + - `"cancelled"` - The name of the file to be sent to the model. +### Chat Session Workflow Param - - `prompt_cache_breakpoint: optional object { mode }` +- `chat_session_workflow_param: object { id, state_variables, tracing, version }` - 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. + Workflow reference and overrides applied to the chat session. - - `mode: "explicit"` + - `id: string` - The breakpoint mode. Always `explicit`. + Identifier for the workflow invoked by the session. - - `role: "user" or "assistant" or "system" or "developer"` + - `state_variables: optional map[string or boolean or number]` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - - `"user"` + - `union_member_0: string` - - `"assistant"` + - `union_member_1: boolean` - - `"system"` + - `union_member_2: number` - - `"developer"` + - `tracing: optional object { enabled }` - - `phase: optional "commentary"` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - 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. + - `enabled: optional boolean` - - `"commentary"` + Whether tracing is enabled during the session. Defaults to true. - - `type: optional "message"` + - `version: optional string` - The type of the message input. Always `message`. + Specific workflow version to run. Defaults to the latest deployed version. - - `"message"` +### ChatKit Attachment - - `message: object { content, role, agent, 2 more }` +- `chatkit_attachment: object { id, mime_type, name, 2 more }` - 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. + Attachment metadata included on thread items. - - `content: array of BetaResponseInputContent` + - `id: string` - A list of one or many input items to the model, containing different content - types. + Identifier for the attachment. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `mime_type: string` - A text input to the model. + MIME type of the attachment. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `name: string` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + Original display name for the attachment. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `preview_url: string` - A file input to the model. + Preview URL for rendering the attachment inline. - - `role: "user" or "system" or "developer"` + - `type: "image" or "file"` - The role of the message input. One of `user`, `system`, or `developer`. + Attachment discriminator. - - `"user"` + - `"image"` - - `"system"` + - `"file"` - - `"developer"` +### ChatKit Response Output Text - - `agent: optional object { agent_name }` +- `chatkit_response_output_text: object { annotations, text, type }` - The agent that produced this item. + Assistant response text accompanied by optional annotations. - - `agent_name: string` + - `annotations: array of object { source, type } or object { source, type }` - The canonical name of the agent that produced this item. + Ordered list of annotations attached to the response text. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `file: object { source, type }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Annotation that references an uploaded file. - - `"in_progress"` + - `source: object { filename, type }` - - `"completed"` + File attachment referenced by the annotation. - - `"incomplete"` + - `filename: string` - - `type: optional "message"` + Filename referenced by the annotation. - The type of the message input. Always set to `message`. + - `type: "file"` - - `"message"` + Type discriminator that is always `file`. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `type: "file"` - An output message from the model. + Type discriminator that is always `file` for this annotation. - - `id: string` + - `url: object { source, type }` - The unique ID of the output message. + Annotation that references a URL. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `source: object { type, url }` - The content of the output message. + URL referenced by the annotation. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `type: "url"` - A text output from the model. + Type discriminator that is always `url`. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `url: string` - The annotations of the text output. + URL referenced by the annotation. - - `file_citation: object { file_id, filename, index, type }` + - `type: "url"` - A citation to a file. + Type discriminator that is always `url` for this annotation. - - `file_id: string` + - `text: string` - The ID of the file. + Assistant generated text. - - `filename: string` + - `type: "output_text"` + + Type discriminator that is always `output_text`. - The filename of the file cited. +### ChatKit Thread - - `index: number` +- `chatkit_thread: object { id, created_at, object, 3 more }` - The index of the file in the list of files. + Represents a ChatKit thread and its current status. - - `type: "file_citation"` + - `id: string` - The type of the file citation. Always `file_citation`. + Identifier of the thread. - - `url_citation: object { end_index, start_index, title, 2 more }` + - `created_at: number` - A citation for a web resource used to generate a model response. + Unix timestamp (in seconds) for when the thread was created. - - `end_index: number` + - `object: "chatkit.thread"` - The index of the last character of the URL citation in the message. + Type discriminator that is always `chatkit.thread`. - - `start_index: number` + - `status: object { type } or object { reason, type } or object { reason, type }` - The index of the first character of the URL citation in the message. + Current status for the thread. Defaults to `active` for newly created threads. - - `title: string` + - `active: object { type }` - The title of the web resource. + Indicates that a thread is active. - - `type: "url_citation"` + - `locked: object { reason, type }` - The type of the URL citation. Always `url_citation`. + Indicates that a thread is locked and cannot accept new input. - - `url: string` + - `reason: string` - The URL of the web resource. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `type: "locked"` - A citation for a container file used to generate a model response. + Status discriminator that is always `locked`. - - `container_id: string` + - `closed: object { reason, type }` - The ID of the container file. + Indicates that a thread has been closed. - - `end_index: number` + - `reason: string` - The index of the last character of the container file citation in the message. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `file_id: string` + - `type: "closed"` - The ID of the file. + Status discriminator that is always `closed`. - - `filename: string` + - `title: string` - The filename of the container file cited. + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `start_index: number` + - `user: string` - The index of the first character of the container file citation in the message. + Free-form string that identifies your end user who owns the thread. - - `type: "container_file_citation"` +### ChatKit Thread Assistant Message Item - The type of the container file citation. Always `container_file_citation`. +- `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` - - `file_path: object { file_id, index, type }` + Assistant-authored message within a thread. - A path to a file. + - `id: string` - - `file_id: string` + Identifier of the thread item. - The ID of the file. + - `content: array of ChatKitResponseOutputText` - - `index: number` + Ordered assistant response segments. - The index of the file in the list of files. + - `annotations: array of object { source, type } or object { source, type }` - - `type: "file_path"` + Ordered list of annotations attached to the response text. - The type of the file path. Always `file_path`. + - `file: object { source, type }` - - `text: string` + Annotation that references an uploaded file. - The text output from the model. + - `source: object { filename, type }` - - `type: "output_text"` + File attachment referenced by the annotation. - The type of the output text. Always `output_text`. + - `filename: string` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + Filename referenced by the annotation. - - `token: string` + - `type: "file"` - - `bytes: array of number` + Type discriminator that is always `file`. - - `logprob: number` + - `type: "file"` - - `top_logprobs: array of object { token, bytes, logprob }` + Type discriminator that is always `file` for this annotation. - - `token: string` + - `url: object { source, type }` - - `bytes: array of number` + Annotation that references a URL. - - `logprob: number` + - `source: object { type, url }` - - `beta_response_output_refusal: object { refusal, type }` + URL referenced by the annotation. - A refusal from the model. + - `type: "url"` - - `refusal: string` + Type discriminator that is always `url`. - The refusal explanation from the model. + - `url: string` - - `type: "refusal"` + URL referenced by the annotation. - The type of the refusal. Always `refusal`. + - `type: "url"` - - `role: "assistant"` + Type discriminator that is always `url` for this annotation. - The role of the output message. Always `assistant`. + - `text: string` - - `status: "in_progress" or "completed" or "incomplete"` + Assistant generated text. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "output_text"` - - `"in_progress"` + Type discriminator that is always `output_text`. - - `"completed"` + - `created_at: number` - - `"incomplete"` + Unix timestamp (in seconds) for when the item was created. - - `type: "message"` + - `object: "chatkit.thread_item"` - The type of the output message. Always `message`. + Type discriminator that is always `chatkit.thread_item`. - - `agent: optional object { agent_name }` + - `thread_id: string` - The agent that produced this item. + Identifier of the parent thread. - - `agent_name: string` + - `type: "chatkit.assistant_message"` - The canonical name of the agent that produced this item. + Type discriminator that is always `chatkit.assistant_message`. - - `phase: optional "commentary"` +### ChatKit Thread Item List - 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. +- `chatkit_thread_item_list: object { data, first_id, has_more, 2 more }` - - `"commentary"` + A paginated list of thread items rendered for the ChatKit API. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - 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. + A list of items - - `id: string` + - `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` - The unique ID of the file search tool call. + User-authored messages within a thread. - - `queries: array of string` + - `id: string` - The queries used to search for files. + Identifier of the thread item. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `attachments: array of ChatKitAttachment` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Attachments associated with the user message. Defaults to an empty list. - - `"in_progress"` + - `id: string` - - `"searching"` + Identifier for the attachment. - - `"completed"` + - `mime_type: string` - - `"incomplete"` + MIME type of the attachment. - - `"failed"` + - `name: string` - - `type: "file_search_call"` + Original display name for the attachment. - The type of the file search tool call. Always `file_search_call`. + - `preview_url: string` - - `agent: optional object { agent_name }` + Preview URL for rendering the attachment inline. - The agent that produced this item. + - `type: "image" or "file"` - - `agent_name: string` + Attachment discriminator. - The canonical name of the agent that produced this item. + - `"image"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"file"` - The results of the file search tool call. + - `content: array of object { text, type } or object { text, type }` - - `attributes: optional map[string or number or boolean]` + Ordered content elements supplied by the user. - 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. + - `input_text: object { text, type }` - - `union_member_0: string` + Text block that a user contributed to the thread. - - `union_member_1: number` + - `text: string` - - `union_member_2: boolean` + Plain-text content supplied by the user. - - `file_id: optional string` + - `type: "input_text"` - The unique ID of the file. + Type discriminator that is always `input_text`. - - `filename: optional string` + - `quoted_text: object { text, type }` - The name of the file. + Quoted snippet that the user referenced in their message. - - `score: optional number` + - `text: string` - The relevance score of the file - a value between 0 and 1. + Quoted text content. - - `text: optional string` + - `type: "quoted_text"` - The text that was retrieved from the file. + Type discriminator that is always `quoted_text`. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `created_at: number` - 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. + Unix timestamp (in seconds) for when the item was created. - - `id: string` + - `inference_options: object { model, tool_choice }` - The unique ID of the computer call. + Inference overrides applied to the message. Defaults to null when unset. - - `call_id: string` + - `model: string` - An identifier used when responding to the tool call with output. + Model name that generated the response. Defaults to null when using the session default. - - `pending_safety_checks: array of object { id, code, message }` + - `tool_choice: object { id }` - The pending safety checks for the computer call. + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - `id: string` - The ID of the pending safety check. + Identifier of the requested tool. - - `code: optional string` + - `object: "chatkit.thread_item"` - The type of the pending safety check. + Type discriminator that is always `chatkit.thread_item`. - - `message: optional string` + - `thread_id: string` - Details about the pending safety check. + Identifier of the parent thread. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "chatkit.user_message"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }` - - `"in_progress"` + Assistant-authored message within a thread. - - `"completed"` + - `id: string` - - `"incomplete"` + Identifier of the thread item. - - `type: "computer_call"` + - `content: array of ChatKitResponseOutputText` - The type of the computer call. Always `computer_call`. + Ordered assistant response segments. - - `"computer_call"` + - `annotations: array of object { source, type } or object { source, type }` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + Ordered list of annotations attached to the response text. - A click action. + - `file: object { source, type }` - - `click: object { button, type, x, 2 more }` + Annotation that references an uploaded file. - A click action. + - `source: object { filename, type }` - - `button: "left" or "right" or "wheel" or 2 more` + File attachment referenced by the annotation. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `filename: string` - - `"left"` + Filename referenced by the annotation. - - `"right"` + - `type: "file"` - - `"wheel"` + Type discriminator that is always `file`. - - `"back"` + - `type: "file"` - - `"forward"` + Type discriminator that is always `file` for this annotation. - - `type: "click"` + - `url: object { source, type }` - Specifies the event type. For a click action, this property is always `click`. + Annotation that references a URL. - - `x: number` + - `source: object { type, url }` - The x-coordinate where the click occurred. + URL referenced by the annotation. - - `y: number` + - `type: "url"` - The y-coordinate where the click occurred. + Type discriminator that is always `url`. - - `keys: optional array of string` + - `url: string` - The keys being held while clicking. + URL referenced by the annotation. - - `double_click: object { keys, type, x, y }` + - `type: "url"` - A double click action. + Type discriminator that is always `url` for this annotation. - - `keys: array of string` + - `text: string` - The keys being held while double-clicking. + Assistant generated text. - - `type: "double_click"` + - `type: "output_text"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Type discriminator that is always `output_text`. - - `x: number` + - `created_at: number` - The x-coordinate where the double click occurred. + Unix timestamp (in seconds) for when the item was created. - - `y: number` + - `object: "chatkit.thread_item"` - The y-coordinate where the double click occurred. + Type discriminator that is always `chatkit.thread_item`. - - `drag: object { path, type, keys }` + - `thread_id: string` - A drag action. + Identifier of the parent thread. - - `path: array of object { x, y }` + - `type: "chatkit.assistant_message"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Type discriminator that is always `chatkit.assistant_message`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `chatkit_widget_item: object { id, created_at, object, 3 more }` - - `x: number` + Thread item that renders a widget payload. - The x-coordinate. + - `id: string` - - `y: number` + Identifier of the thread item. - The y-coordinate. + - `created_at: number` - - `type: "drag"` + Unix timestamp (in seconds) for when the item was created. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `object: "chatkit.thread_item"` - - `keys: optional array of string` + Type discriminator that is always `chatkit.thread_item`. - The keys being held while dragging the mouse. + - `thread_id: string` - - `keypress: object { keys, type }` + Identifier of the parent thread. - A collection of keypresses the model would like to perform. + - `type: "chatkit.widget"` - - `keys: array of string` + Type discriminator that is always `chatkit.widget`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `widget: string` - - `type: "keypress"` + Serialized widget payload rendered in the UI. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `chatkit.client_tool_call: object { id, arguments, call_id, 7 more }` - - `move: object { type, x, y, keys }` + Record of a client side tool invocation initiated by the assistant. - A mouse move action. + - `id: string` - - `type: "move"` + Identifier of the thread item. - Specifies the event type. For a move action, this property is always set to `move`. + - `arguments: string` - - `x: number` + JSON-encoded arguments that were sent to the tool. - The x-coordinate to move to. + - `call_id: string` - - `y: number` + Identifier for the client tool call. - The y-coordinate to move to. + - `created_at: number` - - `keys: optional array of string` + Unix timestamp (in seconds) for when the item was created. - The keys being held while moving the mouse. + - `name: string` - - `screenshot: object { type }` + Tool name that was invoked. - A screenshot action. + - `object: "chatkit.thread_item"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + Type discriminator that is always `chatkit.thread_item`. - A scroll action. + - `output: string` - - `scroll_x: number` + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - The horizontal scroll distance. + - `status: "in_progress" or "completed"` - - `scroll_y: number` + Execution status for the tool call. - The vertical scroll distance. + - `"in_progress"` - - `type: "scroll"` + - `"completed"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `thread_id: string` - - `x: number` + Identifier of the parent thread. - The x-coordinate where the scroll occurred. + - `type: "chatkit.client_tool_call"` - - `y: number` + Type discriminator that is always `chatkit.client_tool_call`. - The y-coordinate where the scroll occurred. + - `chatkit.task: object { id, created_at, heading, 5 more }` - - `keys: optional array of string` + Task emitted by the workflow to show progress and status updates. - The keys being held while scrolling. + - `id: string` - - `type: object { text, type }` + Identifier of the thread item. - An action to type in text. + - `created_at: number` - - `text: string` + Unix timestamp (in seconds) for when the item was created. - The text to type. + - `heading: string` - - `type: "type"` + Optional heading for the task. Defaults to null when not provided. - Specifies the event type. For a type action, this property is always set to `type`. + - `object: "chatkit.thread_item"` - - `wait: object { type }` + Type discriminator that is always `chatkit.thread_item`. - A wait action. + - `summary: string` - - `actions: optional array of BetaComputerAction` + Optional summary that describes the task. Defaults to null when omitted. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `task_type: "custom" or "thought"` - - `click: object { button, type, x, 2 more }` + Subtype for the task. - A click action. + - `"custom"` - - `double_click: object { keys, type, x, y }` + - `"thought"` - A double click action. + - `thread_id: string` - - `drag: object { path, type, keys }` + Identifier of the parent thread. - A drag action. + - `type: "chatkit.task"` - - `keypress: object { keys, type }` + Type discriminator that is always `chatkit.task`. - A collection of keypresses the model would like to perform. + - `chatkit.task_group: object { id, created_at, object, 3 more }` - - `move: object { type, x, y, keys }` + Collection of workflow tasks grouped together in the thread. - A mouse move action. + - `id: string` - - `screenshot: object { type }` + Identifier of the thread item. - A screenshot action. + - `created_at: number` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + Unix timestamp (in seconds) for when the item was created. - A scroll action. + - `object: "chatkit.thread_item"` - - `type: object { text, type }` + Type discriminator that is always `chatkit.thread_item`. - An action to type in text. + - `tasks: array of object { heading, summary, type }` - - `wait: object { type }` + Tasks included in the group. - A wait action. + - `heading: string` - - `agent: optional object { agent_name }` + Optional heading for the grouped task. Defaults to null when not provided. - The agent that produced this item. + - `summary: string` - - `agent_name: string` + Optional summary that describes the grouped task. Defaults to null when omitted. - The canonical name of the agent that produced this item. + - `type: "custom" or "thought"` - - `computer_call_output: object { call_id, output, type, 4 more }` + Subtype for the grouped task. - The output of a computer tool call. + - `"custom"` - - `call_id: string` + - `"thought"` - The ID of the computer tool call that produced the output. + - `thread_id: string` - - `output: object { type, file_id, image_url }` + Identifier of the parent thread. - A computer screenshot image used with the computer use tool. + - `type: "chatkit.task_group"` - - `type: "computer_screenshot"` + Type discriminator that is always `chatkit.task_group`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `first_id: string` - - `file_id: optional string` + The ID of the first item in the list. - The identifier of an uploaded file that contains the screenshot. + - `has_more: boolean` - - `image_url: optional string` + Whether there are more items available. - The URL of the screenshot image. + - `last_id: string` - - `type: "computer_call_output"` + The ID of the last item in the list. - The type of the computer tool call output. Always `computer_call_output`. + - `object: "list"` - - `id: optional string` + The type of object returned, must be `list`. - The ID of the computer tool call output. +### ChatKit Thread User Message Item - - `acknowledged_safety_checks: optional array of object { id, code, message }` +- `chatkit_thread_user_message_item: object { id, attachments, content, 5 more }` - The safety checks reported by the API that have been acknowledged by the developer. + User-authored messages within a thread. - `id: string` - The ID of the pending safety check. - - - `code: optional string` - - The type of the pending safety check. + Identifier of the thread item. - - `message: optional string` + - `attachments: array of ChatKitAttachment` - Details about the pending safety check. + Attachments associated with the user message. Defaults to an empty list. - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + Identifier for the attachment. - - `agent_name: string` + - `mime_type: string` - The canonical name of the agent that produced this item. + MIME type of the attachment. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + Original display name for the attachment. - - `"in_progress"` + - `preview_url: string` - - `"completed"` + Preview URL for rendering the attachment inline. - - `"incomplete"` + - `type: "image" or "file"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + Attachment discriminator. - 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. + - `"image"` - - `id: string` + - `"file"` - The unique ID of the web search tool call. + - `content: array of object { text, type } or object { text, type }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Ordered content elements supplied by the user. - 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). + - `input_text: object { text, type }` - - `search: object { type, queries, query, sources }` + Text block that a user contributed to the thread. - Action type "search" - Performs a web search query. + - `text: string` - - `type: "search"` + Plain-text content supplied by the user. - The action type. + - `type: "input_text"` - - `queries: optional array of string` + Type discriminator that is always `input_text`. - The search queries. + - `quoted_text: object { text, type }` - - `query: optional string` + Quoted snippet that the user referenced in their message. - The search query. + - `text: string` - - `sources: optional array of object { type, url }` + Quoted text content. - The sources used in the search. + - `type: "quoted_text"` - - `type: "url"` + Type discriminator that is always `quoted_text`. - The type of source. Always `url`. + - `created_at: number` - - `url: string` + Unix timestamp (in seconds) for when the item was created. - The URL of the source. + - `inference_options: object { model, tool_choice }` - - `open_page: object { type, url }` + Inference overrides applied to the message. Defaults to null when unset. - Action type "open_page" - Opens a specific URL from search results. + - `model: string` - - `type: "open_page"` + Model name that generated the response. Defaults to null when using the session default. - The action type. + - `tool_choice: object { id }` - - `url: optional string` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - The URL opened by the model. + - `id: string` - - `find_in_page: object { pattern, type, url }` + Identifier of the requested tool. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `object: "chatkit.thread_item"` - - `pattern: string` + Type discriminator that is always `chatkit.thread_item`. - The pattern or text to search for within the page. + - `thread_id: string` - - `type: "find_in_page"` + Identifier of the parent thread. - The action type. + - `type: "chatkit.user_message"` - - `url: string` +### ChatKit Widget Item - The URL of the page searched for the pattern. +- `chatkit_widget_item: object { id, created_at, object, 3 more }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + Thread item that renders a widget payload. - The status of the web search tool call. + - `id: string` - - `"in_progress"` + Identifier of the thread item. - - `"searching"` + - `created_at: number` - - `"completed"` + Unix timestamp (in seconds) for when the item was created. - - `"failed"` + - `object: "chatkit.thread_item"` - - `type: "web_search_call"` + Type discriminator that is always `chatkit.thread_item`. - The type of the web search tool call. Always `web_search_call`. + - `thread_id: string` - - `agent: optional object { agent_name }` + Identifier of the parent thread. - The agent that produced this item. + - `type: "chatkit.widget"` - - `agent_name: string` + Type discriminator that is always `chatkit.widget`. - The canonical name of the agent that produced this item. + - `widget: string` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + Serialized widget payload rendered in the UI. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. +# Assistants - - `arguments: string` +## List assistants - A JSON string of the arguments to pass to the function. +`$ openai beta:assistants list` - - `call_id: string` +**get** `/assistants` - The unique ID of the function tool call generated by the model. +Returns a list of assistants. - - `name: string` +### Parameters - The name of the function to run. +- `--after: optional string` - - `type: "function_call"` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - The type of the function tool call. Always `function_call`. +- `--before: optional string` - - `id: optional string` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - The unique ID of the function tool call. +- `--limit: optional number` - - `agent: optional object { agent_name }` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The agent that produced this item. +- `--order: optional "asc" or "desc"` - - `agent_name: string` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - The canonical name of the agent that produced this item. +### Returns - - `caller: optional object { type } or object { caller_id, type }` +- `ListAssistantsResponse: object { data, first_id, has_more, 2 more }` - The execution context that produced this tool call. + - `data: array of Assistant` - - `direct: object { type }` + - `id: string` - - `program: object { caller_id, type }` + The identifier, which can be referenced in API endpoints. - - `caller_id: string` + - `created_at: number` - The call ID of the program item that produced this tool call. + The Unix timestamp (in seconds) for when the assistant was created. - - `type: "program"` + - `description: string` - - `namespace: optional string` + The description of the assistant. The maximum length is 512 characters. - The namespace of the function to run. + - `instructions: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `metadata: map[string]` - - `"in_progress"` + 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. - - `"completed"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"incomplete"` + - `model: string` - - `function_call_output: object { call_id, output, type, 4 more }` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - The output of a function tool call. + - `name: string` - - `call_id: string` + The name of the assistant. The maximum length is 256 characters. - The unique ID of the function tool call generated by the model. + - `object: "assistant"` - - `output: string or BetaResponseFunctionCallOutputItemList` + The object type, which is always `assistant`. - Text, image, or file output of the function tool call. + - `tools: array of AssistantTool` - - `union_member_0: string` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - A JSON string of the output of the function tool call. + - `code_interpreter_tool: object { type }` - - `beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem` + - `type: "code_interpreter"` - An array of content outputs (text, image, file) for the function tool call. + The type of tool being defined: `code_interpreter` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` + - `file_search_tool: object { type, file_search }` - A text input to the model. + - `type: "file_search"` - - `text: string` + The type of tool being defined: `file_search` - The text input to the model. + - `file_search: optional object { max_num_results, ranking_options }` - - `type: "input_text"` + Overrides for the file search tool. - The type of the input item. Always `input_text`. + - `max_num_results: optional number` - - `prompt_cache_breakpoint: optional object { mode }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - 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. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `mode: "explicit"` + - `ranking_options: optional object { score_threshold, ranker }` - The breakpoint mode. Always `explicit`. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) + - `score_threshold: number` - - `type: "input_image"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The type of the input item. Always `input_image`. + - `ranker: optional "auto" or "default_2024_08_21"` - - `detail: optional "low" or "high" or "auto" or "original"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"auto"` - - `"low"` + - `"default_2024_08_21"` - - `"high"` + - `function_tool: object { function, type }` - - `"auto"` + - `function: object { name, description, parameters, strict }` - - `"original"` + - `name: string` - - `file_id: optional string` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The ID of the file to be sent to the model. + - `description: optional string` - - `image_url: optional string` + A description of what the function does, used by the model to choose when and how to call the function. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `parameters: optional map[unknown]` - - `prompt_cache_breakpoint: optional object { mode }` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - 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. + Omitting `parameters` defines a function with an empty parameter list. - - `mode: "explicit"` + - `strict: optional boolean` - The breakpoint mode. Always `explicit`. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `beta_response_input_file_content: object { type, detail, file_data, 4 more }` + - `type: "function"` - A file input to the model. + The type of tool being defined: `function` - - `type: "input_file"` + - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The type of the input item. Always `input_file`. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `detail: optional "auto" or "low" or "high"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - 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`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"auto"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"low"` + - `union_member_0: "auto"` - - `"high"` + `auto` is the default value - - `file_data: optional string` + - `response_format_text: object { type }` - The base64-encoded data of the file to be sent to the model. + Default response format. Used to generate text responses. - - `file_id: optional string` + - `type: "text"` - The ID of the file to be sent to the model. + The type of response format being defined. Always `text`. - - `file_url: optional string` + - `response_format_json_object: object { type }` - The URL of the file to be sent to the model. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `filename: optional string` + - `type: "json_object"` - The name of the file to be sent to the model. + The type of response format being defined. Always `json_object`. - - `prompt_cache_breakpoint: optional object { mode }` + - `response_format_json_schema: object { json_schema, type }` - 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. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `mode: "explicit"` + - `json_schema: object { name, description, schema, strict }` - The breakpoint mode. Always `explicit`. + Structured Outputs configuration options, including a JSON Schema. - - `type: "function_call_output"` + - `name: string` - The type of the function tool call output. Always `function_call_output`. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `id: optional string` + - `description: optional string` - The unique ID of the function tool call output. Populated when this item is returned via API. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `agent: optional object { agent_name }` + - `schema: optional map[unknown]` - The agent that produced this item. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `agent_name: string` + - `strict: optional boolean` - The canonical name of the agent that produced this item. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `caller: optional object { type } or object { caller_id, type }` + - `type: "json_schema"` - The execution context that produced this tool call. + The type of response format being defined. Always `json_schema`. - - `direct: object { type }` + - `temperature: optional number` - - `program: object { caller_id, type }` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `caller_id: string` + - `tool_resources: optional object { code_interpreter, file_search }` - The call ID of the program item that produced this tool call. + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `type: "program"` + - `code_interpreter: optional object { file_ids }` - The caller type. Always `program`. + - `file_ids: optional array of string` - - `status: optional "in_progress" or "completed" or "incomplete"` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `file_search: optional object { vector_store_ids }` - - `"in_progress"` + - `vector_store_ids: optional array of string` - - `"completed"` + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `"incomplete"` + - `top_p: optional number` - - `agent_message: object { author, content, recipient, 3 more }` + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - A message routed between agents. + We generally recommend altering this or temperature but not both. - - `author: string` + - `first_id: string` - The sending agent identity. + - `has_more: boolean` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `last_id: string` - Plaintext, image, or encrypted content sent between agents. + - `object: string` - - `beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }` +### Example - A text input to the model. +```cli +openai beta:assistants list \ + --api-key 'My API Key' +``` - - `text: string` +#### Response - The text input to the model. +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 + } + ], + "first_id": "asst_abc123", + "has_more": false, + "last_id": "asst_abc456", + "object": "list" +} +``` - - `type: "input_text"` +## Create assistant - The type of the input item. Always `input_text`. +`$ openai beta:assistants create` - - `prompt_cache_breakpoint: optional object { mode }` +**post** `/assistants` - 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. +Create an assistant with a model and instructions. - - `beta_response_input_image_content: object { type, detail, file_id, 2 more }` +### Parameters - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) +- `--model: string or ChatModel` - - `type: "input_image"` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - The type of the input item. Always `input_image`. +- `--description: optional string` - - `detail: optional "low" or "high" or "auto" or "original"` + The description of the assistant. The maximum length is 512 characters. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +- `--instructions: optional string` - - `file_id: optional string` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The ID of the file to be sent to the model. +- `--metadata: optional map[string]` - - `image_url: optional string` + 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. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `prompt_cache_breakpoint: optional object { mode }` +- `--name: optional string` - 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. + The name of the assistant. The maximum length is 256 characters. - - `encrypted_content: object { encrypted_content, type }` +- `--reasoning-effort: optional "none" or "minimal" or "low" or 4 more` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `encrypted_content: string` +- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - Opaque encrypted content. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `type: "encrypted_content"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The type of the input item. Always `encrypted_content`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `recipient: string` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The destination agent identity. +- `--temperature: optional number` - - `type: "agent_message"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - The item type. Always `agent_message`. +- `--tool-resources: optional object { code_interpreter, file_search }` - - `id: optional string` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The unique ID of this agent message item. +- `--tool: optional array of AssistantTool` - - `agent: optional object { agent_name }` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - The agent that produced this item. +- `--top-p: optional number` - - `agent_name: string` + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - The canonical name of the agent that produced this item. + We generally recommend altering this or temperature but not both. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` +### Returns - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` +- `assistant: object { id, created_at, description, 10 more }` - The multi-agent action that was executed. + Represents an `assistant` that can call the model and use tools. - - `"spawn_agent"` + - `id: string` - - `"interrupt_agent"` + The identifier, which can be referenced in API endpoints. - - `"list_agents"` + - `created_at: number` - - `"send_message"` + The Unix timestamp (in seconds) for when the assistant was created. - - `"followup_task"` + - `description: string` - - `"wait_agent"` + The description of the assistant. The maximum length is 512 characters. - - `arguments: string` + - `instructions: string` - The action arguments as a JSON string. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `call_id: string` + - `metadata: map[string]` - The unique ID linking this call to its output. + 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. - - `type: "multi_agent_call"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The item type. Always `multi_agent_call`. + - `model: string` - - `id: optional string` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - The unique ID of this multi-agent call. + - `name: string` - - `agent: optional object { agent_name }` + The name of the assistant. The maximum length is 256 characters. - The agent that produced this item. + - `object: "assistant"` - - `agent_name: string` + The object type, which is always `assistant`. - The canonical name of the agent that produced this item. + - `tools: array of AssistantTool` - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `code_interpreter_tool: object { type }` - The multi-agent action that produced this result. + - `type: "code_interpreter"` - - `"spawn_agent"` + The type of tool being defined: `code_interpreter` - - `"interrupt_agent"` + - `file_search_tool: object { type, file_search }` - - `"list_agents"` + - `type: "file_search"` - - `"send_message"` + The type of tool being defined: `file_search` - - `"followup_task"` + - `file_search: optional object { max_num_results, ranking_options }` - - `"wait_agent"` + Overrides for the file search tool. - - `call_id: string` + - `max_num_results: optional number` - The unique ID of the multi-agent call. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `output: array of object { text, type, annotations }` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Text output returned by the multi-agent action. + - `ranking_options: optional object { score_threshold, ranker }` - - `text: string` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The text content. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "output_text"` + - `score_threshold: number` - The content type. Always `output_text`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `annotations: optional array of object { file_id, filename, index, type } or array of object { end_index, start_index, title, 2 more } or array of object { container_id, end_index, file_id, 3 more }` + - `ranker: optional "auto" or "default_2024_08_21"` - Citations associated with the text content. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `union_member_0: array of object { file_id, filename, index, type }` + - `"auto"` - - `file_id: string` + - `"default_2024_08_21"` - The ID of the file. + - `function_tool: object { function, type }` - - `filename: string` + - `function: object { name, description, parameters, strict }` - The filename of the file cited. + - `name: string` - - `index: number` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The index of the file in the list of files. + - `description: optional string` - - `type: "file_citation"` + A description of what the function does, used by the model to choose when and how to call the function. - The citation type. Always `file_citation`. + - `parameters: optional map[unknown]` - - `union_member_1: array of object { end_index, start_index, title, 2 more }` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `end_index: number` + Omitting `parameters` defines a function with an empty parameter list. - The index of the last character of the citation in the message. + - `strict: optional boolean` - - `start_index: number` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The index of the first character of the citation in the message. + - `type: "function"` - - `title: string` + The type of tool being defined: `function` - The title of the cited resource. + - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `type: "url_citation"` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The citation type. Always `url_citation`. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `url: string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The URL of the cited resource. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `union_member_2: array of object { container_id, end_index, file_id, 3 more }` + - `union_member_0: "auto"` - - `container_id: string` + `auto` is the default value - The ID of the container. + - `response_format_text: object { type }` - - `end_index: number` + Default response format. Used to generate text responses. - The index of the last character of the citation in the message. + - `type: "text"` - - `file_id: string` + The type of response format being defined. Always `text`. - The ID of the container file. + - `response_format_json_object: object { type }` - - `filename: string` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The filename of the container file cited. + - `type: "json_object"` - - `start_index: number` + The type of response format being defined. Always `json_object`. - The index of the first character of the citation in the message. + - `response_format_json_schema: object { json_schema, type }` - - `type: "container_file_citation"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The citation type. Always `container_file_citation`. + - `json_schema: object { name, description, schema, strict }` - - `type: "multi_agent_call_output"` + Structured Outputs configuration options, including a JSON Schema. - The item type. Always `multi_agent_call_output`. + - `name: string` - - `id: optional string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The unique ID of this multi-agent call output. + - `description: optional string` - - `agent: optional object { agent_name }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The agent that produced this item. + - `schema: optional map[unknown]` - - `agent_name: string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The canonical name of the agent that produced this item. + - `strict: optional boolean` - - `tool_search_call: object { arguments, type, id, 4 more }` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `arguments: unknown` + - `type: "json_schema"` - The arguments supplied to the tool search call. + The type of response format being defined. Always `json_schema`. - - `type: "tool_search_call"` + - `temperature: optional number` - The item type. Always `tool_search_call`. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `id: optional string` + - `tool_resources: optional object { code_interpreter, file_search }` - The unique ID of this tool search call. + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `agent: optional object { agent_name }` + - `code_interpreter: optional object { file_ids }` - The agent that produced this item. + - `file_ids: optional array of string` - - `agent_name: string` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - The canonical name of the agent that produced this item. + - `file_search: optional object { vector_store_ids }` - - `call_id: optional string` + - `vector_store_ids: optional array of string` - The unique ID of the tool search call generated by the model. + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `execution: optional "server" or "client"` + - `top_p: optional number` - Whether tool search was executed by the server or by the client. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `"server"` + We generally recommend altering this or temperature but not both. - - `"client"` +### Example - - `status: optional "in_progress" or "completed" or "incomplete"` +```cli +openai beta:assistants create \ + --api-key 'My API Key' \ + --model gpt-4o +``` - The status of the tool search call. +#### Response - - `"in_progress"` +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - - `"completed"` +## Retrieve assistant - - `"incomplete"` +`$ openai beta:assistants retrieve` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` +**get** `/assistants/{assistant_id}` - - `tools: array of BetaTool` +Retrieves an assistant. - The loaded tool definitions returned by the tool search output. +### Parameters - - `beta_function_tool: object { name, parameters, strict, 5 more }` +- `--assistant-id: string` - 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). + The ID of the assistant to retrieve. - - `name: string` +### Returns - The name of the function to call. +- `assistant: object { id, created_at, description, 10 more }` - - `parameters: map[unknown]` + Represents an `assistant` that can call the model and use tools. - A JSON schema object describing the parameters of the function. + - `id: string` - - `strict: boolean` + The identifier, which can be referenced in API endpoints. - Whether strict parameter validation is enforced for this function tool. + - `created_at: number` - - `type: "function"` + The Unix timestamp (in seconds) for when the assistant was created. - The type of the function tool. Always `function`. + - `description: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The description of the assistant. The maximum length is 512 characters. - The tool invocation context(s). + - `instructions: string` - - `"direct"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `"programmatic"` + - `metadata: map[string]` - - `defer_loading: optional boolean` + 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. - Whether this function is deferred and loaded via tool search. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `description: optional string` + - `model: string` - A description of the function. Used by the model to determine whether or not to call the function. + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - `output_schema: optional map[unknown]` + - `name: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The name of the assistant. The maximum length is 256 characters. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `object: "assistant"` - 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). + The object type, which is always `assistant`. - - `type: "file_search"` + - `tools: array of AssistantTool` - The type of the file search tool. Always `file_search`. + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `vector_store_ids: array of string` + - `code_interpreter_tool: object { type }` - The IDs of the vector stores to search. + - `type: "code_interpreter"` - - `filters: optional object { key, type, value } or object { filters, type }` + The type of tool being defined: `code_interpreter` - A filter to apply. + - `file_search_tool: object { type, file_search }` - - `Comparison Filter: object { key, type, value }` + - `type: "file_search"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The type of tool being defined: `file_search` - - `key: string` + - `file_search: optional object { max_num_results, ranking_options }` - The key to compare against the value. + Overrides for the file search tool. - - `type: "eq" or "ne" or "gt" or 5 more` + - `max_num_results: optional number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `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 + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"eq"` + - `ranking_options: optional object { score_threshold, ranker }` - - `"ne"` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"gt"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"gte"` + - `score_threshold: number` - - `"lt"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"lte"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"in"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"nin"` + - `"auto"` - - `value: string or number or boolean or array of unknown` + - `"default_2024_08_21"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `function_tool: object { function, type }` - - `union_member_0: string` + - `function: object { name, description, parameters, strict }` - - `union_member_1: number` + - `name: string` - - `union_member_2: boolean` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `union_member_3: array of unknown` + - `description: optional string` - - `Compound Filter: object { filters, type }` + A description of what the function does, used by the model to choose when and how to call the function. - Combine multiple filters using `and` or `or`. + - `parameters: optional map[unknown]` - - `filters: array of object { key, type, value } or unknown` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Omitting `parameters` defines a function with an empty parameter list. - - `Comparison Filter: object { key, type, value }` + - `strict: optional boolean` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `key: string` + - `type: "function"` - The key to compare against the value. + The type of tool being defined: `function` - - `type: "eq" or "ne" or "gt" or 5 more` + - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `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 + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"eq"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"ne"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"gt"` + - `union_member_0: "auto"` - - `"gte"` + `auto` is the default value - - `"lt"` + - `response_format_text: object { type }` - - `"lte"` + Default response format. Used to generate text responses. - - `"in"` + - `type: "text"` - - `"nin"` + The type of response format being defined. Always `text`. - - `value: string or number or boolean or array of unknown` + - `response_format_json_object: object { type }` - The value to compare against the attribute key; supports string, number, or boolean types. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `union_member_0: string` + - `type: "json_object"` - - `union_member_1: number` + The type of response format being defined. Always `json_object`. - - `union_member_2: boolean` + - `response_format_json_schema: object { json_schema, type }` - - `union_member_3: array of unknown` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `union_member_1: unknown` + - `json_schema: object { name, description, schema, strict }` - - `type: "and" or "or"` + Structured Outputs configuration options, including a JSON Schema. - Type of operation: `and` or `or`. + - `name: string` - - `"and"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `"or"` + - `description: optional string` - - `max_num_results: optional number` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `schema: optional map[unknown]` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Ranking options for search. + - `strict: optional boolean` - - `hybrid_search: optional object { embedding_weight, text_weight }` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: "json_schema"` - - `embedding_weight: number` + The type of response format being defined. Always `json_schema`. - The weight of the embedding in the reciprocal ranking fusion. + - `temperature: optional number` - - `text_weight: number` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - The weight of the text in the reciprocal ranking fusion. + - `tool_resources: optional object { code_interpreter, file_search }` - - `ranker: optional "auto" or "default-2024-11-15"` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The ranker to use for the file search. + - `code_interpreter: optional object { file_ids }` - - `"auto"` + - `file_ids: optional array of string` - - `"default-2024-11-15"` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `score_threshold: optional number` + - `file_search: optional object { vector_store_ids }` - 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. + - `vector_store_ids: optional array of string` - - `beta_computer_tool: object { type }` + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `top_p: optional number` - - `type: "computer"` + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - The type of the computer tool. Always `computer`. + We generally recommend altering this or temperature but not both. - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` +### Example - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +```cli +openai beta:assistants retrieve \ + --api-key 'My API Key' \ + --assistant-id assistant_id +``` - - `display_height: number` +#### Response - The height of the computer display. +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - - `display_width: number` +## Modify assistant - The width of the computer display. +`$ openai beta:assistants update` - - `environment: "windows" or "mac" or "linux" or 2 more` +**post** `/assistants/{assistant_id}` - The type of computer environment to control. +Modifies an assistant. - - `"windows"` +### Parameters - - `"mac"` +- `--assistant-id: string` - - `"linux"` + The ID of the assistant to modify. - - `"ubuntu"` +- `--description: optional string` - - `"browser"` + The description of the assistant. The maximum length is 512 characters. - - `type: "computer_use_preview"` +- `--instructions: optional string` - The type of the computer use tool. Always `computer_use_preview`. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` +- `--metadata: optional map[string]` - 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). + 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. - - `type: "web_search" or "web_search_2025_08_26"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. +- `--model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `"web_search"` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - `"web_search_2025_08_26"` +- `--name: optional string` - - `filters: optional object { allowed_domains }` + The name of the assistant. The maximum length is 256 characters. - Filters for the search. +- `--reasoning-effort: optional "none" or "minimal" or "low" or 4 more` - - `allowed_domains: optional array of string` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. +- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `search_context_size: optional "low" or "medium" or "high"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - 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. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"low"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"medium"` +- `--temperature: optional number` - - `"high"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `user_location: optional object { city, country, region, 2 more }` +- `--tool-resources: optional object { code_interpreter, file_search }` - The approximate location of the user. + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `city: optional string` +- `--tool: optional array of AssistantTool` - Free text input for the city of the user, e.g. `San Francisco`. + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `country: optional string` +- `--top-p: optional number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `region: optional string` + We generally recommend altering this or temperature but not both. - Free text input for the region of the user, e.g. `California`. +### Returns - - `timezone: optional string` +- `assistant: object { id, created_at, description, 10 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Represents an `assistant` that can call the model and use tools. - - `type: optional "approximate"` + - `id: string` - The type of location approximation. Always `approximate`. + The identifier, which can be referenced in API endpoints. - - `"approximate"` + - `created_at: number` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The Unix timestamp (in seconds) for when the assistant was created. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `description: string` - - `server_label: string` + The description of the assistant. The maximum length is 512 characters. - A label for this MCP server, used to identify it in tool calls. + - `instructions: string` - - `type: "mcp"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The type of the MCP tool. Always `mcp`. + - `metadata: map[string]` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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. - The tool invocation context(s). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"direct"` + - `model: string` - - `"programmatic"` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `name: string` - List of allowed tool names or a filter object. + The name of the assistant. The maximum length is 256 characters. - - `MCP allowed tools: array of string` + - `object: "assistant"` - A string array of allowed tool names + The object type, which is always `assistant`. - - `MCP tool filter: object { read_only, tool_names }` + - `tools: array of AssistantTool` - A filter object to specify which tools are allowed. + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `read_only: optional boolean` + - `code_interpreter_tool: object { type }` - 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. + - `type: "code_interpreter"` - - `tool_names: optional array of string` + The type of tool being defined: `code_interpreter` - List of allowed tool names. + - `file_search_tool: object { type, file_search }` - - `authorization: optional string` + - `type: "file_search"` - 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. + The type of tool being defined: `file_search` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `file_search: optional object { max_num_results, ranking_options }` - 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). + Overrides for the file search tool. - Currently supported `connector_id` values are: + - `max_num_results: optional number` - - 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` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `"connector_dropbox"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"connector_gmail"` + - `ranking_options: optional object { score_threshold, ranker }` - - `"connector_googlecalendar"` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"connector_googledrive"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"connector_microsoftteams"` + - `score_threshold: number` - - `"connector_outlookcalendar"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"connector_outlookemail"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"connector_sharepoint"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `defer_loading: optional boolean` + - `"auto"` - Whether this MCP tool is deferred and discovered via tool search. + - `"default_2024_08_21"` - - `headers: optional map[string]` + - `function_tool: object { function, type }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `function: object { name, description, parameters, strict }` - - `require_approval: optional object { always, never } or "always" or "never"` + - `name: string` - Specify which of the MCP server's tools require approval. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `MCP tool approval filter: object { always, never }` + - `description: optional string` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + A description of what the function does, used by the model to choose when and how to call the function. - - `always: optional object { read_only, tool_names }` + - `parameters: optional map[unknown]` - A filter object to specify which tools are allowed. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `read_only: optional boolean` + Omitting `parameters` defines a function with an empty parameter list. - 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. + - `strict: optional boolean` - - `tool_names: optional array of string` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - List of allowed tool names. + - `type: "function"` - - `never: optional object { read_only, tool_names }` + The type of tool being defined: `function` - A filter object to specify which tools are allowed. + - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `read_only: optional boolean` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - 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. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `tool_names: optional array of string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - List of allowed tool names. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `MCP tool approval setting: "always" or "never"` + - `union_member_0: "auto"` - 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. + `auto` is the default value - - `"always"` + - `response_format_text: object { type }` - - `"never"` + Default response format. Used to generate text responses. - - `server_description: optional string` + - `type: "text"` - Optional description of the MCP server, used to provide more context. + The type of response format being defined. Always `text`. - - `server_url: optional string` + - `response_format_json_object: object { type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `tunnel_id: optional string` + - `type: "json_object"` - 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. + The type of response format being defined. Always `json_object`. - - `code_interpreter: object { container, type, allowed_callers }` + - `response_format_json_schema: object { json_schema, type }` - A tool that runs Python code to help generate a response to a prompt. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `json_schema: object { name, description, schema, strict }` - 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. + Structured Outputs configuration options, including a JSON Schema. - - `union_member_0: string` + - `name: string` - The container ID. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + - `description: optional string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "auto"` + - `schema: optional map[unknown]` - Always `auto`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `file_ids: optional array of string` + - `strict: optional boolean` - An optional list of uploaded files to make available to your code. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "json_schema"` - The memory limit for the code interpreter container. + The type of response format being defined. Always `json_schema`. - - `"1g"` + - `temperature: optional number` - - `"4g"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `"16g"` + - `tool_resources: optional object { code_interpreter, file_search }` - - `"64g"` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `code_interpreter: optional object { file_ids }` - Network access policy for the container. + - `file_ids: optional array of string` - - `beta_container_network_policy_disabled: object { type }` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `type: "disabled"` + - `file_search: optional object { vector_store_ids }` - Disable outbound network access. Always `disabled`. + - `vector_store_ids: optional array of string` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `allowed_domains: array of string` + - `top_p: optional number` - A list of allowed domains when type is `allowlist`. + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `type: "allowlist"` + We generally recommend altering this or temperature but not both. - Allow outbound network access only to specified domains. Always `allowlist`. +### Example - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` +```cli +openai beta:assistants update \ + --api-key 'My API Key' \ + --assistant-id assistant_id +``` - Optional domain-scoped secrets for allowlisted domains. +#### Response - - `domain: string` +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - The domain associated with the secret. +## Delete assistant - - `name: string` +`$ openai beta:assistants delete` - The name of the secret to inject for the domain. +**delete** `/assistants/{assistant_id}` - - `value: string` +Delete an assistant. - The secret value to inject for the domain. +### Parameters - - `type: "code_interpreter"` +- `--assistant-id: string` - The type of the code interpreter tool. Always `code_interpreter`. + The ID of the assistant to delete. - - `allowed_callers: optional array of "direct" or "programmatic"` +### Returns - The tool invocation context(s). +- `assistant_deleted: object { id, deleted, object }` - - `"direct"` + - `id: string` - - `"programmatic"` + - `deleted: boolean` - - `programmatic_tool_calling: object { type }` + - `object: "assistant.deleted"` - - `image_generation: object { type, action, background, 9 more }` +### Example - A tool that generates images using the GPT image models. +```cli +openai beta:assistants delete \ + --api-key 'My API Key' \ + --assistant-id assistant_id +``` - - `type: "image_generation"` +#### Response - The type of the image generation tool. Always `image_generation`. +```json +{ + "id": "id", + "deleted": true, + "object": "assistant.deleted" +} +``` - - `action: optional "generate" or "edit" or "auto"` +## Domain Types - Whether to generate a new image or edit an existing image. Default: `auto`. +### Assistant - - `"generate"` +- `assistant: object { id, created_at, description, 10 more }` - - `"edit"` + Represents an `assistant` that can call the model and use tools. - - `"auto"` + - `id: string` - - `background: optional "transparent" or "opaque" or "auto"` + The identifier, which can be referenced in API endpoints. - 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. + - `created_at: number` - `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. + The Unix timestamp (in seconds) for when the assistant was created. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `description: string` - - `"transparent"` + The description of the assistant. The maximum length is 512 characters. - - `"opaque"` + - `instructions: string` - - `"auto"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `input_fidelity: optional "high" or "low"` + - `metadata: map[string]` - 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`. + 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. - - `"high"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"low"` + - `model: string` - - `input_image_mask: optional object { file_id, image_url }` + ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `name: string` - - `file_id: optional string` + The name of the assistant. The maximum length is 256 characters. - File ID for the mask image. + - `object: "assistant"` - - `image_url: optional string` + The object type, which is always `assistant`. - Base64-encoded mask image. + - `tools: array of AssistantTool` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - The image generation model to use. Default: `gpt-image-1`. + - `code_interpreter_tool: object { type }` - - `"gpt-image-1"` + - `type: "code_interpreter"` - - `"gpt-image-1-mini"` + The type of tool being defined: `code_interpreter` - - `"gpt-image-2"` + - `file_search_tool: object { type, file_search }` - - `"gpt-image-2-2026-04-21"` + - `type: "file_search"` - - `"gpt-image-1.5"` + The type of tool being defined: `file_search` - - `"chatgpt-image-latest"` + - `file_search: optional object { max_num_results, ranking_options }` - - `moderation: optional "auto" or "low"` + Overrides for the file search tool. - Moderation level for the generated image. Default: `auto`. + - `max_num_results: optional number` - - `"auto"` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `"low"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `output_compression: optional number` + - `ranking_options: optional object { score_threshold, ranker }` - Compression level for the output image. Default: 100. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `output_format: optional "png" or "webp" or "jpeg"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `score_threshold: number` - - `"png"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"webp"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"jpeg"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `partial_images: optional number` + - `"auto"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"default_2024_08_21"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `function_tool: object { function, type }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `function: object { name, description, parameters, strict }` - - `"low"` + - `name: string` - - `"medium"` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `"high"` + - `description: optional string` - - `"auto"` + A description of what the function does, used by the model to choose when and how to call the function. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `parameters: optional map[unknown]` - 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`. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `"1024x1024"` + Omitting `parameters` defines a function with an empty parameter list. - - `"1024x1536"` + - `strict: optional boolean` - - `"1536x1024"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `"auto"` + - `type: "function"` - - `local_shell: object { type }` + The type of tool being defined: `function` - A tool that allows the model to execute shell commands in a local environment. + - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - A tool that allows the model to execute shell commands. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `type: "shell"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The type of the shell tool. Always `shell`. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `union_member_0: "auto"` - The tool invocation context(s). + `auto` is the default value - - `"direct"` + - `response_format_text: object { type }` - - `"programmatic"` + Default response format. Used to generate text responses. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `type: "text"` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + The type of response format being defined. Always `text`. - - `type: "container_auto"` + - `response_format_json_object: object { type }` - Automatically creates a container for this request + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `file_ids: optional array of string` + - `type: "json_object"` - An optional list of uploaded files to make available to your code. + The type of response format being defined. Always `json_object`. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `response_format_json_schema: object { json_schema, type }` - The memory limit for the container. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"1g"` + - `json_schema: object { name, description, schema, strict }` - - `"4g"` + Structured Outputs configuration options, including a JSON Schema. - - `"16g"` + - `name: string` - - `"64g"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `description: optional string` - Network access policy for the container. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `beta_container_network_policy_disabled: object { type }` + - `schema: optional map[unknown]` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `strict: optional boolean` - An optional list of skills referenced by id or inline data. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `beta_skill_reference: object { skill_id, type, version }` + - `type: "json_schema"` - - `skill_id: string` + The type of response format being defined. Always `json_schema`. - The ID of the referenced skill. + - `temperature: optional number` - - `type: "skill_reference"` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - References a skill created with the /v1/skills endpoint. + - `tool_resources: optional object { code_interpreter, file_search }` - - `version: optional string` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `code_interpreter: optional object { file_ids }` - - `beta_inline_skill: object { description, name, source, type }` + - `file_ids: optional array of string` - - `description: string` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - The description of the skill. + - `file_search: optional object { vector_store_ids }` - - `name: string` + - `vector_store_ids: optional array of string` - The name of the skill. + The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `source: object { data, media_type, type }` + - `top_p: optional number` - Inline skill payload + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `data: string` + We generally recommend altering this or temperature but not both. - Base64-encoded skill zip bundle. +### Assistant Deleted - - `media_type: "application/zip"` +- `assistant_deleted: object { id, deleted, object }` - The media type of the inline skill payload. Must be `application/zip`. + - `id: string` - - `type: "base64"` + - `deleted: boolean` - The type of the inline skill source. Must be `base64`. + - `object: "assistant.deleted"` - - `type: "inline"` +### Assistant Stream Event - Defines an inline skill for this request. +- `assistant_stream_event: object { data, event, enabled } or object { data, event } or object { data, event } or 21 more` - - `beta_local_environment: object { type, skills }` + Represents an event emitted when streaming a Run. - - `type: "local"` + Each event in a server-sent events stream has an `event` and `data` property: - Use a local computer environment. + ``` + event: thread.created + data: {"id": "thread_123", "object": "thread", ...} + ``` - - `skills: optional array of BetaLocalSkill` + We emit events whenever a new object is created, transitions to a new state, or is being + streamed in parts (deltas). For example, we emit `thread.run.created` when a new run + is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses + to create a message during a run, we emit a `thread.message.created event`, a + `thread.message.in_progress` event, many `thread.message.delta` events, and finally a + `thread.message.completed` event. - An optional list of skills. + We may add additional events over time, so we recommend handling unknown events gracefully + in your code. See the [Assistants API quickstart](https://platform.openai.com/docs/assistants/overview) to learn how to + integrate the Assistants API with streaming. - - `description: string` + - `thread.created: object { data, event, enabled }` - The description of the skill. + Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - - `name: string` + - `data: object { id, created_at, metadata, 2 more }` - The name of the skill. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `path: string` + - `id: string` - The path to the directory containing the skill. + The identifier, which can be referenced in API endpoints. - - `beta_container_reference: object { container_id, type }` + - `created_at: number` - - `container_id: string` + The Unix timestamp (in seconds) for when the thread was created. - The ID of the referenced container. + - `metadata: map[string]` - - `type: "container_reference"` + 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. - References a container created with the /v1/containers endpoint + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `object: "thread"` - 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) + The object type, which is always `thread`. - - `name: string` + - `tool_resources: object { code_interpreter, file_search }` - The name of the custom tool, used to identify it in tool calls. + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `type: "custom"` + - `code_interpreter: optional object { file_ids }` - The type of the custom tool. Always `custom`. + - `file_ids: optional array of string` - - `allowed_callers: optional array of "direct" or "programmatic"` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - The tool invocation context(s). + - `file_search: optional object { vector_store_ids }` - - `"direct"` + - `vector_store_ids: optional array of string` - - `"programmatic"` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `defer_loading: optional boolean` + - `event: "thread.created"` - Whether this tool should be deferred and discovered via tool search. + - `enabled: optional boolean` - - `description: optional string` + Whether to enable input audio transcription. - Optional description of the custom tool, used to provide more context. + - `thread.run.created: object { data, event }` - - `format: optional object { type } or object { definition, syntax, type }` + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - The input format for the custom tool. Default is unconstrained text. + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `text: object { type }` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - Unconstrained free-form text. + - `id: string` - - `grammar: object { definition, syntax, type }` + The identifier, which can be referenced in API endpoints. - A grammar defined by the user. + - `assistant_id: string` - - `definition: string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The grammar definition. + - `cancelled_at: number` - - `syntax: "lark" or "regex"` + The Unix timestamp (in seconds) for when the run was cancelled. - The syntax of the grammar definition. One of `lark` or `regex`. + - `completed_at: number` - - `"lark"` + The Unix timestamp (in seconds) for when the run was completed. - - `"regex"` + - `created_at: number` - - `type: "grammar"` + The Unix timestamp (in seconds) for when the run was created. - Grammar format. Always `grammar`. + - `expires_at: number` - - `beta_namespace_tool: object { description, name, tools, type }` + The Unix timestamp (in seconds) for when the run will expire. - Groups function/custom tools under a shared namespace. + - `failed_at: number` - - `description: string` + The Unix timestamp (in seconds) for when the run failed. - A description of the namespace shown to the model. + - `incomplete_details: object { reason }` - - `name: string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The namespace name used in tool calls (for example, `crm`). + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The function/custom tools available inside this namespace. + - `"max_completion_tokens"` - - `function: object { name, type, allowed_callers, 5 more }` + - `"max_prompt_tokens"` - - `name: string` + - `instructions: string` - - `type: "function"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `last_error: object { code, message }` - The tool invocation context(s). + The last error associated with this run. Will be `null` if there are no errors. - - `"direct"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `"programmatic"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `defer_loading: optional boolean` + - `"server_error"` - Whether this function should be deferred and discovered via tool search. + - `"rate_limit_exceeded"` - - `description: optional string` + - `"invalid_prompt"` - - `output_schema: optional map[unknown]` + - `message: string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A human-readable description of the error. - - `parameters: optional unknown` + - `max_completion_tokens: number` - - `strict: optional boolean` + The maximum number of completion tokens specified to have been used over the course of the run. - 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. + - `max_prompt_tokens: number` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The maximum number of prompt tokens specified to have been used over the course of the run. - 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) + - `metadata: map[string]` - - `name: string` + 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. - The name of the custom tool, used to identify it in tool calls. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "custom"` + - `model: string` - The type of the custom tool. Always `custom`. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `object: "thread.run"` - The tool invocation context(s). + The object type, which is always `thread.run`. - - `defer_loading: optional boolean` + - `parallel_tool_calls: boolean` - Whether this tool should be deferred and discovered via tool search. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `description: optional string` + - `required_action: object { submit_tool_outputs, type }` - Optional description of the custom tool, used to provide more context. + Details on the action required to continue the run. Will be `null` if no action is required. - - `format: optional object { type } or object { definition, syntax, type }` + - `submit_tool_outputs: object { tool_calls }` - The input format for the custom tool. Default is unconstrained text. + Details on the tool outputs needed for this run to continue. - - `type: "namespace"` + - `tool_calls: array of RequiredActionFunctionToolCall` - The type of the tool. Always `namespace`. + A list of the relevant tool calls. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `id: string` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `type: "tool_search"` + - `function: object { arguments, name }` - The type of the tool. Always `tool_search`. + The function definition. - - `description: optional string` + - `arguments: string` - Description shown to the model for a client-executed tool search tool. + The arguments that the model expects you to pass to the function. - - `execution: optional "server" or "client"` + - `name: string` - Whether tool search is executed by the server or by the client. + The name of the function. - - `"server"` + - `type: "function"` - - `"client"` + The type of tool call the output is required for. For now, this is always `function`. - - `parameters: optional unknown` + - `type: "submit_tool_outputs"` - Parameter schema for a client-executed tool search tool. + For now, this is always `submit_tool_outputs`. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - 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). + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"web_search_preview"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"web_search_preview_2025_03_11"` + - `union_member_0: "auto"` - - `search_content_types: optional array of "text" or "image"` + `auto` is the default value - - `"text"` + - `response_format_text: object { type }` - - `"image"` + Default response format. Used to generate text responses. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "text"` - 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. + The type of response format being defined. Always `text`. - - `"low"` + - `response_format_json_object: object { type }` - - `"medium"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `"high"` + - `type: "json_object"` - - `user_location: optional object { type, city, country, 2 more }` + The type of response format being defined. Always `json_object`. - The user's location. + - `response_format_json_schema: object { json_schema, type }` - - `type: "approximate"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The type of location approximation. Always `approximate`. + - `json_schema: object { name, description, schema, strict }` - - `city: optional string` + Structured Outputs configuration options, including a JSON Schema. - Free text input for the city of the user, e.g. `San Francisco`. + - `name: string` - - `country: optional string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `description: optional string` - - `region: optional string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Free text input for the region of the user, e.g. `California`. + - `schema: optional map[unknown]` - - `timezone: optional string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `strict: optional boolean` - - `beta_apply_patch_tool: object { type, allowed_callers }` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "json_schema"` - - `type: "apply_patch"` + The type of response format being defined. Always `json_schema`. - The type of the tool. Always `apply_patch`. + - `started_at: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The Unix timestamp (in seconds) for when the run was started. - The tool invocation context(s). + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `"direct"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `"programmatic"` + - `"queued"` - - `type: "tool_search_output"` + - `"in_progress"` - The item type. Always `tool_search_output`. + - `"requires_action"` - - `id: optional string` + - `"cancelling"` - The unique ID of this tool search output. + - `"cancelled"` - - `agent: optional object { agent_name }` + - `"failed"` - The agent that produced this item. + - `"completed"` - - `agent_name: string` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `"expired"` - - `call_id: optional string` + - `thread_id: string` - The unique ID of the tool search call generated by the model. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `execution: optional "server" or "client"` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - Whether tool search was executed by the server or by the client. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `"server"` + - `Auto: "none" or "auto" or "required"` - - `"client"` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"none"` - The status of the tool search output. + - `"auto"` - - `"in_progress"` + - `"required"` - - `"completed"` + - `assistant_tool_choice: object { type, function }` - - `"incomplete"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `additional_tools: object { role, tools, type, 2 more }` + - `type: "function" or "code_interpreter" or "file_search"` - - `role: "developer"` + The type of the tool. If type is `function`, the function name must be set - The role that provided the additional tools. Only `developer` is supported. + - `"function"` - - `tools: array of BetaTool` + - `"code_interpreter"` - A list of additional tools made available at this item. + - `"file_search"` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `function: optional object { name }` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `name: string` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The name of the function to call. - 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). + - `tools: array of AssistantTool` - - `beta_computer_tool: object { type }` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `code_interpreter_tool: object { type }` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `type: "code_interpreter"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of tool being defined: `code_interpreter` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `file_search_tool: object { type, file_search }` - 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: "file_search"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The type of tool being defined: `file_search` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `file_search: optional object { max_num_results, ranking_options }` - - `code_interpreter: object { container, type, allowed_callers }` + Overrides for the file search tool. - A tool that runs Python code to help generate a response to a prompt. + - `max_num_results: optional number` - - `programmatic_tool_calling: object { type }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `image_generation: object { type, action, background, 9 more }` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - A tool that generates images using the GPT image models. + - `ranking_options: optional object { score_threshold, ranker }` - - `local_shell: object { type }` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - A tool that allows the model to execute shell commands in a local environment. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `score_threshold: number` - A tool that allows the model to execute shell commands. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `ranker: optional "auto" or "default_2024_08_21"` - 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) + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `beta_namespace_tool: object { description, name, tools, type }` + - `"auto"` - Groups function/custom tools under a shared namespace. + - `"default_2024_08_21"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `function_tool: object { function, type }` - Hosted or BYOT tool search configuration for deferred tools. + - `function: object { name, description, parameters, strict }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `name: string` - 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). + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `description: optional string` - Allows the assistant to create, delete, or update files using unified diffs. + A description of what the function does, used by the model to choose when and how to call the function. - - `type: "additional_tools"` + - `parameters: optional map[unknown]` - The item type. Always `additional_tools`. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `id: optional string` + Omitting `parameters` defines a function with an empty parameter list. - The unique ID of this additional tools item. + - `strict: optional boolean` - - `agent: optional object { agent_name }` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The agent that produced this item. + - `type: "function"` - - `agent_name: string` + The type of tool being defined: `function` - The canonical name of the agent that produced this item. + - `truncation_strategy: object { type, last_messages }` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - 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). + - `type: "auto" or "last_messages"` - - `id: string` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The unique identifier of the reasoning content. + - `"auto"` - - `summary: array of object { text, type }` + - `"last_messages"` - Reasoning summary content. + - `last_messages: optional number` - - `text: string` + The number of most recent messages from the thread when constructing the context for the run. - A summary of the reasoning output from the model so far. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "summary_text"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The type of the object. Always `summary_text`. + - `completion_tokens: number` - - `type: "reasoning"` + Number of completion tokens used over the course of the run. - The type of the object. Always `reasoning`. + - `prompt_tokens: number` - - `agent: optional object { agent_name }` + Number of prompt tokens used over the course of the run. - The agent that produced this item. + - `total_tokens: number` - - `agent_name: string` + Total number of tokens used (prompt + completion). - The canonical name of the agent that produced this item. + - `temperature: optional number` - - `content: optional array of object { text, type }` + The sampling temperature used for this run. If not set, defaults to 1. - Reasoning text content. + - `top_p: optional number` - - `text: string` + The nucleus sampling value used for this run. If not set, defaults to 1. - The reasoning text from the model. + - `event: "thread.run.created"` - - `type: "reasoning_text"` + - `thread.run.queued: object { data, event }` - The type of the reasoning text. Always `reasoning_text`. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - - `encrypted_content: optional string` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `status: optional "in_progress" or "completed" or "incomplete"` + - `id: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The identifier, which can be referenced in API endpoints. - - `"in_progress"` + - `assistant_id: string` - - `"completed"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `"incomplete"` + - `cancelled_at: number` - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + The Unix timestamp (in seconds) for when the run was cancelled. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `completed_at: number` - - `encrypted_content: string` + The Unix timestamp (in seconds) for when the run was completed. - The encrypted content of the compaction summary. + - `created_at: number` - - `type: "compaction"` + The Unix timestamp (in seconds) for when the run was created. - The type of the item. Always `compaction`. + - `expires_at: number` - - `id: optional string` + The Unix timestamp (in seconds) for when the run will expire. - The ID of the compaction item. + - `failed_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run failed. - The agent that produced this item. + - `incomplete_details: object { reason }` - - `agent_name: string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The canonical name of the agent that produced this item. + - `instructions: string` - - `image_generation_call: object { id, result, status, 2 more }` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - An image generation request made by the model. + - `last_error: object { code, message }` - - `id: string` + The last error associated with this run. Will be `null` if there are no errors. - The unique ID of the image generation call. + - `max_completion_tokens: number` - - `result: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The generated image encoded in base64. + - `max_prompt_tokens: number` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The maximum number of prompt tokens specified to have been used over the course of the run. - The status of the image generation call. + - `metadata: map[string]` - - `"in_progress"` + 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. - - `"completed"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"generating"` + - `model: string` - - `"failed"` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: "image_generation_call"` + - `object: "thread.run"` - The type of the image generation call. Always `image_generation_call`. + The object type, which is always `thread.run`. - - `agent: optional object { agent_name }` + - `parallel_tool_calls: boolean` - The agent that produced this item. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `agent_name: string` + - `required_action: object { submit_tool_outputs, type }` - The canonical name of the agent that produced this item. + Details on the action required to continue the run. Will be `null` if no action is required. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - A tool call to run code. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `id: string` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The unique ID of the code interpreter tool call. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `code: string` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The code to run, or null if not available. + - `started_at: number` - - `container_id: string` + The Unix timestamp (in seconds) for when the run was started. - The ID of the container used to run the code. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `outputs: array of object { logs, type } or object { type, url }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `thread_id: string` - - `logs: object { logs, type }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The logs output from the code interpreter. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `logs: string` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The logs output from the code interpreter. + - `tools: array of AssistantTool` - - `type: "logs"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the output. Always `logs`. + - `truncation_strategy: object { type, last_messages }` - - `image: object { type, url }` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The image output from the code interpreter. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "image"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The type of the output. Always `image`. + - `temperature: optional number` - - `url: string` + The sampling temperature used for this run. If not set, defaults to 1. - The URL of the image output from the code interpreter. + - `top_p: optional number` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The nucleus sampling value used for this run. If not set, defaults to 1. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `event: "thread.run.queued"` - - `"in_progress"` + - `thread.run.in_progress: object { data, event }` - - `"completed"` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - - `"incomplete"` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `"interpreting"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"failed"` + - `id: string` - - `type: "code_interpreter_call"` + The identifier, which can be referenced in API endpoints. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `assistant_id: string` - - `agent: optional object { agent_name }` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The agent that produced this item. + - `cancelled_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the run was cancelled. - The canonical name of the agent that produced this item. + - `completed_at: number` - - `local_shell_call: object { id, action, call_id, 3 more }` + The Unix timestamp (in seconds) for when the run was completed. - A tool call to run a command on the local shell. + - `created_at: number` - - `id: string` + The Unix timestamp (in seconds) for when the run was created. - The unique ID of the local shell call. + - `expires_at: number` - - `action: object { command, env, type, 3 more }` + The Unix timestamp (in seconds) for when the run will expire. - Execute a shell command on the server. + - `failed_at: number` - - `command: array of string` + The Unix timestamp (in seconds) for when the run failed. - The command to run. + - `incomplete_details: object { reason }` - - `env: map[string]` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - Environment variables to set for the command. + - `instructions: string` - - `type: "exec"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the local shell action. Always `exec`. + - `last_error: object { code, message }` - - `timeout_ms: optional number` + The last error associated with this run. Will be `null` if there are no errors. - Optional timeout in milliseconds for the command. + - `max_completion_tokens: number` - - `user: optional string` + The maximum number of completion tokens specified to have been used over the course of the run. - Optional user to run the command as. + - `max_prompt_tokens: number` - - `working_directory: optional string` + The maximum number of prompt tokens specified to have been used over the course of the run. - Optional working directory to run the command in. + - `metadata: map[string]` - - `call_id: string` + 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. - The unique ID of the local shell tool call generated by the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `status: "in_progress" or "completed" or "incomplete"` + - `model: string` - The status of the local shell call. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"in_progress"` + - `object: "thread.run"` - - `"completed"` + The object type, which is always `thread.run`. - - `"incomplete"` + - `parallel_tool_calls: boolean` - - `type: "local_shell_call"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The type of the local shell call. Always `local_shell_call`. + - `required_action: object { submit_tool_outputs, type }` - - `agent: optional object { agent_name }` + Details on the action required to continue the run. Will be `null` if no action is required. - The agent that produced this item. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `agent_name: string` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The canonical name of the agent that produced this item. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `local_shell_call_output: object { id, output, type, 2 more }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The output of a local shell tool call. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `id: string` + - `started_at: number` - The unique ID of the local shell tool call generated by the model. + The Unix timestamp (in seconds) for when the run was started. - - `output: string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - A JSON string of the output of the local shell tool call. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `type: "local_shell_call_output"` + - `thread_id: string` - The type of the local shell tool call output. Always `local_shell_call_output`. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `agent: optional object { agent_name }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - The agent that produced this item. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `agent_name: string` + - `tools: array of AssistantTool` - The canonical name of the agent that produced this item. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `truncation_strategy: object { type, last_messages }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"in_progress"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"completed"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `"incomplete"` + - `temperature: optional number` - - `shell_call: object { action, call_id, type, 5 more }` + The sampling temperature used for this run. If not set, defaults to 1. - A tool representing a request to execute one or more shell commands. + - `top_p: optional number` - - `action: object { commands, max_output_length, timeout_ms }` + The nucleus sampling value used for this run. If not set, defaults to 1. - The shell commands and limits that describe how to run the tool call. + - `event: "thread.run.in_progress"` - - `commands: array of string` + - `thread.run.requires_action: object { data, event }` - Ordered shell commands for the execution environment to run. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - `max_output_length: optional number` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `timeout_ms: optional number` + - `id: string` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The identifier, which can be referenced in API endpoints. - - `call_id: string` + - `assistant_id: string` - The unique ID of the shell tool call generated by the model. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `type: "shell_call"` + - `cancelled_at: number` - The type of the item. Always `shell_call`. + The Unix timestamp (in seconds) for when the run was cancelled. - - `id: optional string` + - `completed_at: number` - The unique ID of the shell tool call. Populated when this item is returned via API. + The Unix timestamp (in seconds) for when the run was completed. - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run was created. - - `agent_name: string` + - `expires_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run will expire. - - `caller: optional object { type } or object { caller_id, type }` + - `failed_at: number` - The execution context that produced this tool call. + The Unix timestamp (in seconds) for when the run failed. - - `direct: object { type }` + - `incomplete_details: object { reason }` - - `program: object { caller_id, type }` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `caller_id: string` + - `instructions: string` - The call ID of the program item that produced this tool call. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: "program"` + - `last_error: object { code, message }` - The caller type. Always `program`. + The last error associated with this run. Will be `null` if there are no errors. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `max_completion_tokens: number` - The environment to execute the shell commands in. + The maximum number of completion tokens specified to have been used over the course of the run. - - `beta_local_environment: object { type, skills }` + - `max_prompt_tokens: number` - - `beta_container_reference: object { container_id, type }` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `metadata: map[string]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + 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. - - `"in_progress"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"completed"` + - `model: string` - - `"incomplete"` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `object: "thread.run"` - The streamed output items emitted by a shell tool call. + The object type, which is always `thread.run`. - - `call_id: string` + - `parallel_tool_calls: boolean` - The unique ID of the shell tool call generated by the model. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `required_action: object { submit_tool_outputs, type }` - Captured chunks of stdout and stderr output, along with their associated outcomes. + Details on the action required to continue the run. Will be `null` if no action is required. - - `outcome: object { type } or object { exit_code, type }` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The exit or timeout outcome associated with this shell call. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `timeout: object { type }` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - Indicates that the shell call exceeded its configured time limit. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `exit: object { exit_code, type }` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - Indicates that the shell commands finished and returned an exit code. + - `started_at: number` - - `exit_code: number` + The Unix timestamp (in seconds) for when the run was started. - The exit code returned by the shell process. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `type: "exit"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The outcome type. Always `exit`. + - `thread_id: string` - - `stderr: string` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - Captured stderr output for the shell call. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `stdout: string` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - Captured stdout output for the shell call. + - `tools: array of AssistantTool` - - `type: "shell_call_output"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the item. Always `shell_call_output`. + - `truncation_strategy: object { type, last_messages }` - - `id: optional string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `agent: optional object { agent_name }` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The agent that produced this item. + - `temperature: optional number` - - `agent_name: string` + The sampling temperature used for this run. If not set, defaults to 1. - The canonical name of the agent that produced this item. + - `top_p: optional number` - - `caller: optional object { type } or object { caller_id, type }` + The nucleus sampling value used for this run. If not set, defaults to 1. - The execution context that produced this tool call. + - `event: "thread.run.requires_action"` - - `direct: object { type }` + - `thread.run.completed: object { data, event }` - - `program: object { caller_id, type }` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - - `caller_id: string` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - The call ID of the program item that produced this tool call. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: "program"` + - `id: string` - The caller type. Always `program`. + The identifier, which can be referenced in API endpoints. - - `max_output_length: optional number` + - `assistant_id: string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `cancelled_at: number` - The status of the shell call output. + The Unix timestamp (in seconds) for when the run was cancelled. - - `"in_progress"` + - `completed_at: number` - - `"completed"` + The Unix timestamp (in seconds) for when the run was completed. - - `"incomplete"` + - `created_at: number` - - `apply_patch_call: object { call_id, operation, status, 4 more }` + The Unix timestamp (in seconds) for when the run was created. - A tool call representing a request to create, delete, or update files using diff patches. + - `expires_at: number` - - `call_id: string` + The Unix timestamp (in seconds) for when the run will expire. - The unique ID of the apply patch tool call generated by the model. + - `failed_at: number` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The Unix timestamp (in seconds) for when the run failed. - The specific create, delete, or update instruction for the apply_patch tool call. + - `incomplete_details: object { reason }` - - `create_file: object { diff, path, type }` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - Instruction for creating a new file via the apply_patch tool. + - `instructions: string` - - `diff: string` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Unified diff content to apply when creating the file. + - `last_error: object { code, message }` - - `path: string` + The last error associated with this run. Will be `null` if there are no errors. - Path of the file to create relative to the workspace root. + - `max_completion_tokens: number` - - `type: "create_file"` + The maximum number of completion tokens specified to have been used over the course of the run. - The operation type. Always `create_file`. + - `max_prompt_tokens: number` - - `delete_file: object { path, type }` + The maximum number of prompt tokens specified to have been used over the course of the run. - Instruction for deleting an existing file via the apply_patch tool. + - `metadata: map[string]` - - `path: string` + 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. - Path of the file to delete relative to the workspace root. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "delete_file"` + - `model: string` - The operation type. Always `delete_file`. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `update_file: object { diff, path, type }` + - `object: "thread.run"` - Instruction for updating an existing file via the apply_patch tool. + The object type, which is always `thread.run`. - - `diff: string` + - `parallel_tool_calls: boolean` - Unified diff content to apply to the existing file. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `path: string` + - `required_action: object { submit_tool_outputs, type }` - Path of the file to update relative to the workspace root. + Details on the action required to continue the run. Will be `null` if no action is required. - - `type: "update_file"` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The operation type. Always `update_file`. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `status: "in_progress" or "completed"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The status of the apply patch tool call. One of `in_progress` or `completed`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"in_progress"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"completed"` + - `started_at: number` - - `type: "apply_patch_call"` + The Unix timestamp (in seconds) for when the run was started. - The type of the item. Always `apply_patch_call`. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `id: optional string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `thread_id: string` - - `agent: optional object { agent_name }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The agent that produced this item. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `agent_name: string` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The canonical name of the agent that produced this item. + - `tools: array of AssistantTool` - - `caller: optional object { type } or object { caller_id, type }` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The execution context that produced this tool call. + - `truncation_strategy: object { type, last_messages }` - - `direct: object { type }` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `program: object { caller_id, type }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `caller_id: string` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The call ID of the program item that produced this tool call. + - `temperature: optional number` - - `type: "program"` + The sampling temperature used for this run. If not set, defaults to 1. - The caller type. Always `program`. + - `top_p: optional number` - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + The nucleus sampling value used for this run. If not set, defaults to 1. - The streamed output emitted by an apply patch tool call. + - `event: "thread.run.completed"` - - `call_id: string` + - `thread.run.incomplete: object { data, event }` - The unique ID of the apply patch tool call generated by the model. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - - `status: "completed" or "failed"` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - The status of the apply patch tool call output. One of `completed` or `failed`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"completed"` + - `id: string` - - `"failed"` + The identifier, which can be referenced in API endpoints. - - `type: "apply_patch_call_output"` + - `assistant_id: string` - The type of the item. Always `apply_patch_call_output`. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `id: optional string` + - `cancelled_at: number` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The Unix timestamp (in seconds) for when the run was cancelled. - - `agent: optional object { agent_name }` + - `completed_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run was completed. - - `agent_name: string` + - `created_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run was created. - - `caller: optional object { type } or object { caller_id, type }` + - `expires_at: number` - The execution context that produced this tool call. + The Unix timestamp (in seconds) for when the run will expire. - - `direct: object { type }` + - `failed_at: number` - - `program: object { caller_id, type }` + The Unix timestamp (in seconds) for when the run failed. - - `caller_id: string` + - `incomplete_details: object { reason }` - The call ID of the program item that produced this tool call. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `type: "program"` + - `instructions: string` - The caller type. Always `program`. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `output: optional string` + - `last_error: object { code, message }` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The last error associated with this run. Will be `null` if there are no errors. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `max_completion_tokens: number` - A list of tools available on an MCP server. + The maximum number of completion tokens specified to have been used over the course of the run. - - `id: string` + - `max_prompt_tokens: number` - The unique ID of the list. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `server_label: string` + - `metadata: map[string]` - The label of the MCP server. + 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. - - `tools: array of object { input_schema, name, annotations, description }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The tools available on the server. + - `model: string` - - `input_schema: unknown` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The JSON schema describing the tool's input. + - `object: "thread.run"` - - `name: string` + The object type, which is always `thread.run`. - The name of the tool. + - `parallel_tool_calls: boolean` - - `annotations: optional unknown` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - Additional annotations about the tool. + - `required_action: object { submit_tool_outputs, type }` - - `description: optional string` + Details on the action required to continue the run. Will be `null` if no action is required. - The description of the tool. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `type: "mcp_list_tools"` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The type of the item. Always `mcp_list_tools`. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `agent: optional object { agent_name }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The agent that produced this item. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `agent_name: string` + - `started_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run was started. - - `error: optional string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - Error message if the server could not list tools. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `thread_id: string` - A request for human approval of a tool invocation. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `id: string` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - The unique ID of the approval request. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `arguments: string` + - `tools: array of AssistantTool` - A JSON string of arguments for the tool. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `name: string` + - `truncation_strategy: object { type, last_messages }` - The name of the tool to run. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `server_label: string` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The label of the MCP server making the request. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `type: "mcp_approval_request"` + - `temperature: optional number` - The type of the item. Always `mcp_approval_request`. + The sampling temperature used for this run. If not set, defaults to 1. - - `agent: optional object { agent_name }` + - `top_p: optional number` - The agent that produced this item. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `agent_name: string` + - `event: "thread.run.incomplete"` - The canonical name of the agent that produced this item. + - `thread.run.failed: object { data, event }` - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - A response to an MCP approval request. + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `approval_request_id: string` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The ID of the approval request being answered. + - `id: string` - - `approve: boolean` + The identifier, which can be referenced in API endpoints. - Whether the request was approved. + - `assistant_id: string` - - `type: "mcp_approval_response"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The type of the item. Always `mcp_approval_response`. + - `cancelled_at: number` - - `id: optional string` + The Unix timestamp (in seconds) for when the run was cancelled. - The unique ID of the approval response + - `completed_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run was completed. - The agent that produced this item. + - `created_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the run was created. - The canonical name of the agent that produced this item. + - `expires_at: number` - - `reason: optional string` + The Unix timestamp (in seconds) for when the run will expire. - Optional reason for the decision. + - `failed_at: number` - - `mcp_call: object { id, arguments, name, 7 more }` + The Unix timestamp (in seconds) for when the run failed. - An invocation of a tool on an MCP server. + - `incomplete_details: object { reason }` - - `id: string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The unique ID of the tool call. + - `instructions: string` - - `arguments: string` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - A JSON string of the arguments passed to the tool. + - `last_error: object { code, message }` - - `name: string` + The last error associated with this run. Will be `null` if there are no errors. - The name of the tool that was run. + - `max_completion_tokens: number` - - `server_label: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The label of the MCP server running the tool. + - `max_prompt_tokens: number` - - `type: "mcp_call"` + The maximum number of prompt tokens specified to have been used over the course of the run. - The type of the item. Always `mcp_call`. + - `metadata: map[string]` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `agent_name: string` + - `model: string` - The canonical name of the agent that produced this item. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `approval_request_id: optional string` + - `object: "thread.run"` - 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. + The object type, which is always `thread.run`. - - `error: optional string` + - `parallel_tool_calls: boolean` - The error from the tool call, if any. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `output: optional string` + - `required_action: object { submit_tool_outputs, type }` - The output from the tool call. + Details on the action required to continue the run. Will be `null` if no action is required. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `"in_progress"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"completed"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"incomplete"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"calling"` + - `started_at: number` - - `"failed"` + The Unix timestamp (in seconds) for when the run was started. - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The output of a custom tool call from your code, being sent back to the model. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `call_id: string` + - `thread_id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `string output: string` + - `tools: array of AssistantTool` - A string of the output of the custom tool call. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `truncation_strategy: object { type, last_messages }` - Text, image, or file output of the custom tool call. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - A text input to the model. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `text: string` + - `temperature: optional number` - The text input to the model. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: "input_text"` + - `top_p: optional number` - The type of the input item. Always `input_text`. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `prompt_cache_breakpoint: optional object { mode }` + - `event: "thread.run.failed"` - 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. + - `thread.run.cancelling: object { data, event }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `detail: "low" or "high" or "auto" or "original"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `id: string` - - `type: "input_image"` + The identifier, which can be referenced in API endpoints. - The type of the input item. Always `input_image`. + - `assistant_id: string` - - `file_id: optional string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The ID of the file to be sent to the model. + - `cancelled_at: number` - - `image_url: optional string` + The Unix timestamp (in seconds) for when the run was cancelled. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `completed_at: number` - - `prompt_cache_breakpoint: optional object { mode }` + The Unix timestamp (in seconds) for when the run was completed. - 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. + - `created_at: number` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The Unix timestamp (in seconds) for when the run was created. - A file input to the model. + - `expires_at: number` - - `type: "input_file"` + The Unix timestamp (in seconds) for when the run will expire. - The type of the input item. Always `input_file`. + - `failed_at: number` - - `detail: optional "auto" or "low" or "high"` + The Unix timestamp (in seconds) for when the run failed. - 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`. + - `incomplete_details: object { reason }` - - `file_data: optional string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The content of the file to be sent to the model. + - `instructions: string` - - `file_id: optional string` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The ID of the file to be sent to the model. + - `last_error: object { code, message }` - - `file_url: optional string` + The last error associated with this run. Will be `null` if there are no errors. - The URL of the file to be sent to the model. + - `max_completion_tokens: number` - - `filename: optional string` + The maximum number of completion tokens specified to have been used over the course of the run. - The name of the file to be sent to the model. + - `max_prompt_tokens: number` - - `prompt_cache_breakpoint: optional object { mode }` + The maximum number of prompt tokens specified to have been used over the course of the run. - 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. + - `metadata: map[string]` - - `type: "custom_tool_call_output"` + 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. - The type of the custom tool call output. Always `custom_tool_call_output`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `id: optional string` + - `model: string` - The unique ID of the custom tool call output in the OpenAI platform. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `agent: optional object { agent_name }` + - `object: "thread.run"` - The agent that produced this item. + The object type, which is always `thread.run`. - - `agent_name: string` + - `parallel_tool_calls: boolean` - The canonical name of the agent that produced this item. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `caller: optional object { type } or object { caller_id, type }` + - `required_action: object { submit_tool_outputs, type }` - The execution context that produced this tool call. + Details on the action required to continue the run. Will be `null` if no action is required. - - `direct: object { type }` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `program: object { caller_id, type }` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `caller_id: string` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The call ID of the program item that produced this tool call. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `type: "program"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The caller type. Always `program`. + - `started_at: number` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + The Unix timestamp (in seconds) for when the run was started. - A call to a custom tool created by the model. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `call_id: string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - An identifier used to map this custom tool call to a tool call output. + - `thread_id: string` - - `input: string` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The input for the custom tool call generated by the model. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `name: string` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The name of the custom tool being called. + - `tools: array of AssistantTool` - - `type: "custom_tool_call"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the custom tool call. Always `custom_tool_call`. + - `truncation_strategy: object { type, last_messages }` - - `id: optional string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The unique ID of the custom tool call in the OpenAI platform. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `agent: optional object { agent_name }` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The agent that produced this item. + - `temperature: optional number` - - `agent_name: string` + The sampling temperature used for this run. If not set, defaults to 1. - The canonical name of the agent that produced this item. + - `top_p: optional number` - - `caller: optional object { type } or object { caller_id, type }` + The nucleus sampling value used for this run. If not set, defaults to 1. - The execution context that produced this tool call. + - `event: "thread.run.cancelling"` - - `direct: object { type }` + - `thread.run.cancelled: object { data, event }` - - `program: object { caller_id, type }` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - - `caller_id: string` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - The call ID of the program item that produced this tool call. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `type: "program"` + - `id: string` - - `namespace: optional string` + The identifier, which can be referenced in API endpoints. - The namespace of the custom tool being called. + - `assistant_id: string` - - `compaction_trigger: object { type, agent }` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - Compacts the current context. Must be the final input item. + - `cancelled_at: number` - - `type: "compaction_trigger"` + The Unix timestamp (in seconds) for when the run was cancelled. - The type of the item. Always `compaction_trigger`. + - `completed_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run was completed. - The agent that produced this item. + - `created_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the run was created. - The canonical name of the agent that produced this item. + - `expires_at: number` - - `item_reference: object { id, agent, type }` + The Unix timestamp (in seconds) for when the run will expire. - An internal identifier for an item to reference. + - `failed_at: number` - - `id: string` + The Unix timestamp (in seconds) for when the run failed. - The ID of the item to reference. + - `incomplete_details: object { reason }` - - `agent: optional object { agent_name }` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The agent that produced this item. + - `instructions: string` - - `agent_name: string` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The canonical name of the agent that produced this item. + - `last_error: object { code, message }` - - `type: optional "item_reference"` + The last error associated with this run. Will be `null` if there are no errors. - The type of item to reference. Always `item_reference`. + - `max_completion_tokens: number` - - `"item_reference"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `program: object { id, call_id, code, 3 more }` + - `max_prompt_tokens: number` - - `id: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The unique ID of this program item. + - `metadata: map[string]` - - `call_id: string` + 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. - The stable call ID of the program item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `code: string` + - `model: string` - The JavaScript source executed by programmatic tool calling. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `fingerprint: string` + - `object: "thread.run"` - Opaque program replay fingerprint that must be round-tripped. + The object type, which is always `thread.run`. - - `type: "program"` + - `parallel_tool_calls: boolean` - The item type. Always `program`. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `agent: optional object { agent_name }` + - `required_action: object { submit_tool_outputs, type }` - The agent that produced this item. + Details on the action required to continue the run. Will be `null` if no action is required. - - `agent_name: string` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The canonical name of the agent that produced this item. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `program_output: object { id, call_id, result, 3 more }` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `id: string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The unique ID of this program output item. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `call_id: string` + - `started_at: number` - The call ID of the program item. + The Unix timestamp (in seconds) for when the run was started. - - `result: string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The result produced by the program item. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `status: "completed" or "incomplete"` + - `thread_id: string` - The terminal status of the program output. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `"completed"` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `"incomplete"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `type: "program_output"` + - `tools: array of AssistantTool` - The item type. Always `program_output`. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `agent: optional object { agent_name }` + - `truncation_strategy: object { type, last_messages }` - The agent that produced this item. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `agent_name: string` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The canonical name of the agent that produced this item. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `metadata: map[string]` + - `temperature: optional number` - 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. + The sampling temperature used for this run. If not set, defaults to 1. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `top_p: optional number` - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + The nucleus sampling value used for this run. If not set, defaults to 1. - Model ID used to generate the response, like `gpt-4o` 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. + - `event: "thread.run.cancelled"` - - `"gpt-5.6-sol"` + - `thread.run.expired: object { data, event }` - - `"gpt-5.6-terra"` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - - `"gpt-5.6-luna"` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `"gpt-5.4"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"gpt-5.4-mini"` + - `id: string` - - `"gpt-5.4-nano"` + The identifier, which can be referenced in API endpoints. - - `"gpt-5.4-mini-2026-03-17"` + - `assistant_id: string` - - `"gpt-5.4-nano-2026-03-17"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `"gpt-5.3-chat-latest"` + - `cancelled_at: number` - - `"gpt-5.2"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `"gpt-5.2-2025-12-11"` + - `completed_at: number` - - `"gpt-5.2-chat-latest"` + The Unix timestamp (in seconds) for when the run was completed. - - `"gpt-5.2-pro"` + - `created_at: number` - - `"gpt-5.2-pro-2025-12-11"` + The Unix timestamp (in seconds) for when the run was created. - - `"gpt-5.1"` + - `expires_at: number` - - `"gpt-5.1-2025-11-13"` + The Unix timestamp (in seconds) for when the run will expire. - - `"gpt-5.1-codex"` + - `failed_at: number` - - `"gpt-5.1-mini"` + The Unix timestamp (in seconds) for when the run failed. - - `"gpt-5.1-chat-latest"` + - `incomplete_details: object { reason }` - - `"gpt-5"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"gpt-5-mini"` + - `instructions: string` - - `"gpt-5-nano"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"gpt-5-2025-08-07"` + - `last_error: object { code, message }` - - `"gpt-5-mini-2025-08-07"` + The last error associated with this run. Will be `null` if there are no errors. - - `"gpt-5-nano-2025-08-07"` + - `max_completion_tokens: number` - - `"gpt-5-chat-latest"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `"gpt-4.1"` + - `max_prompt_tokens: number` - - `"gpt-4.1-mini"` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `"gpt-4.1-nano"` + - `metadata: map[string]` - - `"gpt-4.1-2025-04-14"` + 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. - - `"gpt-4.1-mini-2025-04-14"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"gpt-4.1-nano-2025-04-14"` + - `model: string` - - `"o4-mini"` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"o4-mini-2025-04-16"` + - `object: "thread.run"` - - `"o3"` + The object type, which is always `thread.run`. - - `"o3-2025-04-16"` + - `parallel_tool_calls: boolean` - - `"o3-mini"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"o3-mini-2025-01-31"` + - `required_action: object { submit_tool_outputs, type }` - - `"o1"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `"o1-2024-12-17"` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `"o1-preview"` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `"o1-preview-2024-09-12"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"o1-mini"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"o1-mini-2024-09-12"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"gpt-4o"` + - `started_at: number` - - `"gpt-4o-2024-11-20"` + The Unix timestamp (in seconds) for when the run was started. - - `"gpt-4o-2024-08-06"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `"gpt-4o-2024-05-13"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `"gpt-4o-audio-preview"` + - `thread_id: string` - - `"gpt-4o-audio-preview-2024-10-01"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `"gpt-4o-audio-preview-2024-12-17"` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `"gpt-4o-audio-preview-2025-06-03"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `"gpt-4o-mini-audio-preview"` + - `tools: array of AssistantTool` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"gpt-4o-search-preview"` + - `truncation_strategy: object { type, last_messages }` - - `"gpt-4o-mini-search-preview"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"gpt-4o-search-preview-2025-03-11"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `"chatgpt-4o-latest"` + - `temperature: optional number` - - `"codex-mini-latest"` + The sampling temperature used for this run. If not set, defaults to 1. - - `"gpt-4o-mini"` + - `top_p: optional number` - - `"gpt-4o-mini-2024-07-18"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `"gpt-4-turbo"` + - `event: "thread.run.expired"` - - `"gpt-4-turbo-2024-04-09"` + - `thread.run.step.created: object { data, event }` - - `"gpt-4-0125-preview"` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `"gpt-4-turbo-preview"` + - `data: object { id, assistant_id, cancelled_at, 13 more }` - - `"gpt-4-1106-preview"` + Represents a step in execution of a run. - - `"gpt-4-vision-preview"` + - `id: string` - - `"gpt-4"` + The identifier of the run step, which can be referenced in API endpoints. - - `"gpt-4-0314"` + - `assistant_id: string` - - `"gpt-4-0613"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `"gpt-4-32k"` + - `cancelled_at: number` - - `"gpt-4-32k-0314"` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `"gpt-4-32k-0613"` + - `completed_at: number` - - `"gpt-3.5-turbo"` + The Unix timestamp (in seconds) for when the run step completed. - - `"gpt-3.5-turbo-16k"` + - `created_at: number` - - `"gpt-3.5-turbo-0301"` + The Unix timestamp (in seconds) for when the run step was created. - - `"gpt-3.5-turbo-0613"` + - `expired_at: number` - - `"gpt-3.5-turbo-1106"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `"gpt-3.5-turbo-0125"` + - `failed_at: number` - - `"gpt-3.5-turbo-16k-0613"` + The Unix timestamp (in seconds) for when the run step failed. - - `"o1-pro"` + - `last_error: object { code, message }` - - `"o1-pro-2025-03-19"` + The last error associated with this run step. Will be `null` if there are no errors. - - `"o3-pro"` + - `code: "server_error" or "rate_limit_exceeded"` - - `"o3-pro-2025-06-10"` + One of `server_error` or `rate_limit_exceeded`. - - `"o3-deep-research"` + - `"server_error"` - - `"o3-deep-research-2025-06-26"` + - `"rate_limit_exceeded"` - - `"o4-mini-deep-research"` + - `message: string` - - `"o4-mini-deep-research-2025-06-26"` + A human-readable description of the error. - - `"computer-use-preview"` + - `metadata: map[string]` - - `"computer-use-preview-2025-03-11"` + 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. - - `"gpt-5-codex"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"gpt-5-pro"` + - `object: "thread.run.step"` - - `"gpt-5-pro-2025-10-06"` + The object type, which is always `thread.run.step`. - - `"gpt-5.1-codex-max"` + - `run_id: string` - - `object: "response"` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - The object type of this resource - always set to `response`. + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `output: array of BetaResponseOutputItem` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - An array of content items generated by the model. + - `"in_progress"` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `"cancelled"` - - `beta_response_output_message: object { id, content, role, 4 more }` + - `"failed"` - An output message from the model. + - `"completed"` - - `id: string` + - `"expired"` - The unique ID of the output message. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The details of the run step. - The content of the output message. + - `message_creation_step_details: object { message_creation, type }` - - `role: "assistant"` + Details of the message creation by the run step. - The role of the output message. Always `assistant`. + - `message_creation: object { message_id }` - - `status: "in_progress" or "completed" or "incomplete"` + - `message_id: string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The ID of the message that was created by this run step. - - `type: "message"` + - `type: "message_creation"` - The type of the output message. Always `message`. + Always `message_creation`. - - `agent: optional object { agent_name }` + - `tool_calls_step_details: object { tool_calls, type }` - The agent that produced this item. + Details of the tool call. - - `phase: optional "commentary"` + - `tool_calls: array of ToolCall` - 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. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - 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. + Details of the Code Interpreter tool call the run step was involved in. - `id: string` - The unique ID of the file search tool call. - - - `queries: array of string` + The ID of the tool call. - The queries used to search for files. + - `code_interpreter: object { input, outputs }` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The Code Interpreter tool call definition. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `input: string` - - `type: "file_search_call"` + The input to the Code Interpreter tool call. - The type of the file search tool call. Always `file_search_call`. + - `outputs: array of object { logs, type } or object { image, type }` - - `agent: optional object { agent_name }` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The agent that produced this item. + - `logs: object { logs, type }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Text output from the Code Interpreter tool call as part of a run step. - The results of the file search tool call. + - `logs: string` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + The text output from the Code Interpreter tool call. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `type: "logs"` - - `arguments: string` + Always `logs`. - A JSON string of the arguments to pass to the function. + - `image: object { image, type }` - - `call_id: string` + - `image: object { file_id }` - The unique ID of the function tool call generated by the model. + - `file_id: string` - - `name: string` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The name of the function to run. + - `type: "image"` - - `type: "function_call"` + Always `image`. - The type of the function tool call. Always `function_call`. + - `type: "code_interpreter"` - - `id: optional string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The unique ID of the function tool call. + - `file_search_tool_call: object { id, file_search, type }` - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + The ID of the tool call object. - - `caller: optional object { type } or object { caller_id, type }` + - `file_search: object { ranking_options, results }` - The execution context that produced this tool call. + For now, this is always going to be an empty object. - - `namespace: optional string` + - `ranking_options: optional object { ranker, score_threshold }` - The namespace of the function to run. + The ranking options for the file search. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `ranker: "auto" or "default_2024_08_21"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `"auto"` - - `id: string` + - `"default_2024_08_21"` - The unique ID of the function call tool output. + - `score_threshold: number` - - `call_id: string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The unique ID of the function tool call generated by the model. + - `results: optional array of object { file_id, file_name, score, content }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The results of the file search. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `file_id: string` - - `string output: string` + The ID of the file that result was found in. - A string of the output of the function call. + - `file_name: string` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The name of the file that result was found in. - Text, image, or file output of the function call. + - `score: number` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The score of the result. All values must be a floating point number between 0 and 1. - A text input to the model. + - `content: optional array of object { text, type }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The content of the result that was found. The content is only included if requested via the include query parameter. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `text: optional string` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The text content of the file. - A file input to the model. + - `type: optional "text"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the content. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"text"` - - `"in_progress"` + - `type: "file_search"` - - `"completed"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"incomplete"` + - `function_tool_call: object { id, function, type }` - - `type: "function_call_output"` + - `id: string` - The type of the function tool call output. Always `function_call_output`. + The ID of the tool call object. - - `agent: optional object { agent_name }` + - `function: object { arguments, name, output }` - The agent that produced this item. + The definition of the function that was called. - - `agent_name: string` + - `arguments: string` - The canonical name of the agent that produced this item. + The arguments passed to the function. - - `caller: optional object { type } or object { caller_id, type }` + - `name: string` - The execution context that produced this tool call. + The name of the function. - - `direct: object { type }` + - `output: string` - - `program: object { caller_id, type }` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `caller_id: string` + - `type: "function"` - The call ID of the program item that produced this tool call. + The type of tool call. This is always going to be `function` for this type of tool call. - - `type: "program"` + - `type: "tool_calls"` - The caller type. Always `program`. + Always `tool_calls`. - - `created_by: optional string` + - `thread_id: string` - The identifier of the actor that created the item. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `agent_message: object { id, author, content, 3 more }` + - `type: "message_creation" or "tool_calls"` - - `id: string` + The type of run step, which can be either `message_creation` or `tool_calls`. - The unique ID of the agent message. + - `"message_creation"` - - `author: string` + - `"tool_calls"` - The sending agent identity. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - Encrypted content sent between agents. + - `completion_tokens: number` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + Number of completion tokens used over the course of the run step. - A text input to the model. + - `prompt_tokens: number` - - `beta_response_output_text: object { annotations, text, type, logprobs }` + Number of prompt tokens used over the course of the run step. - A text output from the model. + - `total_tokens: number` - - `text: object { text, type }` + Total number of tokens used (prompt + completion). - A text content. + - `event: "thread.run.step.created"` - - `text: string` + - `thread.run.step.in_progress: object { data, event }` - - `type: "text"` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - - `summary_text: object { text, type }` + - `data: object { id, assistant_id, cancelled_at, 13 more }` - A summary text from the model. + Represents a step in execution of a run. - - `text: string` + - `id: string` - A summary of the reasoning output from the model so far. + The identifier of the run step, which can be referenced in API endpoints. - - `type: "summary_text"` + - `assistant_id: string` - The type of the object. Always `summary_text`. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `reasoning_text: object { text, type }` + - `cancelled_at: number` - Reasoning text from the model. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `text: string` + - `completed_at: number` - The reasoning text from the model. + The Unix timestamp (in seconds) for when the run step completed. - - `type: "reasoning_text"` + - `created_at: number` - The type of the reasoning text. Always `reasoning_text`. + The Unix timestamp (in seconds) for when the run step was created. - - `beta_response_output_refusal: object { refusal, type }` + - `expired_at: number` - A refusal from the model. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `failed_at: number` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The Unix timestamp (in seconds) for when the run step failed. - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `last_error: object { code, message }` - A screenshot of a computer. + The last error associated with this run step. Will be `null` if there are no errors. - - `detail: "low" or "high" or "auto" or "original"` + - `metadata: map[string]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + 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. - - `"low"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"high"` + - `object: "thread.run.step"` - - `"auto"` + The object type, which is always `thread.run.step`. - - `"original"` + - `run_id: string` - - `file_id: string` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - The identifier of an uploaded file that contains the screenshot. + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `image_url: string` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The URL of the screenshot image. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `type: "computer_screenshot"` + The details of the run step. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `thread_id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - 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. + - `type: "message_creation" or "tool_calls"` - - `mode: "explicit"` + The type of run step, which can be either `message_creation` or `tool_calls`. - The breakpoint mode. Always `explicit`. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - A file input to the model. + - `event: "thread.run.step.in_progress"` - - `encrypted_content: object { encrypted_content, type }` + - `thread.run.step.delta: object { data, event }` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - - `encrypted_content: string` + - `data: object { id, delta, object }` - Opaque encrypted content. + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `type: "encrypted_content"` + - `id: string` - The type of the input item. Always `encrypted_content`. + The identifier of the run step, which can be referenced in API endpoints. - - `recipient: string` + - `delta: object { step_details }` - The destination agent identity. + The delta containing the fields that have changed on the run step. - - `type: "agent_message"` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - The type of the item. Always `agent_message`. + The details of the run step. - - `agent: optional object { agent_name }` + - `run_step_delta_message_delta: object { type, message_creation }` - The agent that produced this item. + Details of the message creation by the run step. - - `agent_name: string` + - `type: "message_creation"` - The canonical name of the agent that produced this item. + Always `message_creation`. - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `message_creation: optional object { message_id }` - - `id: string` + - `message_id: optional string` - The unique ID of the multi-agent call item. + The ID of the message that was created by this run step. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `tool_call_delta_object: object { type, tool_calls }` - The multi-agent action to execute. + Details of the tool call. - - `"spawn_agent"` + - `type: "tool_calls"` - - `"interrupt_agent"` + Always `tool_calls`. - - `"list_agents"` + - `tool_calls: optional array of ToolCallDelta` - - `"send_message"` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `"followup_task"` + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - - `"wait_agent"` + Details of the Code Interpreter tool call the run step was involved in. - - `arguments: string` + - `index: number` - The JSON string of arguments generated for the action. + The index of the tool call in the tool calls array. - - `call_id: string` + - `type: "code_interpreter"` - The unique ID linking this call to its output. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `type: "multi_agent_call"` + - `id: optional string` - The type of the multi-agent call. Always `multi_agent_call`. + The ID of the tool call. - - `agent: optional object { agent_name }` + - `code_interpreter: optional object { input, outputs }` - The agent that produced this item. + The Code Interpreter tool call definition. - - `agent_name: string` + - `input: optional string` - The canonical name of the agent that produced this item. + The input to the Code Interpreter tool call. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `id: string` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The unique ID of the multi-agent call output item. + - `code_interpreter_logs: object { index, type, logs }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Text output from the Code Interpreter tool call as part of a run step. - The multi-agent action that produced this result. + - `index: number` - - `"spawn_agent"` + The index of the output in the outputs array. - - `"interrupt_agent"` + - `type: "logs"` - - `"list_agents"` + Always `logs`. - - `"send_message"` + - `logs: optional string` - - `"followup_task"` + The text output from the Code Interpreter tool call. - - `"wait_agent"` + - `code_interpreter_output_image: object { index, type, image }` - - `call_id: string` + - `index: number` - The unique ID of the multi-agent call. + The index of the output in the outputs array. - - `output: array of BetaResponseOutputText` + - `type: "image"` - Text output returned by the multi-agent action. + Always `image`. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `image: optional object { file_id }` - The annotations of the text output. + - `file_id: optional string` - - `text: string` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The text output from the model. + - `file_search_tool_call_delta: object { file_search, index, type, id }` - - `type: "output_text"` + - `file_search: unknown` - The type of the output text. Always `output_text`. + For now, this is always going to be an empty object. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `index: number` - - `type: "multi_agent_call_output"` + The index of the tool call in the tool calls array. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `type: "file_search"` - - `agent: optional object { agent_name }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The agent that produced this item. + - `id: optional string` - - `agent_name: string` + The ID of the tool call object. - The canonical name of the agent that produced this item. + - `function_tool_call_delta: object { index, type, id, function }` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `index: number` - 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. + The index of the tool call in the tool calls array. - - `id: string` + - `type: "function"` - The unique ID of the web search tool call. + The type of tool call. This is always going to be `function` for this type of tool call. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `id: optional string` - 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). + The ID of the tool call object. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `function: optional object { arguments, name, output }` - The status of the web search tool call. + The definition of the function that was called. - - `type: "web_search_call"` + - `arguments: optional string` - The type of the web search tool call. Always `web_search_call`. + The arguments passed to the function. - - `agent: optional object { agent_name }` + - `name: optional string` - The agent that produced this item. + The name of the function. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `output: optional string` - 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. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `id: string` + - `object: "thread.run.step.delta"` - The unique ID of the computer call. + The object type, which is always `thread.run.step.delta`. - - `call_id: string` + - `event: "thread.run.step.delta"` - An identifier used when responding to the tool call with output. + - `thread.run.step.completed: object { data, event }` - - `pending_safety_checks: array of object { id, code, message }` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - The pending safety checks for the computer call. + - `data: object { id, assistant_id, cancelled_at, 13 more }` - - `status: "in_progress" or "completed" or "incomplete"` + Represents a step in execution of a run. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `id: string` - - `type: "computer_call"` + The identifier of the run step, which can be referenced in API endpoints. - The type of the computer call. Always `computer_call`. + - `assistant_id: string` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - A click action. + - `cancelled_at: number` - - `actions: optional array of BetaComputerAction` + The Unix timestamp (in seconds) for when the run step was cancelled. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `completed_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run step completed. - The agent that produced this item. + - `created_at: number` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + The Unix timestamp (in seconds) for when the run step was created. - - `id: string` + - `expired_at: number` - The unique ID of the computer call tool output. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `call_id: string` + - `failed_at: number` - The ID of the computer tool call that produced the output. + The Unix timestamp (in seconds) for when the run step failed. - - `output: object { type, file_id, image_url }` + - `last_error: object { code, message }` - A computer screenshot image used with the computer use tool. + The last error associated with this run step. Will be `null` if there are no errors. - - `type: "computer_screenshot"` + - `metadata: map[string]` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + 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. - - `file_id: optional string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The identifier of an uploaded file that contains the screenshot. + - `object: "thread.run.step"` - - `image_url: optional string` + The object type, which is always `thread.run.step`. - The URL of the screenshot image. + - `run_id: string` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `"completed"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `"incomplete"` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `"failed"` + The details of the run step. - - `"in_progress"` + - `thread_id: string` - - `type: "computer_call_output"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - The type of the computer tool call output. Always `computer_call_output`. + - `type: "message_creation" or "tool_calls"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The type of run step, which can be either `message_creation` or `tool_calls`. - The safety checks reported by the API that have been acknowledged by the - developer. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `id: string` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The ID of the pending safety check. + - `event: "thread.run.step.completed"` - - `code: optional string` + - `thread.run.step.failed: object { data, event }` - The type of the pending safety check. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - - `message: optional string` + - `data: object { id, assistant_id, cancelled_at, 13 more }` - Details about the pending safety check. + Represents a step in execution of a run. - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + The identifier of the run step, which can be referenced in API endpoints. - - `agent_name: string` + - `assistant_id: string` - The canonical name of the agent that produced this item. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `created_by: optional string` + - `cancelled_at: number` - The identifier of the actor that created the item. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `completed_at: number` - 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). + The Unix timestamp (in seconds) for when the run step completed. - - `id: string` + - `created_at: number` - The unique identifier of the reasoning content. + The Unix timestamp (in seconds) for when the run step was created. - - `summary: array of object { text, type }` + - `expired_at: number` - Reasoning summary content. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `type: "reasoning"` + - `failed_at: number` - The type of the object. Always `reasoning`. + The Unix timestamp (in seconds) for when the run step failed. - - `agent: optional object { agent_name }` + - `last_error: object { code, message }` - The agent that produced this item. + The last error associated with this run step. Will be `null` if there are no errors. - - `content: optional array of object { text, type }` + - `metadata: map[string]` - Reasoning text content. + 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. - - `encrypted_content: optional string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `object: "thread.run.step"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The object type, which is always `thread.run.step`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `run_id: string` - - `program: object { id, call_id, code, 3 more }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `id: string` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - The unique ID of the program item. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `call_id: string` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - The stable call ID of the program item. + The details of the run step. - - `code: string` + - `thread_id: string` - The JavaScript source executed by programmatic tool calling. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `fingerprint: string` + - `type: "message_creation" or "tool_calls"` - Opaque program replay fingerprint that must be round-tripped. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `type: "program"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The type of the item. Always `program`. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `agent: optional object { agent_name }` + - `event: "thread.run.step.failed"` - The agent that produced this item. + - `thread.run.step.cancelled: object { data, event }` - - `agent_name: string` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. - The canonical name of the agent that produced this item. + - `data: object { id, assistant_id, cancelled_at, 13 more }` - - `program_output: object { id, call_id, result, 3 more }` + Represents a step in execution of a run. - `id: string` - The unique ID of the program output item. + The identifier of the run step, which can be referenced in API endpoints. - - `call_id: string` + - `assistant_id: string` - The call ID of the program item. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `result: string` + - `cancelled_at: number` - The result produced by the program item. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `status: "completed" or "incomplete"` + - `completed_at: number` - The terminal status of the program output item. + The Unix timestamp (in seconds) for when the run step completed. - - `"completed"` + - `created_at: number` - - `"incomplete"` + The Unix timestamp (in seconds) for when the run step was created. - - `type: "program_output"` + - `expired_at: number` - The type of the item. Always `program_output`. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `agent: optional object { agent_name }` + - `failed_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run step failed. - - `agent_name: string` + - `last_error: object { code, message }` - The canonical name of the agent that produced this item. + The last error associated with this run step. Will be `null` if there are no errors. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `metadata: map[string]` - - `id: string` + 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. - The unique ID of the tool search call item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `arguments: unknown` + - `object: "thread.run.step"` - Arguments used for the tool search call. + The object type, which is always `thread.run.step`. - - `call_id: string` + - `run_id: string` - The unique ID of the tool search call generated by the model. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `execution: "server" or "client"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - Whether tool search was executed by the server or by the client. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `"server"` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `"client"` + The details of the run step. - - `status: "in_progress" or "completed" or "incomplete"` + - `thread_id: string` - The status of the tool search call item that was recorded. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `"in_progress"` + - `type: "message_creation" or "tool_calls"` - - `"completed"` + The type of run step, which can be either `message_creation` or `tool_calls`. - - `"incomplete"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "tool_search_call"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The type of the item. Always `tool_search_call`. + - `event: "thread.run.step.cancelled"` - - `agent: optional object { agent_name }` + - `thread.run.step.expired: object { data, event }` - The agent that produced this item. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - - `agent_name: string` + - `data: object { id, assistant_id, cancelled_at, 13 more }` - The canonical name of the agent that produced this item. + Represents a step in execution of a run. - - `created_by: optional string` + - `id: string` - The identifier of the actor that created the item. + The identifier of the run step, which can be referenced in API endpoints. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `assistant_id: string` - - `id: string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The unique ID of the tool search output item. + - `cancelled_at: number` - - `call_id: string` + The Unix timestamp (in seconds) for when the run step was cancelled. - The unique ID of the tool search call generated by the model. + - `completed_at: number` - - `execution: "server" or "client"` + The Unix timestamp (in seconds) for when the run step completed. - Whether tool search was executed by the server or by the client. + - `created_at: number` - - `"server"` + The Unix timestamp (in seconds) for when the run step was created. - - `"client"` + - `expired_at: number` - - `status: "in_progress" or "completed" or "incomplete"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The status of the tool search output item that was recorded. + - `failed_at: number` - - `"in_progress"` + The Unix timestamp (in seconds) for when the run step failed. - - `"completed"` + - `last_error: object { code, message }` - - `"incomplete"` + The last error associated with this run step. Will be `null` if there are no errors. - - `tools: array of BetaTool` + - `metadata: map[string]` - The loaded tool definitions returned by tool search. + 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. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - 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). + - `object: "thread.run.step"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The object type, which is always `thread.run.step`. - 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). + - `run_id: string` - - `beta_computer_tool: object { type }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The details of the run step. - 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). + - `thread_id: string` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `type: "message_creation" or "tool_calls"` - - `code_interpreter: object { container, type, allowed_callers }` + The type of run step, which can be either `message_creation` or `tool_calls`. - A tool that runs Python code to help generate a response to a prompt. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `programmatic_tool_calling: object { type }` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `image_generation: object { type, action, background, 9 more }` + - `event: "thread.run.step.expired"` - A tool that generates images using the GPT image models. + - `thread.message.created: object { data, event }` - - `local_shell: object { type }` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - A tool that allows the model to execute shell commands in a local environment. + - `data: object { id, assistant_id, attachments, 11 more }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - A tool that allows the model to execute shell commands. + - `id: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The identifier, which can be referenced in API endpoints. - 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) + - `assistant_id: string` - - `beta_namespace_tool: object { description, name, tools, type }` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - Groups function/custom tools under a shared namespace. + - `attachments: array of object { file_id, tools }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + A list of files attached to the message, and the tools they were added to. - Hosted or BYOT tool search configuration for deferred tools. + - `file_id: optional string` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The ID of the file to attach to the message. - 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). + - `tools: optional array of CodeInterpreterTool or object { type }` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The tools to add this file to. - Allows the assistant to create, delete, or update files using unified diffs. + - `code_interpreter_tool: object { type }` - - `type: "tool_search_output"` + - `type: "code_interpreter"` - The type of the item. Always `tool_search_output`. + The type of tool being defined: `code_interpreter` - - `agent: optional object { agent_name }` + - `AssistantToolsFileSearchTypeOnly: object { type }` - The agent that produced this item. + - `completed_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the message was completed. - The canonical name of the agent that produced this item. + - `content: array of MessageContent` - - `created_by: optional string` + The content of the message in array of text and/or images. - The identifier of the actor that created the item. + - `image_file_content_block: object { image_file, type }` - - `additional_tools: object { id, role, tools, 2 more }` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `id: string` + - `image_file: object { file_id, detail }` - The unique ID of the additional tools item. + - `file_id: string` - - `role: "unknown" or "user" or "assistant" or 5 more` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The role that provided the additional tools. + - `detail: optional "auto" or "low" or "high"` - - `"unknown"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"user"` + - `"auto"` - - `"assistant"` + - `"low"` - - `"system"` + - `"high"` - - `"critic"` + - `type: "image_file"` - - `"discriminator"` + Always `image_file`. - - `"developer"` + - `image_url_content_block: object { image_url, type }` - - `"tool"` + References an image URL in the content of a message. - - `tools: array of BetaTool` + - `image_url: object { url, detail }` - The additional tool definitions made available at this item. + - `url: string` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - 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). + - `detail: optional "auto" or "low" or "high"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - 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). + - `"auto"` - - `beta_computer_tool: object { type }` + - `"low"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"high"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `type: "image_url"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the content part. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `text_content_block: object { text, type }` - 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). + The text content that is part of a message. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `text: object { annotations, value }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `annotations: array of Annotation` - - `code_interpreter: object { container, type, allowed_callers }` + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - A tool that runs Python code to help generate a response to a prompt. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `programmatic_tool_calling: object { type }` + - `end_index: number` - - `image_generation: object { type, action, background, 9 more }` + - `file_citation: object { file_id }` - A tool that generates images using the GPT image models. + - `file_id: string` - - `local_shell: object { type }` + The ID of the specific File the citation is from. - A tool that allows the model to execute shell commands in a local environment. + - `start_index: number` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `text: string` - A tool that allows the model to execute shell commands. + The text in the message content that needs to be replaced. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `type: "file_citation"` - 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) + Always `file_citation`. - - `beta_namespace_tool: object { description, name, tools, type }` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - Groups function/custom tools under a shared namespace. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `end_index: number` - Hosted or BYOT tool search configuration for deferred tools. + - `file_path: object { file_id }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `file_id: string` - 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). + The ID of the file that was generated. - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `start_index: number` - Allows the assistant to create, delete, or update files using unified diffs. + - `text: string` - - `type: "additional_tools"` + The text in the message content that needs to be replaced. - The type of the item. Always `additional_tools`. + - `type: "file_path"` - - `agent: optional object { agent_name }` + Always `file_path`. - The agent that produced this item. + - `value: string` - - `agent_name: string` + The data that makes up the text. - The canonical name of the agent that produced this item. + - `type: "text"` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + Always `text`. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `refusal_content_block: object { refusal, type }` - - `id: string` + The refusal content generated by the assistant. - The unique ID of the compaction item. + - `refusal: string` - - `encrypted_content: string` + - `type: "refusal"` - The encrypted content that was produced by compaction. + Always `refusal`. - - `type: "compaction"` + - `created_at: number` - The type of the item. Always `compaction`. + The Unix timestamp (in seconds) for when the message was created. - - `agent: optional object { agent_name }` + - `incomplete_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `agent_name: string` + - `incomplete_details: object { reason }` - The canonical name of the agent that produced this item. + On an incomplete message, details about why the message is incomplete. - - `created_by: optional string` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - The identifier of the actor that created the item. + The reason the message is incomplete. - - `image_generation_call: object { id, result, status, 2 more }` + - `"content_filter"` - An image generation request made by the model. + - `"max_tokens"` - - `id: string` + - `"run_cancelled"` - The unique ID of the image generation call. + - `"run_expired"` - - `result: string` + - `"run_failed"` - The generated image encoded in base64. + - `metadata: map[string]` - - `status: "in_progress" or "completed" or "generating" or "failed"` + 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. - The status of the image generation call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"in_progress"` + - `object: "thread.message"` - - `"completed"` + The object type, which is always `thread.message`. - - `"generating"` + - `role: "user" or "assistant"` - - `"failed"` + The entity that produced the message. One of `user` or `assistant`. - - `type: "image_generation_call"` + - `"user"` - The type of the image generation call. Always `image_generation_call`. + - `"assistant"` - - `agent: optional object { agent_name }` + - `run_id: string` - The agent that produced this item. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `agent_name: string` + - `status: "in_progress" or "incomplete" or "completed"` - The canonical name of the agent that produced this item. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `"in_progress"` - A tool call to run code. + - `"incomplete"` - - `id: string` + - `"completed"` - The unique ID of the code interpreter tool call. + - `thread_id: string` - - `code: string` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The code to run, or null if not available. + - `event: "thread.message.created"` - - `container_id: string` + - `thread.message.in_progress: object { data, event }` - The ID of the container used to run the code. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - - `outputs: array of object { logs, type } or object { type, url }` + - `data: object { id, assistant_id, attachments, 11 more }` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `id: string` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The identifier, which can be referenced in API endpoints. - - `type: "code_interpreter_call"` + - `assistant_id: string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `agent: optional object { agent_name }` + - `attachments: array of object { file_id, tools }` - The agent that produced this item. + A list of files attached to the message, and the tools they were added to. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `completed_at: number` - A tool call to run a command on the local shell. + The Unix timestamp (in seconds) for when the message was completed. - - `id: string` + - `content: array of MessageContent` - The unique ID of the local shell call. + The content of the message in array of text and/or images. - - `action: object { command, env, type, 3 more }` + - `created_at: number` - Execute a shell command on the server. + The Unix timestamp (in seconds) for when the message was created. - - `command: array of string` + - `incomplete_at: number` - The command to run. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `env: map[string]` + - `incomplete_details: object { reason }` - Environment variables to set for the command. + On an incomplete message, details about why the message is incomplete. - - `type: "exec"` + - `metadata: map[string]` - The type of the local shell action. Always `exec`. + 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. - - `timeout_ms: optional number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Optional timeout in milliseconds for the command. + - `object: "thread.message"` - - `user: optional string` + The object type, which is always `thread.message`. - Optional user to run the command as. + - `role: "user" or "assistant"` - - `working_directory: optional string` + The entity that produced the message. One of `user` or `assistant`. - Optional working directory to run the command in. + - `run_id: string` - - `call_id: string` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - The unique ID of the local shell tool call generated by the model. + - `status: "in_progress" or "incomplete" or "completed"` - - `status: "in_progress" or "completed" or "incomplete"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The status of the local shell call. + - `thread_id: string` - - `"in_progress"` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `"completed"` + - `event: "thread.message.in_progress"` - - `"incomplete"` + - `thread.message.delta: object { data, event }` - - `type: "local_shell_call"` + Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - The type of the local shell call. Always `local_shell_call`. + - `data: object { id, delta, object }` - - `agent: optional object { agent_name }` + Represents a message delta i.e. any changed fields on a message during streaming. - The agent that produced this item. + - `id: string` - - `agent_name: string` + The identifier of the message, which can be referenced in API endpoints. - The canonical name of the agent that produced this item. + - `delta: object { content, role }` - - `local_shell_call_output: object { id, output, type, 2 more }` + The delta containing the fields that have changed on the Message. - The output of a local shell tool call. + - `content: optional array of MessageContentDelta` - - `id: string` + The content of the message in array of text and/or images. - The unique ID of the local shell tool call generated by the model. + - `image_file_delta_block: object { index, type, image_file }` - - `output: string` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - A JSON string of the output of the local shell tool call. + - `index: number` - - `type: "local_shell_call_output"` + The index of the content part in the message. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `type: "image_file"` - - `agent: optional object { agent_name }` + Always `image_file`. - The agent that produced this item. + - `image_file: optional object { detail, file_id }` - - `agent_name: string` + - `detail: optional "auto" or "low" or "high"` - The canonical name of the agent that produced this item. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"low"` - - `"in_progress"` + - `"high"` - - `"completed"` + - `file_id: optional string` - - `"incomplete"` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `text_delta_block: object { index, type, text }` - A tool call that executes one or more shell commands in a managed environment. + The text content that is part of a message. - - `id: string` + - `index: number` - The unique ID of the shell tool call. Populated when this item is returned via API. + The index of the content part in the message. - - `action: object { commands, max_output_length, timeout_ms }` + - `type: "text"` - The shell commands and limits that describe how to run the tool call. + Always `text`. - - `commands: array of string` + - `text: optional object { annotations, value }` - - `max_output_length: number` + - `annotations: optional array of AnnotationDelta` - Optional maximum number of characters to return from each command. + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - - `timeout_ms: number` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Optional timeout in milliseconds for the commands. + - `index: number` - - `call_id: string` + The index of the annotation in the text content part. - The unique ID of the shell tool call generated by the model. + - `type: "file_citation"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + Always `file_citation`. - Represents the use of a local environment to perform shell actions. + - `end_index: optional number` - - `beta_response_local_environment: object { type }` + - `file_citation: optional object { file_id, quote }` - Represents the use of a local environment to perform shell actions. + - `file_id: optional string` - - `type: "local"` + The ID of the specific File the citation is from. - The environment type. Always `local`. + - `quote: optional string` - - `beta_response_container_reference: object { container_id, type }` + The specific quote in the file. - Represents a container created with /v1/containers. + - `start_index: optional number` - - `container_id: string` + - `text: optional string` - - `type: "container_reference"` + The text in the message content that needs to be replaced. - The environment type. Always `container_reference`. + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - - `status: "in_progress" or "completed" or "incomplete"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `index: number` - - `"in_progress"` + The index of the annotation in the text content part. - - `"completed"` + - `type: "file_path"` - - `"incomplete"` + Always `file_path`. - - `type: "shell_call"` + - `end_index: optional number` - The type of the item. Always `shell_call`. + - `file_path: optional object { file_id }` - - `agent: optional object { agent_name }` + - `file_id: optional string` - The agent that produced this item. + The ID of the file that was generated. - - `agent_name: string` + - `start_index: optional number` - The canonical name of the agent that produced this item. + - `text: optional string` - - `caller: optional object { type } or object { caller_id, type }` + The text in the message content that needs to be replaced. - The execution context that produced this tool call. + - `value: optional string` - - `direct: object { type }` + The data that makes up the text. - - `program: object { caller_id, type }` + - `refusal_delta_block: object { index, type, refusal }` - - `caller_id: string` + The refusal content that is part of a message. - The call ID of the program item that produced this tool call. + - `index: number` - - `type: "program"` + The index of the refusal part in the message. - - `created_by: optional string` + - `type: "refusal"` - The ID of the entity that created this tool call. + Always `refusal`. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `refusal: optional string` - The output of a shell tool call that was emitted. + - `image_url_delta_block: object { index, type, image_url }` - - `id: string` + References an image URL in the content of a message. - The unique ID of the shell call output. Populated when this item is returned via API. + - `index: number` - - `call_id: string` + The index of the content part in the message. - The unique ID of the shell tool call generated by the model. + - `type: "image_url"` - - `max_output_length: number` + Always `image_url`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `image_url: optional object { detail, url }` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `detail: optional "auto" or "low" or "high"` - An array of shell call output contents + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `outcome: object { type } or object { exit_code, type }` + - `"auto"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"low"` - - `timeout: object { type }` + - `"high"` - Indicates that the shell call exceeded its configured time limit. + - `url: optional string` - - `exit: object { exit_code, type }` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Indicates that the shell commands finished and returned an exit code. + - `role: optional "user" or "assistant"` - - `exit_code: number` + The entity that produced the message. One of `user` or `assistant`. - Exit code from the shell process. + - `"user"` - - `type: "exit"` + - `"assistant"` - The outcome type. Always `exit`. + - `object: "thread.message.delta"` - - `stderr: string` + The object type, which is always `thread.message.delta`. - The standard error output that was captured. + - `event: "thread.message.delta"` - - `stdout: string` + - `thread.message.completed: object { data, event }` - The standard output that was captured. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - - `created_by: optional string` + - `data: object { id, assistant_id, attachments, 11 more }` - The identifier of the actor that created the item. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `status: "in_progress" or "completed" or "incomplete"` + - `id: string` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `"in_progress"` + - `attachments: array of object { file_id, tools }` - - `"completed"` + A list of files attached to the message, and the tools they were added to. - - `"incomplete"` + - `completed_at: number` - - `type: "shell_call_output"` + The Unix timestamp (in seconds) for when the message was completed. - The type of the shell call output. Always `shell_call_output`. + - `content: array of MessageContent` - - `agent: optional object { agent_name }` + The content of the message in array of text and/or images. - The agent that produced this item. + - `created_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the message was created. - The canonical name of the agent that produced this item. + - `incomplete_at: number` - - `caller: optional object { type } or object { caller_id, type }` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - The execution context that produced this tool call. + - `incomplete_details: object { reason }` - - `direct: object { type }` + On an incomplete message, details about why the message is incomplete. - - `program: object { caller_id, type }` + - `metadata: map[string]` - - `caller_id: string` + 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. - The call ID of the program item that produced this tool call. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "program"` + - `object: "thread.message"` - - `created_by: optional string` + The object type, which is always `thread.message`. - The identifier of the actor that created the item. + - `role: "user" or "assistant"` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + The entity that produced the message. One of `user` or `assistant`. - A tool call that applies file diffs by creating, deleting, or updating files. + - `run_id: string` - - `id: string` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `status: "in_progress" or "incomplete" or "completed"` - - `call_id: string` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The unique ID of the apply patch tool call generated by the model. + - `thread_id: string` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `event: "thread.message.completed"` - - `create_file: object { diff, path, type }` + - `thread.message.incomplete: object { data, event }` - Instruction describing how to create a file via the apply_patch tool. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. - - `diff: string` + - `data: object { id, assistant_id, attachments, 11 more }` - Diff to apply. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `path: string` + - `id: string` - Path of the file to create. + The identifier, which can be referenced in API endpoints. - - `type: "create_file"` + - `assistant_id: string` - Create a new file with the provided diff. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `delete_file: object { path, type }` + - `attachments: array of object { file_id, tools }` - Instruction describing how to delete a file via the apply_patch tool. + A list of files attached to the message, and the tools they were added to. - - `path: string` + - `completed_at: number` - Path of the file to delete. + The Unix timestamp (in seconds) for when the message was completed. - - `type: "delete_file"` + - `content: array of MessageContent` - Delete the specified file. + The content of the message in array of text and/or images. - - `update_file: object { diff, path, type }` + - `created_at: number` - Instruction describing how to update a file via the apply_patch tool. + The Unix timestamp (in seconds) for when the message was created. - - `diff: string` + - `incomplete_at: number` - Diff to apply. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `path: string` + - `incomplete_details: object { reason }` - Path of the file to update. + On an incomplete message, details about why the message is incomplete. - - `type: "update_file"` + - `metadata: map[string]` - Update an existing file with the provided diff. + 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. - - `status: "in_progress" or "completed"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `object: "thread.message"` - - `"in_progress"` + The object type, which is always `thread.message`. - - `"completed"` + - `role: "user" or "assistant"` - - `type: "apply_patch_call"` + The entity that produced the message. One of `user` or `assistant`. - The type of the item. Always `apply_patch_call`. + - `run_id: string` - - `agent: optional object { agent_name }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - The agent that produced this item. + - `status: "in_progress" or "incomplete" or "completed"` - - `agent_name: string` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The canonical name of the agent that produced this item. + - `thread_id: string` - - `caller: optional object { type } or object { caller_id, type }` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The execution context that produced this tool call. + - `event: "thread.message.incomplete"` - - `direct: object { type }` + - `error_event: object { data, event }` - - `program: object { caller_id, type }` + Occurs when an [error](https://platform.openai.com/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. - - `caller_id: string` + - `data: object { code, message, param, type }` - The call ID of the program item that produced this tool call. + - `code: string` - - `type: "program"` + - `message: string` - - `created_by: optional string` + - `param: string` - The ID of the entity that created this tool call. + - `type: string` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `event: "error"` - The output emitted by an apply patch tool call. +### Assistant Tool - - `id: string` +- `assistant_tool: CodeInterpreterTool or FileSearchTool or FunctionTool` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `code_interpreter_tool: object { type }` - - `call_id: string` + - `type: "code_interpreter"` - The unique ID of the apply patch tool call generated by the model. + The type of tool being defined: `code_interpreter` - - `status: "completed" or "failed"` + - `file_search_tool: object { type, file_search }` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `type: "file_search"` - - `"completed"` + The type of tool being defined: `file_search` - - `"failed"` + - `file_search: optional object { max_num_results, ranking_options }` - - `type: "apply_patch_call_output"` + Overrides for the file search tool. - The type of the item. Always `apply_patch_call_output`. + - `max_num_results: optional number` - - `agent: optional object { agent_name }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The agent that produced this item. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `agent_name: string` + - `ranking_options: optional object { score_threshold, ranker }` - The canonical name of the agent that produced this item. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `caller: optional object { type } or object { caller_id, type }` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The execution context that produced this tool call. + - `score_threshold: number` - - `direct: object { type }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `program: object { caller_id, type }` + - `ranker: optional "auto" or "default_2024_08_21"` - - `caller_id: string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The call ID of the program item that produced this tool call. + - `"auto"` - - `type: "program"` + - `"default_2024_08_21"` - - `created_by: optional string` + - `function_tool: object { function, type }` - The ID of the entity that created this tool call output. + - `function: object { name, description, parameters, strict }` - - `output: optional string` + - `name: string` - Optional textual output returned by the apply patch tool. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `mcp_call: object { id, arguments, name, 7 more }` + - `description: optional string` - An invocation of a tool on an MCP server. + A description of what the function does, used by the model to choose when and how to call the function. - - `id: string` + - `parameters: optional map[unknown]` - The unique ID of the tool call. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `arguments: string` + Omitting `parameters` defines a function with an empty parameter list. - A JSON string of the arguments passed to the tool. + - `strict: optional boolean` - - `name: string` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The name of the tool that was run. + - `type: "function"` - - `server_label: string` + The type of tool being defined: `function` - The label of the MCP server running the tool. +### Code Interpreter Tool - - `type: "mcp_call"` +- `code_interpreter_tool: object { type }` - The type of the item. Always `mcp_call`. + - `type: "code_interpreter"` - - `agent: optional object { agent_name }` + The type of tool being defined: `code_interpreter` - The agent that produced this item. +### File Search Tool - - `agent_name: string` +- `file_search_tool: object { type, file_search }` - The canonical name of the agent that produced this item. + - `type: "file_search"` - - `approval_request_id: optional string` + The type of tool being defined: `file_search` - 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. + - `file_search: optional object { max_num_results, ranking_options }` - - `error: optional string` + Overrides for the file search tool. - The error from the tool call, if any. + - `max_num_results: optional number` - - `output: optional string` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The output from the tool call. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `ranking_options: optional object { score_threshold, ranker }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"in_progress"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"completed"` + - `score_threshold: number` - - `"incomplete"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"calling"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"failed"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `"auto"` - A list of tools available on an MCP server. + - `"default_2024_08_21"` - - `id: string` +### Function Tool - The unique ID of the list. +- `function_tool: object { function, type }` - - `server_label: string` + - `function: object { name, description, parameters, strict }` - The label of the MCP server. + - `name: string` - - `tools: array of object { input_schema, name, annotations, description }` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The tools available on the server. + - `description: optional string` - - `input_schema: unknown` + A description of what the function does, used by the model to choose when and how to call the function. - The JSON schema describing the tool's input. + - `parameters: optional map[unknown]` - - `name: string` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The name of the tool. + Omitting `parameters` defines a function with an empty parameter list. - - `annotations: optional unknown` + - `strict: optional boolean` - Additional annotations about the tool. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - `description: optional string` + - `type: "function"` - The description of the tool. + The type of tool being defined: `function` - - `type: "mcp_list_tools"` +### Message Stream Event - The type of the item. Always `mcp_list_tools`. +- `message_stream_event: object { data, event } or object { data, event } or object { data, event } or 2 more` - - `agent: optional object { agent_name }` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - The agent that produced this item. + - `thread.message.created: object { data, event }` - - `agent_name: string` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - The canonical name of the agent that produced this item. + - `data: object { id, assistant_id, attachments, 11 more }` - - `error: optional string` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - Error message if the server could not list tools. + - `id: string` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The identifier, which can be referenced in API endpoints. - A request for human approval of a tool invocation. + - `assistant_id: string` - - `id: string` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - The unique ID of the approval request. + - `attachments: array of object { file_id, tools }` - - `arguments: string` + A list of files attached to the message, and the tools they were added to. - A JSON string of arguments for the tool. + - `file_id: optional string` - - `name: string` + The ID of the file to attach to the message. - The name of the tool to run. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `server_label: string` + The tools to add this file to. - The label of the MCP server making the request. + - `code_interpreter_tool: object { type }` - - `type: "mcp_approval_request"` + - `type: "code_interpreter"` - The type of the item. Always `mcp_approval_request`. + The type of tool being defined: `code_interpreter` - - `agent: optional object { agent_name }` + - `AssistantToolsFileSearchTypeOnly: object { type }` - The agent that produced this item. + - `completed_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the message was completed. - The canonical name of the agent that produced this item. + - `content: array of MessageContent` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + The content of the message in array of text and/or images. - A response to an MCP approval request. + - `image_file_content_block: object { image_file, type }` - - `id: string` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The unique ID of the approval response + - `image_file: object { file_id, detail }` - - `approval_request_id: string` + - `file_id: string` - The ID of the approval request being answered. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `approve: boolean` + - `detail: optional "auto" or "low" or "high"` - Whether the request was approved. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `type: "mcp_approval_response"` + - `"auto"` - The type of the item. Always `mcp_approval_response`. + - `"low"` - - `agent: optional object { agent_name }` + - `"high"` - The agent that produced this item. + - `type: "image_file"` - - `agent_name: string` + Always `image_file`. - The canonical name of the agent that produced this item. + - `image_url_content_block: object { image_url, type }` - - `reason: optional string` + References an image URL in the content of a message. - Optional reason for the decision. + - `image_url: object { url, detail }` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `url: string` - A call to a custom tool created by the model. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `call_id: string` + - `detail: optional "auto" or "low" or "high"` - An identifier used to map this custom tool call to a tool call output. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `input: string` + - `"auto"` - The input for the custom tool call generated by the model. + - `"low"` - - `name: string` + - `"high"` - The name of the custom tool being called. + - `type: "image_url"` - - `type: "custom_tool_call"` + The type of the content part. - The type of the custom tool call. Always `custom_tool_call`. + - `text_content_block: object { text, type }` - - `id: optional string` + The text content that is part of a message. - The unique ID of the custom tool call in the OpenAI platform. + - `text: object { annotations, value }` - - `agent: optional object { agent_name }` + - `annotations: array of Annotation` - The agent that produced this item. + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - - `caller: optional object { type } or object { caller_id, type }` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The execution context that produced this tool call. + - `end_index: number` - - `namespace: optional string` + - `file_citation: object { file_id }` - The namespace of the custom tool being called. + - `file_id: string` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The ID of the specific File the citation is from. - The output of a custom tool call from your code, being sent back to the model. + - `start_index: number` - - `id: string` + - `text: string` - The unique ID of the custom tool call output item. + The text in the message content that needs to be replaced. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "file_citation"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Always `file_citation`. - - `"in_progress"` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `"completed"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"incomplete"` + - `end_index: number` - - `created_by: optional string` + - `file_path: object { file_id }` - The identifier of the actor that created the item. + - `file_id: string` - - `parallel_tool_calls: boolean` + The ID of the file that was generated. - Whether to allow the model to run tool calls in parallel. + - `start_index: number` - - `temperature: number` + - `text: string` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + The text in the message content that needs to be replaced. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `type: "file_path"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + Always `file_path`. - - `beta_tool_choice_options: "none" or "auto" or "required"` + - `value: string` - Controls which (if any) tool is called by the model. + The data that makes up the text. - `none` means the model will not call any tool and instead generates a message. + - `type: "text"` - `auto` means the model can pick between generating a message or calling one or - more tools. + Always `text`. - `required` means the model must call one or more tools. + - `refusal_content_block: object { refusal, type }` - - `"none"` + The refusal content generated by the assistant. - - `"auto"` + - `refusal: string` - - `"required"` + - `type: "refusal"` - - `beta_tool_choice_allowed: object { mode, tools, type }` + Always `refusal`. - Constrains the tools available to the model to a pre-defined set. + - `created_at: number` - - `mode: "auto" or "required"` + The Unix timestamp (in seconds) for when the message was created. - Constrains the tools available to the model to a pre-defined set. + - `incomplete_at: number` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - `required` requires the model to call one or more of the allowed tools. + - `incomplete_details: object { reason }` - - `"auto"` + On an incomplete message, details about why the message is incomplete. - - `"required"` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `tools: array of map[unknown]` + The reason the message is incomplete. - A list of tool definitions that the model should be allowed to call. + - `"content_filter"` - For the Responses API, the list of tool definitions might look like: + - `"max_tokens"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"run_cancelled"` - - `type: "allowed_tools"` + - `"run_expired"` - Allowed tool configuration type. Always `allowed_tools`. + - `"run_failed"` - - `beta_tool_choice_types: object { type }` + - `metadata: map[string]` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + 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. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `object: "thread.message"` - Allowed values are: + The object type, which is always `thread.message`. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `role: "user" or "assistant"` - - `"file_search"` + The entity that produced the message. One of `user` or `assistant`. - - `"web_search_preview"` + - `"user"` - - `"computer"` + - `"assistant"` - - `"computer_use_preview"` + - `run_id: string` - - `"computer_use"` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `"web_search_preview_2025_03_11"` + - `status: "in_progress" or "incomplete" or "completed"` - - `"image_generation"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"code_interpreter"` + - `"in_progress"` - - `beta_tool_choice_function: object { name, type }` + - `"incomplete"` - Use this option to force the model to call a specific function. + - `"completed"` - - `name: string` + - `thread_id: string` - The name of the function to call. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `type: "function"` + - `event: "thread.message.created"` - For function calling, the type is always `function`. + - `thread.message.in_progress: object { data, event }` - - `beta_tool_choice_mcp: object { server_label, type, name }` + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - Use this option to force the model to call a specific tool on a remote MCP server. + - `data: object { id, assistant_id, attachments, 11 more }` - - `server_label: string` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The label of the MCP server to use. + - `id: string` - - `type: "mcp"` + The identifier, which can be referenced in API endpoints. - For MCP tools, the type is always `mcp`. + - `assistant_id: string` - - `name: optional string` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - The name of the tool to call on the server. + - `attachments: array of object { file_id, tools }` - - `beta_tool_choice_custom: object { name, type }` + A list of files attached to the message, and the tools they were added to. - Use this option to force the model to call a specific custom tool. + - `completed_at: number` - - `name: string` + The Unix timestamp (in seconds) for when the message was completed. - The name of the custom tool to call. + - `content: array of MessageContent` - - `type: "custom"` + The content of the message in array of text and/or images. - For custom tool calling, the type is always `custom`. + - `created_at: number` - - `BetaSpecificProgrammaticToolCallingParam: object { type }` + The Unix timestamp (in seconds) for when the message was created. - - `beta_tool_choice_apply_patch: object { type }` + - `incomplete_at: number` - Forces the model to call the apply_patch tool when executing a tool call. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `type: "apply_patch"` + - `incomplete_details: object { reason }` - The tool to call. Always `apply_patch`. + On an incomplete message, details about why the message is incomplete. - - `beta_tool_choice_shell: object { type }` + - `metadata: map[string]` - Forces the model to call the shell tool when a tool call is required. + 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. - - `type: "shell"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The tool to call. Always `shell`. + - `object: "thread.message"` - - `tools: array of BetaTool` + The object type, which is always `thread.message`. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `role: "user" or "assistant"` - We support the following categories of tools: + The entity that produced the message. One of `user` or `assistant`. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `run_id: string` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - 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). + - `status: "in_progress" or "incomplete" or "completed"` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - 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). + - `thread_id: string` - - `beta_computer_tool: object { type }` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `event: "thread.message.in_progress"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + - `thread.message.delta: object { data, event }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `data: object { id, delta, object }` - 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). + Represents a message delta i.e. any changed fields on a message during streaming. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `id: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The identifier of the message, which can be referenced in API endpoints. - - `code_interpreter: object { container, type, allowed_callers }` + - `delta: object { content, role }` - A tool that runs Python code to help generate a response to a prompt. + The delta containing the fields that have changed on the Message. - - `programmatic_tool_calling: object { type }` + - `content: optional array of MessageContentDelta` - - `image_generation: object { type, action, background, 9 more }` + The content of the message in array of text and/or images. - A tool that generates images using the GPT image models. + - `image_file_delta_block: object { index, type, image_file }` - - `local_shell: object { type }` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - A tool that allows the model to execute shell commands in a local environment. + - `index: number` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The index of the content part in the message. - A tool that allows the model to execute shell commands. + - `type: "image_file"` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + Always `image_file`. - 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) + - `image_file: optional object { detail, file_id }` - - `beta_namespace_tool: object { description, name, tools, type }` + - `detail: optional "auto" or "low" or "high"` - Groups function/custom tools under a shared namespace. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `"auto"` - Hosted or BYOT tool search configuration for deferred tools. + - `"low"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `"high"` - 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). + - `file_id: optional string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Allows the assistant to create, delete, or update files using unified diffs. + - `text_delta_block: object { index, type, text }` - - `top_p: number` + The text content that is part of a message. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `index: number` - We generally recommend altering this or `temperature` but not both. + The index of the content part in the message. - - `background: optional boolean` + - `type: "text"` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + Always `text`. - - `completed_at: optional number` + - `text: optional object { annotations, value }` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `annotations: optional array of AnnotationDelta` - - `conversation: optional object { id }` + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `id: string` + - `index: number` - The unique ID of the conversation that this response was associated with. + The index of the annotation in the text content part. - - `max_output_tokens: optional number` + - `type: "file_citation"` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + Always `file_citation`. - - `max_tool_calls: optional number` + - `end_index: optional number` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `file_citation: optional object { file_id, quote }` - - `moderation: optional object { input, output }` + - `file_id: optional string` - Moderation results for the response input and output, if moderated completions were requested. + The ID of the specific File the citation is from. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `quote: optional string` - Moderation for the response input. + The specific quote in the file. - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + - `start_index: optional number` - A moderation result produced for the response input or output. + - `text: optional string` - - `categories: map[boolean]` + The text in the message content that needs to be replaced. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - - `category_applied_input_types: map[array of "text" or "image"]` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Which modalities of input are reflected by the score for each category. + - `index: number` - - `"text"` + The index of the annotation in the text content part. - - `"image"` + - `type: "file_path"` - - `category_scores: map[number]` + Always `file_path`. - A dictionary of moderation categories to scores. + - `end_index: optional number` - - `flagged: boolean` + - `file_path: optional object { file_id }` - A boolean indicating whether the content was flagged by any category. + - `file_id: optional string` - - `model: string` + The ID of the file that was generated. - The moderation model that produced this result. + - `start_index: optional number` - - `type: "moderation_result"` + - `text: optional string` - The object type, which was always `moderation_result` for successful moderation results. + The text in the message content that needs to be replaced. - - `error: object { code, message, type }` + - `value: optional string` - An error produced while attempting moderation for the response input or output. + The data that makes up the text. - - `code: string` + - `refusal_delta_block: object { index, type, refusal }` - The error code. + The refusal content that is part of a message. - - `message: string` + - `index: number` - The error message. + The index of the refusal part in the message. - - `type: "error"` + - `type: "refusal"` - The object type, which was always `error` for moderation failures. + Always `refusal`. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `refusal: optional string` - Moderation for the response output. + - `image_url_delta_block: object { index, type, image_url }` - - `moderation_result: object { categories, category_applied_input_types, category_scores, 3 more }` + References an image URL in the content of a message. - A moderation result produced for the response input or output. + - `index: number` - - `categories: map[boolean]` + The index of the content part in the message. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `type: "image_url"` - - `category_applied_input_types: map[array of "text" or "image"]` + Always `image_url`. - Which modalities of input are reflected by the score for each category. + - `image_url: optional object { detail, url }` - - `"text"` + - `detail: optional "auto" or "low" or "high"` - - `"image"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `category_scores: map[number]` + - `"auto"` - A dictionary of moderation categories to scores. + - `"low"` - - `flagged: boolean` + - `"high"` - A boolean indicating whether the content was flagged by any category. + - `url: optional string` - - `model: string` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The moderation model that produced this result. + - `role: optional "user" or "assistant"` - - `type: "moderation_result"` + The entity that produced the message. One of `user` or `assistant`. - The object type, which was always `moderation_result` for successful moderation results. + - `"user"` - - `error: object { code, message, type }` + - `"assistant"` - An error produced while attempting moderation for the response input or output. + - `object: "thread.message.delta"` - - `code: string` + The object type, which is always `thread.message.delta`. - The error code. + - `event: "thread.message.delta"` - - `message: string` + - `thread.message.completed: object { data, event }` - The error message. + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - - `type: "error"` + - `data: object { id, assistant_id, attachments, 11 more }` - The object type, which was always `error` for moderation failures. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `previous_response_id: optional string` + - `id: string` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The identifier, which can be referenced in API endpoints. - - `prompt: optional object { id, variables, version }` + - `assistant_id: string` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `id: string` + - `attachments: array of object { file_id, tools }` - The unique identifier of the prompt template to use. + A list of files attached to the message, and the tools they were added to. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `completed_at: number` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The Unix timestamp (in seconds) for when the message was completed. - - `union_member_0: string` + - `content: array of MessageContent` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The content of the message in array of text and/or images. - A text input to the model. + - `created_at: number` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The Unix timestamp (in seconds) for when the message was created. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `incomplete_at: number` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - A file input to the model. + - `incomplete_details: object { reason }` - - `version: optional string` + On an incomplete message, details about why the message is incomplete. - Optional version of the prompt template. + - `metadata: map[string]` - - `prompt_cache_key: optional string` + 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. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `prompt_cache_options: optional object { mode, ttl }` + - `object: "thread.message"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The object type, which is always `thread.message`. - - `mode: "implicit" or "explicit"` + - `role: "user" or "assistant"` - Whether implicit prompt-cache breakpoints were enabled. + The entity that produced the message. One of `user` or `assistant`. - - `"implicit"` + - `run_id: string` - - `"explicit"` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `ttl: "30m"` + - `status: "in_progress" or "incomplete" or "completed"` - The minimum lifetime applied to each cache breakpoint. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"30m"` + - `thread_id: string` - - `prompt_cache_retention: optional "in_memory" or "24h"` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `event: "thread.message.completed"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `thread.message.incomplete: object { data, event }` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `data: object { id, assistant_id, attachments, 11 more }` - - `"in_memory"` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `"24h"` + - `id: string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The identifier, which can be referenced in API endpoints. - **gpt-5 and o-series models only** + - `assistant_id: string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `attachments: array of object { file_id, tools }` - Controls which reasoning items are rendered back to the model on later turns. - When returned on a response, this is the effective reasoning context mode - used for the response. + A list of files attached to the message, and the tools they were added to. - - `"auto"` + - `completed_at: number` - - `"current_turn"` + The Unix timestamp (in seconds) for when the message was completed. - - `"all_turns"` + - `content: array of MessageContent` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The content of the message in array of text and/or images. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `created_at: number` - - `"none"` + The Unix timestamp (in seconds) for when the message was created. - - `"minimal"` + - `incomplete_at: number` - - `"low"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"medium"` + - `incomplete_details: object { reason }` - - `"high"` + On an incomplete message, details about why the message is incomplete. - - `"xhigh"` + - `metadata: map[string]` - - `"max"` + 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. - - `generate_summary: optional "auto" or "concise" or "detailed"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - **Deprecated:** use `summary` instead. + - `object: "thread.message"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The object type, which is always `thread.message`. - - `"auto"` + - `role: "user" or "assistant"` - - `"concise"` + The entity that produced the message. One of `user` or `assistant`. - - `"detailed"` + - `run_id: string` - - `mode: optional string or "standard" or "pro"` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - Controls the reasoning execution mode for the request. + - `status: "in_progress" or "incomplete" or "completed"` - When returned on a response, this is the effective execution mode. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"standard"` + - `thread_id: string` - - `"pro"` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `summary: optional "auto" or "concise" or "detailed"` + - `event: "thread.message.incomplete"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. +### Run Step Stream Event - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. +- `run_step_stream_event: object { data, event } or object { data, event } or object { data, event } or 4 more` - - `"auto"` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `"concise"` + - `thread.run.step.created: object { data, event }` - - `"detailed"` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - `safety_identifier: optional string` + - `data: object { id, assistant_id, cancelled_at, 13 more }` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Represents a step in execution of a run. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `id: string` - Specifies the processing type used for serving the request. + The identifier of the run step, which can be referenced in API endpoints. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `assistant_id: string` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `"auto"` + - `cancelled_at: number` - - `"default"` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `"flex"` + - `completed_at: number` - - `"scale"` + The Unix timestamp (in seconds) for when the run step completed. - - `"priority"` + - `created_at: number` - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + The Unix timestamp (in seconds) for when the run step was created. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `expired_at: number` - - `"completed"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `"failed"` + - `failed_at: number` - - `"in_progress"` + The Unix timestamp (in seconds) for when the run step failed. - - `"cancelled"` + - `last_error: object { code, message }` - - `"queued"` + The last error associated with this run step. Will be `null` if there are no errors. - - `"incomplete"` + - `code: "server_error" or "rate_limit_exceeded"` - - `text: optional object { format, verbosity }` + One of `server_error` or `rate_limit_exceeded`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"server_error"` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `"rate_limit_exceeded"` - - `format: optional object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + - `message: string` - An object specifying the format that the model must output. + A human-readable description of the error. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + - `metadata: map[string]` - The default format is `{ "type": "text" }` with no additional options. + 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. - **Not recommended for gpt-4o and newer models:** + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `object: "thread.run.step"` - - `text: object { type }` + The object type, which is always `thread.run.step`. - Default response format. Used to generate text responses. + - `run_id: string` - - `beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `name: string` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `"in_progress"` - - `schema: map[unknown]` + - `"cancelled"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"failed"` - - `type: "json_schema"` + - `"completed"` - The type of response format being defined. Always `json_schema`. + - `"expired"` - - `description: optional string` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The details of the run step. - - `strict: optional boolean` + - `message_creation_step_details: object { message_creation, type }` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). + Details of the message creation by the run step. - - `json_object: object { type }` + - `message_creation: object { message_id }` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `message_id: string` - - `verbosity: optional "low" or "medium" or "high"` + The ID of the message that was created by this run step. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. + - `type: "message_creation"` - - `"low"` + Always `message_creation`. - - `"medium"` + - `tool_calls_step_details: object { tool_calls, type }` - - `"high"` + Details of the tool call. - - `top_logprobs: optional number` + - `tool_calls: array of ToolCall` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `truncation: optional "auto" or "disabled"` + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - The truncation strategy to use for the model response. + Details of the Code Interpreter tool call the run step was involved in. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `id: string` - - `"auto"` + The ID of the tool call. - - `"disabled"` + - `code_interpreter: object { input, outputs }` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + The Code Interpreter tool call definition. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `input: string` - - `input_tokens: number` + The input to the Code Interpreter tool call. - The number of input tokens. + - `outputs: array of object { logs, type } or object { image, type }` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - A detailed breakdown of the input tokens. + - `logs: object { logs, type }` - - `cache_write_tokens: number` + Text output from the Code Interpreter tool call as part of a run step. - The number of input tokens that were written to the cache. + - `logs: string` - - `cached_tokens: number` + The text output from the Code Interpreter tool call. - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + - `type: "logs"` - - `output_tokens: number` + Always `logs`. - The number of output tokens. + - `image: object { image, type }` - - `output_tokens_details: object { reasoning_tokens }` + - `image: object { file_id }` - A detailed breakdown of the output tokens. + - `file_id: string` - - `reasoning_tokens: number` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The number of reasoning tokens. + - `type: "image"` - - `total_tokens: number` + Always `image`. - The total number of tokens used. + - `type: "code_interpreter"` - - `user: optional string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `file_search_tool_call: object { id, file_search, type }` - - `sequence_number: number` + - `id: string` - The sequence number for this event. + The ID of the tool call object. - - `type: "response.completed"` + - `file_search: object { ranking_options, results }` - The type of the event. Always `response.completed`. + For now, this is always going to be an empty object. - - `agent: optional object { agent_name }` + - `ranking_options: optional object { ranker, score_threshold }` - The agent that owns this multi-agent streaming event. + The ranking options for the file search. - - `agent_name: string` + - `ranker: "auto" or "default_2024_08_21"` - The canonical name of the agent that produced this item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `beta_response_content_part_added_event: object { content_index, item_id, output_index, 4 more }` + - `"auto"` - Emitted when a new content part is added. + - `"default_2024_08_21"` - - `content_index: number` + - `score_threshold: number` - The index of the content part that was added. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `item_id: string` + - `results: optional array of object { file_id, file_name, score, content }` - The ID of the output item that the content part was added to. + The results of the file search. - - `output_index: number` + - `file_id: string` - The index of the output item that the content part was added to. + The ID of the file that result was found in. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `file_name: string` - The content part that was added. + The name of the file that result was found in. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `score: number` - A text output from the model. + The score of the result. All values must be a floating point number between 0 and 1. - - `beta_response_output_refusal: object { refusal, type }` + - `content: optional array of object { text, type }` - A refusal from the model. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `reasoning_text: object { text, type }` + - `text: optional string` - Reasoning text from the model. + The text content of the file. - - `text: string` + - `type: optional "text"` - The reasoning text from the model. + The type of the content. - - `type: "reasoning_text"` + - `"text"` - The type of the reasoning text. Always `reasoning_text`. + - `type: "file_search"` - - `sequence_number: number` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The sequence number of this event. + - `function_tool_call: object { id, function, type }` - - `type: "response.content_part.added"` + - `id: string` - The type of the event. Always `response.content_part.added`. + The ID of the tool call object. - - `agent: optional object { agent_name }` + - `function: object { arguments, name, output }` - The agent that owns this multi-agent streaming event. + The definition of the function that was called. - - `agent_name: string` + - `arguments: string` - The canonical name of the agent that produced this item. + The arguments passed to the function. - - `beta_response_content_part_done_event: object { content_index, item_id, output_index, 4 more }` + - `name: string` - Emitted when a content part is done. + The name of the function. - - `content_index: number` + - `output: string` - The index of the content part that is done. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `item_id: string` + - `type: "function"` - The ID of the output item that the content part was added to. + The type of tool call. This is always going to be `function` for this type of tool call. - - `output_index: number` + - `type: "tool_calls"` - The index of the output item that the content part was added to. + Always `tool_calls`. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `thread_id: string` - The content part that is done. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `type: "message_creation" or "tool_calls"` - A text output from the model. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `beta_response_output_refusal: object { refusal, type }` + - `"message_creation"` - A refusal from the model. + - `"tool_calls"` - - `reasoning_text: object { text, type }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Reasoning text from the model. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `text: string` + - `completion_tokens: number` - The reasoning text from the model. + Number of completion tokens used over the course of the run step. - - `type: "reasoning_text"` + - `prompt_tokens: number` - The type of the reasoning text. Always `reasoning_text`. + Number of prompt tokens used over the course of the run step. - - `sequence_number: number` + - `total_tokens: number` - The sequence number of this event. + Total number of tokens used (prompt + completion). - - `type: "response.content_part.done"` + - `event: "thread.run.step.created"` - The type of the event. Always `response.content_part.done`. + - `thread.run.step.in_progress: object { data, event }` - - `agent: optional object { agent_name }` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - The agent that owns this multi-agent streaming event. + - `data: object { id, assistant_id, cancelled_at, 13 more }` - - `agent_name: string` + Represents a step in execution of a run. - The canonical name of the agent that produced this item. + - `id: string` - - `beta_response_created_event: object { response, sequence_number, type, agent }` + The identifier of the run step, which can be referenced in API endpoints. - An event that is emitted when a response is created. + - `assistant_id: string` - - `response: object { id, created_at, error, 31 more }` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The response that was created. + - `cancelled_at: number` - - `id: string` + The Unix timestamp (in seconds) for when the run step was cancelled. - Unique identifier for this Response. + - `completed_at: number` - - `created_at: number` + The Unix timestamp (in seconds) for when the run step completed. - Unix timestamp (in seconds) of when this Response was created. + - `created_at: number` - - `error: object { code, message }` + The Unix timestamp (in seconds) for when the run step was created. - An error object returned when the model fails to generate a Response. + - `expired_at: number` - - `incomplete_details: object { reason }` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - Details about why the response is incomplete. + - `failed_at: number` - - `instructions: string or array of BetaResponseInputItem` + The Unix timestamp (in seconds) for when the run step failed. - A system (or developer) message inserted into the model's context. + - `last_error: object { code, message }` - When using 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. + The last error associated with this run step. Will be `null` if there are no errors. - `metadata: map[string]` @@ -135858,425 +147982,393 @@ openai beta:responses compact \ Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `object: "thread.run.step"` - Model ID used to generate the response, like `gpt-4o` 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. + The object type, which is always `thread.run.step`. - - `object: "response"` + - `run_id: string` - The object type of this resource - always set to `response`. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `output: array of BetaResponseOutputItem` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - An array of content items generated by the model. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `parallel_tool_calls: boolean` + The details of the run step. - Whether to allow the model to run tool calls in parallel. + - `thread_id: string` - - `temperature: number` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `type: "message_creation" or "tool_calls"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The type of run step, which can be either `message_creation` or `tool_calls`. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `tools: array of BetaTool` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `event: "thread.run.step.in_progress"` - We support the following categories of tools: + - `thread.run.step.delta: object { data, event }` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - - `top_p: number` + - `data: object { id, delta, object }` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + Represents a run step delta i.e. any changed fields on a run step during streaming. - We generally recommend altering this or `temperature` but not both. + - `id: string` - - `background: optional boolean` + The identifier of the run step, which can be referenced in API endpoints. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `delta: object { step_details }` - - `completed_at: optional number` + The delta containing the fields that have changed on the run step. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - - `conversation: optional object { id }` + The details of the run step. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `run_step_delta_message_delta: object { type, message_creation }` - - `max_output_tokens: optional number` + Details of the message creation by the run step. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `type: "message_creation"` - - `max_tool_calls: optional number` + Always `message_creation`. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `message_creation: optional object { message_id }` - - `moderation: optional object { input, output }` + - `message_id: optional string` - Moderation results for the response input and output, if moderated completions were requested. + The ID of the message that was created by this run step. - - `previous_response_id: optional string` + - `tool_call_delta_object: object { type, tool_calls }` - 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`. + Details of the tool call. - - `prompt: optional object { id, variables, version }` + - `type: "tool_calls"` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Always `tool_calls`. - - `prompt_cache_key: optional string` + - `tool_calls: optional array of ToolCallDelta` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `prompt_cache_options: optional object { mode, ttl }` + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + Details of the Code Interpreter tool call the run step was involved in. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `index: number` - Deprecated. Use `prompt_cache_options.ttl` instead. + The index of the tool call in the tool calls array. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `type: "code_interpreter"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `id: optional string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The ID of the tool call. - **gpt-5 and o-series models only** + - `code_interpreter: optional object { input, outputs }` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The Code Interpreter tool call definition. - - `safety_identifier: optional string` + - `input: optional string` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The input to the Code Interpreter tool call. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - Specifies the processing type used for serving the request. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `code_interpreter_logs: object { index, type, logs }` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + Text output from the Code Interpreter tool call as part of a run step. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `index: number` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The index of the output in the outputs array. - - `text: optional object { format, verbosity }` + - `type: "logs"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Always `logs`. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `logs: optional string` - - `top_logprobs: optional number` + The text output from the Code Interpreter tool call. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `code_interpreter_output_image: object { index, type, image }` - - `truncation: optional "auto" or "disabled"` + - `index: number` - The truncation strategy to use for the model response. + The index of the output in the outputs array. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `type: "image"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + Always `image`. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `image: optional object { file_id }` - - `user: optional string` + - `file_id: optional string` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `sequence_number: number` + - `file_search_tool_call_delta: object { file_search, index, type, id }` - The sequence number for this event. + - `file_search: unknown` - - `type: "response.created"` + For now, this is always going to be an empty object. - The type of the event. Always `response.created`. + - `index: number` - - `agent: optional object { agent_name }` + The index of the tool call in the tool calls array. - The agent that owns this multi-agent streaming event. + - `type: "file_search"` - - `agent_name: string` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The canonical name of the agent that produced this item. + - `id: optional string` - - `beta_response_error_event: object { code, message, param, 3 more }` + The ID of the tool call object. - Emitted when an error occurs. + - `function_tool_call_delta: object { index, type, id, function }` - - `code: string` + - `index: number` - The error code. + The index of the tool call in the tool calls array. - - `message: string` + - `type: "function"` - The error message. + The type of tool call. This is always going to be `function` for this type of tool call. - - `param: string` + - `id: optional string` - The error parameter. + The ID of the tool call object. - - `sequence_number: number` + - `function: optional object { arguments, name, output }` - The sequence number of this event. + The definition of the function that was called. - - `type: "error"` + - `arguments: optional string` - The type of the event. Always `error`. + The arguments passed to the function. - - `agent: optional object { agent_name }` + - `name: optional string` - The agent that owns this multi-agent streaming event. + The name of the function. - - `agent_name: string` + - `output: optional string` - The canonical name of the agent that produced this item. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `beta_response_file_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `object: "thread.run.step.delta"` - Emitted when a file search call is completed (results found). + The object type, which is always `thread.run.step.delta`. - - `item_id: string` + - `event: "thread.run.step.delta"` - The ID of the output item that the file search call is initiated. + - `thread.run.step.completed: object { data, event }` - - `output_index: number` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - The index of the output item that the file search call is initiated. + - `data: object { id, assistant_id, cancelled_at, 13 more }` - - `sequence_number: number` + Represents a step in execution of a run. - The sequence number of this event. + - `id: string` - - `type: "response.file_search_call.completed"` + The identifier of the run step, which can be referenced in API endpoints. - The type of the event. Always `response.file_search_call.completed`. + - `assistant_id: string` - - `agent: optional object { agent_name }` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The agent that owns this multi-agent streaming event. + - `cancelled_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the run step was cancelled. - The canonical name of the agent that produced this item. + - `completed_at: number` - - `beta_response_file_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + The Unix timestamp (in seconds) for when the run step completed. - Emitted when a file search call is initiated. + - `created_at: number` - - `item_id: string` + The Unix timestamp (in seconds) for when the run step was created. - The ID of the output item that the file search call is initiated. + - `expired_at: number` - - `output_index: number` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The index of the output item that the file search call is initiated. + - `failed_at: number` - - `sequence_number: number` + The Unix timestamp (in seconds) for when the run step failed. - The sequence number of this event. + - `last_error: object { code, message }` - - `type: "response.file_search_call.in_progress"` + The last error associated with this run step. Will be `null` if there are no errors. - The type of the event. Always `response.file_search_call.in_progress`. + - `metadata: map[string]` - - `agent: optional object { agent_name }` + 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. - The agent that owns this multi-agent streaming event. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `agent_name: string` + - `object: "thread.run.step"` - The canonical name of the agent that produced this item. + The object type, which is always `thread.run.step`. - - `beta_response_file_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` + - `run_id: string` - Emitted when a file search is currently searching. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `item_id: string` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - The ID of the output item that the file search call is initiated. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `output_index: number` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - The index of the output item that the file search call is searching. + The details of the run step. - - `sequence_number: number` + - `thread_id: string` - The sequence number of this event. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `type: "response.file_search_call.searching"` + - `type: "message_creation" or "tool_calls"` - The type of the event. Always `response.file_search_call.searching`. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `agent: optional object { agent_name }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The agent that owns this multi-agent streaming event. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `agent_name: string` + - `event: "thread.run.step.completed"` - The canonical name of the agent that produced this item. + - `thread.run.step.failed: object { data, event }` - - `beta_response_function_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - Emitted when there is a partial function-call arguments delta. + - `data: object { id, assistant_id, cancelled_at, 13 more }` - - `delta: string` + Represents a step in execution of a run. - The function-call arguments delta that is added. + - `id: string` - - `item_id: string` + The identifier of the run step, which can be referenced in API endpoints. - The ID of the output item that the function-call arguments delta is added to. + - `assistant_id: string` - - `output_index: number` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - The index of the output item that the function-call arguments delta is added to. + - `cancelled_at: number` - - `sequence_number: number` + The Unix timestamp (in seconds) for when the run step was cancelled. - The sequence number of this event. + - `completed_at: number` - - `type: "response.function_call_arguments.delta"` + The Unix timestamp (in seconds) for when the run step completed. - The type of the event. Always `response.function_call_arguments.delta`. + - `created_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run step was created. - The agent that owns this multi-agent streaming event. + - `expired_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The canonical name of the agent that produced this item. + - `failed_at: number` - - `beta_response_function_call_arguments_done_event: object { arguments, item_id, name, 4 more }` + The Unix timestamp (in seconds) for when the run step failed. - Emitted when function-call arguments are finalized. + - `last_error: object { code, message }` - - `arguments: string` + The last error associated with this run step. Will be `null` if there are no errors. - The function-call arguments. + - `metadata: map[string]` - - `item_id: string` + 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. - The ID of the item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `name: string` + - `object: "thread.run.step"` - The name of the function that was called. + The object type, which is always `thread.run.step`. - - `output_index: number` + - `run_id: string` - The index of the output item. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `sequence_number: number` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - The sequence number of this event. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `type: "response.function_call_arguments.done"` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `agent: optional object { agent_name }` + The details of the run step. - The agent that owns this multi-agent streaming event. + - `thread_id: string` - - `agent_name: string` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - The canonical name of the agent that produced this item. + - `type: "message_creation" or "tool_calls"` - - `beta_response_in_progress_event: object { response, sequence_number, type, agent }` + The type of run step, which can be either `message_creation` or `tool_calls`. - Emitted when the response is in progress. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `response: object { id, created_at, error, 31 more }` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The response that is in progress. + - `event: "thread.run.step.failed"` + + - `thread.run.step.cancelled: object { data, event }` + + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. + + - `data: object { id, assistant_id, cancelled_at, 13 more }` + + Represents a step in execution of a run. - `id: string` - Unique identifier for this Response. + The identifier of the run step, which can be referenced in API endpoints. - - `created_at: number` + - `assistant_id: string` - Unix timestamp (in seconds) of when this Response was created. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `error: object { code, message }` + - `cancelled_at: number` - An error object returned when the model fails to generate a Response. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `incomplete_details: object { reason }` + - `completed_at: number` - Details about why the response is incomplete. + The Unix timestamp (in seconds) for when the run step completed. - - `instructions: string or array of BetaResponseInputItem` + - `created_at: number` - A system (or developer) message inserted into the model's context. + The Unix timestamp (in seconds) for when the run step was created. - When using 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. + - `expired_at: number` + + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + + - `failed_at: number` + + The Unix timestamp (in seconds) for when the run step failed. + + - `last_error: object { code, message }` + + The last error associated with this run step. Will be `null` if there are no errors. - `metadata: map[string]` @@ -136287,243 +148379,198 @@ openai beta:responses compact \ Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `object: "thread.run.step"` - Model ID used to generate the response, like `gpt-4o` 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. + The object type, which is always `thread.run.step`. - - `object: "response"` + - `run_id: string` - The object type of this resource - always set to `response`. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `output: array of BetaResponseOutputItem` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - An array of content items generated by the model. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `parallel_tool_calls: boolean` + The details of the run step. - Whether to allow the model to run tool calls in parallel. + - `thread_id: string` - - `temperature: number` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `type: "message_creation" or "tool_calls"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The type of run step, which can be either `message_creation` or `tool_calls`. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `tools: array of BetaTool` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `event: "thread.run.step.cancelled"` - We support the following categories of tools: + - `thread.run.step.expired: object { data, event }` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - - `top_p: number` + - `data: object { id, assistant_id, cancelled_at, 13 more }` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + Represents a step in execution of a run. - We generally recommend altering this or `temperature` but not both. + - `id: string` - - `background: optional boolean` + The identifier of the run step, which can be referenced in API endpoints. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `assistant_id: string` - - `completed_at: optional number` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `cancelled_at: number` - - `conversation: optional object { id }` + The Unix timestamp (in seconds) for when the run step was cancelled. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `completed_at: number` - - `max_output_tokens: optional number` + The Unix timestamp (in seconds) for when the run step completed. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `created_at: number` - - `max_tool_calls: optional number` + The Unix timestamp (in seconds) for when the run step was created. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `expired_at: number` - - `moderation: optional object { input, output }` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - Moderation results for the response input and output, if moderated completions were requested. + - `failed_at: number` - - `previous_response_id: optional string` + The Unix timestamp (in seconds) for when the run step failed. - 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`. + - `last_error: object { code, message }` - - `prompt: optional object { id, variables, version }` + The last error associated with this run step. Will be `null` if there are no errors. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `metadata: map[string]` - - `prompt_cache_key: optional string` + 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. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `prompt_cache_options: optional object { mode, ttl }` + - `object: "thread.run.step"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The object type, which is always `thread.run.step`. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `run_id: string` - Deprecated. Use `prompt_cache_options.ttl` instead. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The details of the run step. - **gpt-5 and o-series models only** + - `thread_id: string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `safety_identifier: optional string` + - `type: "message_creation" or "tool_calls"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The type of run step, which can be either `message_creation` or `tool_calls`. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Specifies the processing type used for serving the request. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `event: "thread.run.step.expired"` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. +### Run Stream Event - - `status: optional "completed" or "failed" or "in_progress" or 3 more` +- `run_stream_event: object { data, event } or object { data, event } or object { data, event } or 7 more` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - `text: optional object { format, verbosity }` + - `thread.run.created: object { data, event }` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `top_logprobs: optional number` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `id: string` - - `truncation: optional "auto" or "disabled"` + The identifier, which can be referenced in API endpoints. - The truncation strategy to use for the model response. + - `assistant_id: string` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `cancelled_at: number` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The Unix timestamp (in seconds) for when the run was cancelled. - - `user: optional string` + - `completed_at: number` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The Unix timestamp (in seconds) for when the run was completed. - - `sequence_number: number` + - `created_at: number` - The sequence number of this event. + The Unix timestamp (in seconds) for when the run was created. - - `type: "response.in_progress"` + - `expires_at: number` - The type of the event. Always `response.in_progress`. + The Unix timestamp (in seconds) for when the run will expire. - - `agent: optional object { agent_name }` + - `failed_at: number` - The agent that owns this multi-agent streaming event. + The Unix timestamp (in seconds) for when the run failed. - - `agent_name: string` + - `incomplete_details: object { reason }` - The canonical name of the agent that produced this item. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `beta_response_failed_event: object { response, sequence_number, type, agent }` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - An event that is emitted when a response fails. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `response: object { id, created_at, error, 31 more }` + - `"max_completion_tokens"` - The response that failed. + - `"max_prompt_tokens"` - - `id: string` + - `instructions: string` - Unique identifier for this Response. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `created_at: number` + - `last_error: object { code, message }` - Unix timestamp (in seconds) of when this Response was created. + The last error associated with this run. Will be `null` if there are no errors. - - `error: object { code, message }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - An error object returned when the model fails to generate a Response. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `incomplete_details: object { reason }` + - `"server_error"` - Details about why the response is incomplete. + - `"rate_limit_exceeded"` - - `instructions: string or array of BetaResponseInputItem` + - `"invalid_prompt"` - A system (or developer) message inserted into the model's context. + - `message: string` - When using 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. + A human-readable description of the error. + + - `max_completion_tokens: number` + + The maximum number of completion tokens specified to have been used over the course of the run. + + - `max_prompt_tokens: number` + + The maximum number of prompt tokens specified to have been used over the course of the run. - `metadata: map[string]` @@ -136534,10447 +148581,11091 @@ openai beta:responses compact \ Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - Model ID used to generate the response, like `gpt-4o` 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. - - - `object: "response"` - - The object type of this resource - always set to `response`. + - `model: string` - - `output: array of BetaResponseOutputItem` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - An array of content items generated by the model. + - `object: "thread.run"` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + The object type, which is always `thread.run`. - `parallel_tool_calls: boolean` - Whether to allow the model to run tool calls in parallel. - - - `temperature: number` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. - - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `tools: array of BetaTool` + - `required_action: object { submit_tool_outputs, type }` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + Details on the action required to continue the run. Will be `null` if no action is required. - We support the following categories of tools: + - `submit_tool_outputs: object { tool_calls }` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + Details on the tool outputs needed for this run to continue. - - `top_p: number` + - `tool_calls: array of RequiredActionFunctionToolCall` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + A list of the relevant tool calls. - We generally recommend altering this or `temperature` but not both. + - `id: string` - - `background: optional boolean` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `function: object { arguments, name }` - - `completed_at: optional number` + The function definition. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `arguments: string` - - `conversation: optional object { id }` + The arguments that the model expects you to pass to the function. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `name: string` - - `max_output_tokens: optional number` + The name of the function. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + - `type: "function"` - - `max_tool_calls: optional number` + The type of tool call the output is required for. For now, this is always `function`. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `type: "submit_tool_outputs"` - - `moderation: optional object { input, output }` + For now, this is always `submit_tool_outputs`. - Moderation results for the response input and output, if moderated completions were requested. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `previous_response_id: optional string` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - 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`. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `prompt: optional object { id, variables, version }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `prompt_cache_key: optional string` + - `union_member_0: "auto"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + `auto` is the default value - - `prompt_cache_options: optional object { mode, ttl }` + - `response_format_text: object { type }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + Default response format. Used to generate text responses. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `type: "text"` - Deprecated. Use `prompt_cache_options.ttl` instead. + The type of response format being defined. Always `text`. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `response_format_json_object: object { type }` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: "json_object"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The type of response format being defined. Always `json_object`. - **gpt-5 and o-series models only** + - `response_format_json_schema: object { json_schema, type }` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `safety_identifier: optional string` + - `json_schema: object { name, description, schema, strict }` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + Structured Outputs configuration options, including a JSON Schema. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `name: string` - Specifies the processing type used for serving the request. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `description: optional string` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `schema: optional map[unknown]` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `text: optional object { format, verbosity }` + - `strict: optional boolean` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `type: "json_schema"` - - `top_logprobs: optional number` + The type of response format being defined. Always `json_schema`. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `started_at: number` - - `truncation: optional "auto" or "disabled"` + The Unix timestamp (in seconds) for when the run was started. - The truncation strategy to use for the model response. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `"queued"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `"in_progress"` - - `user: optional string` + - `"requires_action"` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `"cancelling"` - - `sequence_number: number` + - `"cancelled"` - The sequence number of this event. + - `"failed"` - - `type: "response.failed"` + - `"completed"` - The type of the event. Always `response.failed`. + - `"incomplete"` - - `agent: optional object { agent_name }` + - `"expired"` - The agent that owns this multi-agent streaming event. + - `thread_id: string` - - `agent_name: string` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The canonical name of the agent that produced this item. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `beta_response_incomplete_event: object { response, sequence_number, type, agent }` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - An event that is emitted when a response finishes as incomplete. + - `Auto: "none" or "auto" or "required"` - - `response: object { id, created_at, error, 31 more }` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - The response that was incomplete. + - `"none"` - - `id: string` + - `"auto"` - Unique identifier for this Response. + - `"required"` - - `created_at: number` + - `assistant_tool_choice: object { type, function }` - Unix timestamp (in seconds) of when this Response was created. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `error: object { code, message }` + - `type: "function" or "code_interpreter" or "file_search"` - An error object returned when the model fails to generate a Response. + The type of the tool. If type is `function`, the function name must be set - - `incomplete_details: object { reason }` + - `"function"` - Details about why the response is incomplete. + - `"code_interpreter"` - - `instructions: string or array of BetaResponseInputItem` + - `"file_search"` - A system (or developer) message inserted into the model's context. + - `function: optional object { name }` - When using 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. + - `name: string` - - `metadata: map[string]` + The name of the function to call. - 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. + - `tools: array of AssistantTool` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `code_interpreter_tool: object { type }` - Model ID used to generate the response, like `gpt-4o` 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. + - `type: "code_interpreter"` - - `object: "response"` + The type of tool being defined: `code_interpreter` - The object type of this resource - always set to `response`. + - `file_search_tool: object { type, file_search }` - - `output: array of BetaResponseOutputItem` + - `type: "file_search"` - An array of content items generated by the model. + The type of tool being defined: `file_search` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `file_search: optional object { max_num_results, ranking_options }` - - `parallel_tool_calls: boolean` + Overrides for the file search tool. - Whether to allow the model to run tool calls in parallel. + - `max_num_results: optional number` - - `temperature: number` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `ranking_options: optional object { score_threshold, ranker }` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `tools: array of BetaTool` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `score_threshold: number` - We support the following categories of tools: + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `ranker: optional "auto" or "default_2024_08_21"` - - `top_p: number` + The ranker to use for the file search. If not specified will use the `auto` ranker. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `"auto"` - We generally recommend altering this or `temperature` but not both. + - `"default_2024_08_21"` - - `background: optional boolean` + - `function_tool: object { function, type }` - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). + - `function: object { name, description, parameters, strict }` - - `completed_at: optional number` + - `name: string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `conversation: optional object { id }` + - `description: optional string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A description of what the function does, used by the model to choose when and how to call the function. - - `max_output_tokens: optional number` + - `parameters: optional map[unknown]` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `max_tool_calls: optional number` + Omitting `parameters` defines a function with an empty parameter list. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `strict: optional boolean` - - `moderation: optional object { input, output }` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - Moderation results for the response input and output, if moderated completions were requested. + - `type: "function"` - - `previous_response_id: optional string` + The type of tool being defined: `function` - 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`. + - `truncation_strategy: object { type, last_messages }` - - `prompt: optional object { id, variables, version }` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + - `type: "auto" or "last_messages"` - - `prompt_cache_key: optional string` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `"auto"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"last_messages"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `last_messages: optional number` - - `prompt_cache_retention: optional "in_memory" or "24h"` + The number of most recent messages from the thread when constructing the context for the run. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `completion_tokens: number` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Number of completion tokens used over the course of the run. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `prompt_tokens: number` - **gpt-5 and o-series models only** + Number of prompt tokens used over the course of the run. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `total_tokens: number` - - `safety_identifier: optional string` + Total number of tokens used (prompt + completion). - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + - `temperature: optional number` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The sampling temperature used for this run. If not set, defaults to 1. - Specifies the processing type used for serving the request. + - `top_p: optional number` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The nucleus sampling value used for this run. If not set, defaults to 1. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `event: "thread.run.created"` - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `thread.run.queued: object { data, event }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - - `text: optional object { format, verbosity }` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `id: string` - - `top_logprobs: optional number` + The identifier, which can be referenced in API endpoints. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `assistant_id: string` - - `truncation: optional "auto" or "disabled"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The truncation strategy to use for the model response. + - `cancelled_at: number` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The Unix timestamp (in seconds) for when the run was cancelled. - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `completed_at: number` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The Unix timestamp (in seconds) for when the run was completed. - - `user: optional string` + - `created_at: number` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The Unix timestamp (in seconds) for when the run was created. - - `sequence_number: number` + - `expires_at: number` - The sequence number of this event. + The Unix timestamp (in seconds) for when the run will expire. - - `type: "response.incomplete"` + - `failed_at: number` - The type of the event. Always `response.incomplete`. + The Unix timestamp (in seconds) for when the run failed. - - `agent: optional object { agent_name }` + - `incomplete_details: object { reason }` - The agent that owns this multi-agent streaming event. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `agent_name: string` + - `instructions: string` - The canonical name of the agent that produced this item. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `beta_response_output_item_added_event: object { item, output_index, sequence_number, 2 more }` + - `last_error: object { code, message }` - Emitted when a new output item is added. + The last error associated with this run. Will be `null` if there are no errors. - - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` + - `max_completion_tokens: number` - The output item that was added. + The maximum number of completion tokens specified to have been used over the course of the run. - - `beta_response_output_message: object { id, content, role, 4 more }` + - `max_prompt_tokens: number` - An output message from the model. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `metadata: map[string]` - 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. + 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. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `model: string` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `agent_message: object { id, author, content, 3 more }` + - `object: "thread.run"` - - `multi_agent_call: object { id, action, arguments, 3 more }` + The object type, which is always `thread.run`. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `parallel_tool_calls: boolean` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - 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. + - `required_action: object { submit_tool_outputs, type }` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + Details on the action required to continue the run. Will be `null` if no action is required. - 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. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - 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). + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `program: object { id, call_id, code, 3 more }` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `program_output: object { id, call_id, result, 3 more }` + - `started_at: number` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + The Unix timestamp (in seconds) for when the run was started. - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `additional_tools: object { id, role, tools, 2 more }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `thread_id: string` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `image_generation_call: object { id, result, status, 2 more }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - An image generation request made by the model. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `tools: array of AssistantTool` - A tool call to run code. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `truncation_strategy: object { type, last_messages }` - A tool call to run a command on the local shell. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The output of a local shell tool call. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `temperature: optional number` - A tool call that executes one or more shell commands in a managed environment. + The sampling temperature used for this run. If not set, defaults to 1. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `top_p: optional number` - The output of a shell tool call that was emitted. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `event: "thread.run.queued"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `thread.run.in_progress: object { data, event }` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - The output emitted by an apply patch tool call. + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `mcp_call: object { id, arguments, name, 7 more }` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - An invocation of a tool on an MCP server. + - `id: string` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + The identifier, which can be referenced in API endpoints. - A list of tools available on an MCP server. + - `assistant_id: string` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - A request for human approval of a tool invocation. + - `cancelled_at: number` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + The Unix timestamp (in seconds) for when the run was cancelled. - A response to an MCP approval request. + - `completed_at: number` - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + The Unix timestamp (in seconds) for when the run was completed. - A call to a custom tool created by the model. + - `created_at: number` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The Unix timestamp (in seconds) for when the run was created. - The output of a custom tool call from your code, being sent back to the model. + - `expires_at: number` - - `output_index: number` + The Unix timestamp (in seconds) for when the run will expire. - The index of the output item that was added. + - `failed_at: number` - - `sequence_number: number` + The Unix timestamp (in seconds) for when the run failed. - The sequence number of this event. + - `incomplete_details: object { reason }` - - `type: "response.output_item.added"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The type of the event. Always `response.output_item.added`. + - `instructions: string` - - `agent: optional object { agent_name }` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The agent that owns this multi-agent streaming event. + - `last_error: object { code, message }` - - `agent_name: string` + The last error associated with this run. Will be `null` if there are no errors. - The canonical name of the agent that produced this item. + - `max_completion_tokens: number` - - `beta_response_output_item_done_event: object { item, output_index, sequence_number, 2 more }` + The maximum number of completion tokens specified to have been used over the course of the run. - Emitted when an output item is marked done. + - `max_prompt_tokens: number` - - `item: BetaResponseOutputMessage or BetaResponseFileSearchToolCall or BetaResponseFunctionToolCall or 28 more` + The maximum number of prompt tokens specified to have been used over the course of the run. - The output item that was marked done. + - `metadata: map[string]` - - `beta_response_output_message: object { id, content, role, 4 more }` + 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. - An output message from the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `model: string` - 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. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `object: "thread.run"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + The object type, which is always `thread.run`. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `parallel_tool_calls: boolean` - - `agent_message: object { id, author, content, 3 more }` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `required_action: object { submit_tool_outputs, type }` - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + Details on the action required to continue the run. Will be `null` if no action is required. - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - 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. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - 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. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `started_at: number` - 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). + The Unix timestamp (in seconds) for when the run was started. - - `program: object { id, call_id, code, 3 more }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `program_output: object { id, call_id, result, 3 more }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `thread_id: string` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `additional_tools: object { id, role, tools, 2 more }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `tools: array of AssistantTool` - - `image_generation_call: object { id, result, status, 2 more }` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - An image generation request made by the model. + - `truncation_strategy: object { type, last_messages }` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - A tool call to run code. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `local_shell_call: object { id, action, call_id, 3 more }` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - A tool call to run a command on the local shell. + - `temperature: optional number` - - `local_shell_call_output: object { id, output, type, 2 more }` + The sampling temperature used for this run. If not set, defaults to 1. - The output of a local shell tool call. + - `top_p: optional number` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + The nucleus sampling value used for this run. If not set, defaults to 1. - A tool call that executes one or more shell commands in a managed environment. + - `event: "thread.run.in_progress"` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + - `thread.run.requires_action: object { data, event }` - The output of a shell tool call that was emitted. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - A tool call that applies file diffs by creating, deleting, or updating files. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `id: string` - The output emitted by an apply patch tool call. + The identifier, which can be referenced in API endpoints. - - `mcp_call: object { id, arguments, name, 7 more }` + - `assistant_id: string` - An invocation of a tool on an MCP server. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `cancelled_at: number` - A list of tools available on an MCP server. + The Unix timestamp (in seconds) for when the run was cancelled. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `completed_at: number` - A request for human approval of a tool invocation. + The Unix timestamp (in seconds) for when the run was completed. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `created_at: number` - A response to an MCP approval request. + The Unix timestamp (in seconds) for when the run was created. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `expires_at: number` - A call to a custom tool created by the model. + The Unix timestamp (in seconds) for when the run will expire. - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + - `failed_at: number` - The output of a custom tool call from your code, being sent back to the model. + The Unix timestamp (in seconds) for when the run failed. - - `output_index: number` + - `incomplete_details: object { reason }` - The index of the output item that was marked done. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `sequence_number: number` + - `instructions: string` - The sequence number of this event. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: "response.output_item.done"` + - `last_error: object { code, message }` - The type of the event. Always `response.output_item.done`. + The last error associated with this run. Will be `null` if there are no errors. - - `agent: optional object { agent_name }` + - `max_completion_tokens: number` - The agent that owns this multi-agent streaming event. + The maximum number of completion tokens specified to have been used over the course of the run. - - `agent_name: string` + - `max_prompt_tokens: number` - The canonical name of the agent that produced this item. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `beta_response_reasoning_summary_part_added_event: object { item_id, output_index, part, 4 more }` + - `metadata: map[string]` - Emitted when a new reasoning summary part is added. + 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. - - `item_id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The ID of the item this summary part is associated with. + - `model: string` - - `output_index: number` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The index of the output item this summary part is associated with. + - `object: "thread.run"` - - `part: object { text, type }` + The object type, which is always `thread.run`. - The summary part that was added. + - `parallel_tool_calls: boolean` - - `text: string` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The text of the summary part. + - `required_action: object { submit_tool_outputs, type }` - - `type: "summary_text"` + Details on the action required to continue the run. Will be `null` if no action is required. - The type of the summary part. Always `summary_text`. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `sequence_number: number` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The sequence number of this event. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `summary_index: number` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The index of the summary part within the reasoning summary. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `type: "response.reasoning_summary_part.added"` + - `started_at: number` - The type of the event. Always `response.reasoning_summary_part.added`. + The Unix timestamp (in seconds) for when the run was started. - - `agent: optional object { agent_name }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The agent that owns this multi-agent streaming event. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `agent_name: string` + - `thread_id: string` - The canonical name of the agent that produced this item. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `beta_response_reasoning_summary_part_done_event: object { item_id, output_index, part, 5 more }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - Emitted when a reasoning summary part is completed. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `item_id: string` + - `tools: array of AssistantTool` - The ID of the item this summary part is associated with. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `output_index: number` + - `truncation_strategy: object { type, last_messages }` - The index of the output item this summary part is associated with. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `part: object { text, type }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The completed summary part. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `text: string` + - `temperature: optional number` - The text of the summary part. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: "summary_text"` + - `top_p: optional number` - The type of the summary part. Always `summary_text`. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `sequence_number: number` + - `event: "thread.run.requires_action"` - The sequence number of this event. + - `thread.run.completed: object { data, event }` - - `summary_index: number` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - The index of the summary part within the reasoning summary. + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `type: "response.reasoning_summary_part.done"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The type of the event. Always `response.reasoning_summary_part.done`. + - `id: string` - - `agent: optional object { agent_name }` + The identifier, which can be referenced in API endpoints. - The agent that owns this multi-agent streaming event. + - `assistant_id: string` - - `agent_name: string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The canonical name of the agent that produced this item. + - `cancelled_at: number` - - `status: optional "incomplete"` + The Unix timestamp (in seconds) for when the run was cancelled. - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `completed_at: number` - - `"incomplete"` + The Unix timestamp (in seconds) for when the run was completed. - - `beta_response_reasoning_summary_text_delta_event: object { delta, item_id, output_index, 4 more }` + - `created_at: number` - Emitted when a delta is added to a reasoning summary text. + The Unix timestamp (in seconds) for when the run was created. - - `delta: string` + - `expires_at: number` - The text delta that was added to the summary. + The Unix timestamp (in seconds) for when the run will expire. - - `item_id: string` + - `failed_at: number` - The ID of the item this summary text delta is associated with. + The Unix timestamp (in seconds) for when the run failed. - - `output_index: number` + - `incomplete_details: object { reason }` - The index of the output item this summary text delta is associated with. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `sequence_number: number` + - `instructions: string` - The sequence number of this event. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `summary_index: number` + - `last_error: object { code, message }` - The index of the summary part within the reasoning summary. + The last error associated with this run. Will be `null` if there are no errors. - - `type: "response.reasoning_summary_text.delta"` + - `max_completion_tokens: number` - The type of the event. Always `response.reasoning_summary_text.delta`. + The maximum number of completion tokens specified to have been used over the course of the run. - - `agent: optional object { agent_name }` + - `max_prompt_tokens: number` - The agent that owns this multi-agent streaming event. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `agent_name: string` + - `metadata: map[string]` - The canonical name of the agent that produced this item. + 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. - - `beta_response_reasoning_summary_text_done_event: object { item_id, output_index, sequence_number, 4 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Emitted when a reasoning summary text is completed. + - `model: string` - - `item_id: string` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The ID of the item this summary text is associated with. + - `object: "thread.run"` - - `output_index: number` + The object type, which is always `thread.run`. - The index of the output item this summary text is associated with. + - `parallel_tool_calls: boolean` - - `sequence_number: number` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The sequence number of this event. + - `required_action: object { submit_tool_outputs, type }` - - `summary_index: number` + Details on the action required to continue the run. Will be `null` if no action is required. - The index of the summary part within the reasoning summary. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `text: string` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The full text of the completed reasoning summary. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `type: "response.reasoning_summary_text.done"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The type of the event. Always `response.reasoning_summary_text.done`. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `agent: optional object { agent_name }` + - `started_at: number` - The agent that owns this multi-agent streaming event. + The Unix timestamp (in seconds) for when the run was started. - - `agent_name: string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The canonical name of the agent that produced this item. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `beta_response_reasoning_text_delta_event: object { content_index, delta, item_id, 4 more }` + - `thread_id: string` - Emitted when a delta is added to a reasoning text. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `content_index: number` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - The index of the reasoning content part this delta is associated with. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `delta: string` + - `tools: array of AssistantTool` - The text delta that was added to the reasoning content. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `item_id: string` + - `truncation_strategy: object { type, last_messages }` - The ID of the item this reasoning text delta is associated with. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `output_index: number` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The index of the output item this reasoning text delta is associated with. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `sequence_number: number` + - `temperature: optional number` - The sequence number of this event. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: "response.reasoning_text.delta"` + - `top_p: optional number` - The type of the event. Always `response.reasoning_text.delta`. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `agent: optional object { agent_name }` + - `event: "thread.run.completed"` - The agent that owns this multi-agent streaming event. + - `thread.run.incomplete: object { data, event }` - - `agent_name: string` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - The canonical name of the agent that produced this item. + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `beta_response_reasoning_text_done_event: object { content_index, item_id, output_index, 4 more }` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - Emitted when a reasoning text is completed. + - `id: string` - - `content_index: number` + The identifier, which can be referenced in API endpoints. - The index of the reasoning content part. + - `assistant_id: string` - - `item_id: string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The ID of the item this reasoning text is associated with. + - `cancelled_at: number` - - `output_index: number` + The Unix timestamp (in seconds) for when the run was cancelled. - The index of the output item this reasoning text is associated with. + - `completed_at: number` - - `sequence_number: number` + The Unix timestamp (in seconds) for when the run was completed. - The sequence number of this event. + - `created_at: number` - - `text: string` + The Unix timestamp (in seconds) for when the run was created. - The full text of the completed reasoning content. + - `expires_at: number` - - `type: "response.reasoning_text.done"` + The Unix timestamp (in seconds) for when the run will expire. - The type of the event. Always `response.reasoning_text.done`. + - `failed_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run failed. - The agent that owns this multi-agent streaming event. + - `incomplete_details: object { reason }` - - `agent_name: string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The canonical name of the agent that produced this item. + - `instructions: string` - - `beta_response_refusal_delta_event: object { content_index, delta, item_id, 4 more }` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Emitted when there is a partial refusal text. + - `last_error: object { code, message }` - - `content_index: number` + The last error associated with this run. Will be `null` if there are no errors. - The index of the content part that the refusal text is added to. + - `max_completion_tokens: number` - - `delta: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The refusal text that is added. + - `max_prompt_tokens: number` - - `item_id: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The ID of the output item that the refusal text is added to. + - `metadata: map[string]` - - `output_index: number` + 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. - The index of the output item that the refusal text is added to. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `sequence_number: number` + - `model: string` - The sequence number of this event. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: "response.refusal.delta"` + - `object: "thread.run"` - The type of the event. Always `response.refusal.delta`. + The object type, which is always `thread.run`. - - `agent: optional object { agent_name }` + - `parallel_tool_calls: boolean` - The agent that owns this multi-agent streaming event. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `agent_name: string` + - `required_action: object { submit_tool_outputs, type }` - The canonical name of the agent that produced this item. + Details on the action required to continue the run. Will be `null` if no action is required. - - `beta_response_refusal_done_event: object { content_index, item_id, output_index, 4 more }` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - Emitted when refusal text is finalized. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `content_index: number` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The index of the content part that the refusal text is finalized. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `item_id: string` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The ID of the output item that the refusal text is finalized. + - `started_at: number` - - `output_index: number` + The Unix timestamp (in seconds) for when the run was started. - The index of the output item that the refusal text is finalized. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `refusal: string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The refusal text that is finalized. + - `thread_id: string` - - `sequence_number: number` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The sequence number of this event. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `type: "response.refusal.done"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of the event. Always `response.refusal.done`. + - `tools: array of AssistantTool` - - `agent: optional object { agent_name }` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The agent that owns this multi-agent streaming event. + - `truncation_strategy: object { type, last_messages }` - - `agent_name: string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The canonical name of the agent that produced this item. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `beta_response_text_delta_event: object { content_index, delta, item_id, 5 more }` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - Emitted when there is an additional text delta. + - `temperature: optional number` + + The sampling temperature used for this run. If not set, defaults to 1. + + - `top_p: optional number` + + The nucleus sampling value used for this run. If not set, defaults to 1. - - `content_index: number` + - `event: "thread.run.incomplete"` - The index of the content part that the text delta was added to. + - `thread.run.failed: object { data, event }` - - `delta: string` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - The text delta that was added. + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `item_id: string` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The ID of the output item that the text delta was added to. + - `id: string` - - `logprobs: array of object { token, logprob, top_logprobs }` + The identifier, which can be referenced in API endpoints. - The log probabilities of the tokens in the delta. + - `assistant_id: string` - - `token: string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - A possible text token. + - `cancelled_at: number` - - `logprob: number` + The Unix timestamp (in seconds) for when the run was cancelled. - The log probability of this token. + - `completed_at: number` - - `top_logprobs: optional array of object { token, logprob }` + The Unix timestamp (in seconds) for when the run was completed. - The log probabilities of up to 20 of the most likely tokens. + - `created_at: number` - - `token: optional string` + The Unix timestamp (in seconds) for when the run was created. - A possible text token. + - `expires_at: number` - - `logprob: optional number` + The Unix timestamp (in seconds) for when the run will expire. - The log probability of this token. + - `failed_at: number` - - `output_index: number` + The Unix timestamp (in seconds) for when the run failed. - The index of the output item that the text delta was added to. + - `incomplete_details: object { reason }` - - `sequence_number: number` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The sequence number for this event. + - `instructions: string` - - `type: "response.output_text.delta"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the event. Always `response.output_text.delta`. + - `last_error: object { code, message }` - - `agent: optional object { agent_name }` + The last error associated with this run. Will be `null` if there are no errors. - The agent that owns this multi-agent streaming event. + - `max_completion_tokens: number` - - `agent_name: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The canonical name of the agent that produced this item. + - `max_prompt_tokens: number` - - `beta_response_text_done_event: object { content_index, item_id, logprobs, 5 more }` + The maximum number of prompt tokens specified to have been used over the course of the run. - Emitted when text content is finalized. + - `metadata: map[string]` - - `content_index: number` + 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. - The index of the content part that the text content is finalized. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `item_id: string` + - `model: string` - The ID of the output item that the text content is finalized. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `logprobs: array of object { token, logprob, top_logprobs }` + - `object: "thread.run"` - The log probabilities of the tokens in the delta. + The object type, which is always `thread.run`. - - `token: string` + - `parallel_tool_calls: boolean` - A possible text token. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `logprob: number` + - `required_action: object { submit_tool_outputs, type }` - The log probability of this token. + Details on the action required to continue the run. Will be `null` if no action is required. - - `top_logprobs: optional array of object { token, logprob }` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The log probabilities of up to 20 of the most likely tokens. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `token: optional string` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - A possible text token. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `logprob: optional number` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The log probability of this token. + - `started_at: number` - - `output_index: number` + The Unix timestamp (in seconds) for when the run was started. - The index of the output item that the text content is finalized. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `sequence_number: number` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The sequence number for this event. + - `thread_id: string` - - `text: string` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The text content that is finalized. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `type: "response.output_text.done"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of the event. Always `response.output_text.done`. + - `tools: array of AssistantTool` - - `agent: optional object { agent_name }` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The agent that owns this multi-agent streaming event. + - `truncation_strategy: object { type, last_messages }` - - `agent_name: string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The canonical name of the agent that produced this item. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `beta_response_web_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - Emitted when a web search call is completed. + - `temperature: optional number` - - `item_id: string` + The sampling temperature used for this run. If not set, defaults to 1. - Unique ID for the output item associated with the web search call. + - `top_p: optional number` - - `output_index: number` + The nucleus sampling value used for this run. If not set, defaults to 1. - The index of the output item that the web search call is associated with. + - `event: "thread.run.failed"` - - `sequence_number: number` + - `thread.run.cancelling: object { data, event }` - The sequence number of the web search call being processed. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - - `type: "response.web_search_call.completed"` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - The type of the event. Always `response.web_search_call.completed`. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `agent: optional object { agent_name }` + - `id: string` - The agent that owns this multi-agent streaming event. + The identifier, which can be referenced in API endpoints. - - `agent_name: string` + - `assistant_id: string` - The canonical name of the agent that produced this item. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `beta_response_web_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + - `cancelled_at: number` - Emitted when a web search call is initiated. + The Unix timestamp (in seconds) for when the run was cancelled. - - `item_id: string` + - `completed_at: number` - Unique ID for the output item associated with the web search call. + The Unix timestamp (in seconds) for when the run was completed. - - `output_index: number` + - `created_at: number` - The index of the output item that the web search call is associated with. + The Unix timestamp (in seconds) for when the run was created. - - `sequence_number: number` + - `expires_at: number` - The sequence number of the web search call being processed. + The Unix timestamp (in seconds) for when the run will expire. - - `type: "response.web_search_call.in_progress"` + - `failed_at: number` - The type of the event. Always `response.web_search_call.in_progress`. + The Unix timestamp (in seconds) for when the run failed. - - `agent: optional object { agent_name }` + - `incomplete_details: object { reason }` - The agent that owns this multi-agent streaming event. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `agent_name: string` + - `instructions: string` - The canonical name of the agent that produced this item. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `beta_response_web_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }` + - `last_error: object { code, message }` - Emitted when a web search call is executing. + The last error associated with this run. Will be `null` if there are no errors. - - `item_id: string` + - `max_completion_tokens: number` - Unique ID for the output item associated with the web search call. + The maximum number of completion tokens specified to have been used over the course of the run. - - `output_index: number` + - `max_prompt_tokens: number` - The index of the output item that the web search call is associated with. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `sequence_number: number` + - `metadata: map[string]` - The sequence number of the web search call being processed. + 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. - - `type: "response.web_search_call.searching"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the event. Always `response.web_search_call.searching`. + - `model: string` - - `agent: optional object { agent_name }` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The agent that owns this multi-agent streaming event. + - `object: "thread.run"` - - `agent_name: string` + The object type, which is always `thread.run`. - The canonical name of the agent that produced this item. + - `parallel_tool_calls: boolean` - - `beta_response_image_gen_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - Emitted when an image generation tool call has completed and the final image is available. + - `required_action: object { submit_tool_outputs, type }` - - `item_id: string` + Details on the action required to continue the run. Will be `null` if no action is required. - The unique identifier of the image generation item being processed. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `output_index: number` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The index of the output item in the response's output array. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `sequence_number: number` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The sequence number of this event. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `type: "response.image_generation_call.completed"` + - `started_at: number` - The type of the event. Always 'response.image_generation_call.completed'. + The Unix timestamp (in seconds) for when the run was started. - - `agent: optional object { agent_name }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The agent that owns this multi-agent streaming event. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `agent_name: string` + - `thread_id: string` - The canonical name of the agent that produced this item. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `beta_response_image_gen_call_generating_event: object { item_id, output_index, sequence_number, 2 more }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - Emitted when an image generation tool call is actively generating an image (intermediate state). + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `item_id: string` + - `tools: array of AssistantTool` - The unique identifier of the image generation item being processed. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `output_index: number` + - `truncation_strategy: object { type, last_messages }` - The index of the output item in the response's output array. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `sequence_number: number` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The sequence number of the image generation item being processed. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `type: "response.image_generation_call.generating"` + - `temperature: optional number` - The type of the event. Always 'response.image_generation_call.generating'. + The sampling temperature used for this run. If not set, defaults to 1. - - `agent: optional object { agent_name }` + - `top_p: optional number` - The agent that owns this multi-agent streaming event. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `agent_name: string` + - `event: "thread.run.cancelling"` - The canonical name of the agent that produced this item. + - `thread.run.cancelled: object { data, event }` - - `beta_response_image_gen_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - Emitted when an image generation tool call is in progress. + - `data: object { id, assistant_id, cancelled_at, 24 more }` - - `item_id: string` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The unique identifier of the image generation item being processed. + - `id: string` - - `output_index: number` + The identifier, which can be referenced in API endpoints. - The index of the output item in the response's output array. + - `assistant_id: string` - - `sequence_number: number` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The sequence number of the image generation item being processed. + - `cancelled_at: number` - - `type: "response.image_generation_call.in_progress"` + The Unix timestamp (in seconds) for when the run was cancelled. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `completed_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run was completed. - The agent that owns this multi-agent streaming event. + - `created_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the run was created. - The canonical name of the agent that produced this item. + - `expires_at: number` - - `beta_response_image_gen_call_partial_image_event: object { item_id, output_index, partial_image_b64, 4 more }` + The Unix timestamp (in seconds) for when the run will expire. - Emitted when a partial image is available during image generation streaming. + - `failed_at: number` - - `item_id: string` + The Unix timestamp (in seconds) for when the run failed. - The unique identifier of the image generation item being processed. + - `incomplete_details: object { reason }` - - `output_index: number` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The index of the output item in the response's output array. + - `instructions: string` - - `partial_image_b64: string` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Base64-encoded partial image data, suitable for rendering as an image. + - `last_error: object { code, message }` - - `partial_image_index: number` + The last error associated with this run. Will be `null` if there are no errors. - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `max_completion_tokens: number` - - `sequence_number: number` + The maximum number of completion tokens specified to have been used over the course of the run. - The sequence number of the image generation item being processed. + - `max_prompt_tokens: number` - - `type: "response.image_generation_call.partial_image"` + The maximum number of prompt tokens specified to have been used over the course of the run. - The type of the event. Always 'response.image_generation_call.partial_image'. + - `metadata: map[string]` - - `agent: optional object { agent_name }` + 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. - The agent that owns this multi-agent streaming event. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `agent_name: string` + - `model: string` - The canonical name of the agent that produced this item. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `beta_response_mcp_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }` + - `object: "thread.run"` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + The object type, which is always `thread.run`. - - `delta: string` + - `parallel_tool_calls: boolean` - A JSON string containing the partial update to the arguments for the MCP tool call. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `item_id: string` + - `required_action: object { submit_tool_outputs, type }` - The unique identifier of the MCP tool call item being processed. + Details on the action required to continue the run. Will be `null` if no action is required. - - `output_index: number` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The index of the output item in the response's output array. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `sequence_number: number` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The sequence number of this event. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `type: "response.mcp_call_arguments.delta"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `started_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run was started. - The agent that owns this multi-agent streaming event. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `agent_name: string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The canonical name of the agent that produced this item. + - `thread_id: string` - - `beta_response_mcp_call_arguments_done_event: object { arguments, item_id, output_index, 3 more }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - Emitted when the arguments for an MCP tool call are finalized. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `arguments: string` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - A JSON string containing the finalized arguments for the MCP tool call. + - `tools: array of AssistantTool` - - `item_id: string` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The unique identifier of the MCP tool call item being processed. + - `truncation_strategy: object { type, last_messages }` - - `output_index: number` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The index of the output item in the response's output array. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `sequence_number: number` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The sequence number of this event. + - `temperature: optional number` - - `type: "response.mcp_call_arguments.done"` + The sampling temperature used for this run. If not set, defaults to 1. - The type of the event. Always 'response.mcp_call_arguments.done'. + - `top_p: optional number` - - `agent: optional object { agent_name }` + The nucleus sampling value used for this run. If not set, defaults to 1. - The agent that owns this multi-agent streaming event. + - `event: "thread.run.cancelled"` - - `agent_name: string` + - `thread.run.expired: object { data, event }` - The canonical name of the agent that produced this item. + Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - - `beta_response_mcp_call_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `data: object { id, assistant_id, cancelled_at, 24 more }` - Emitted when an MCP tool call has completed successfully. + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - `item_id: string` + - `id: string` - The ID of the MCP tool call item that completed. + The identifier, which can be referenced in API endpoints. - - `output_index: number` + - `assistant_id: string` - The index of the output item that completed. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `sequence_number: number` + - `cancelled_at: number` - The sequence number of this event. + The Unix timestamp (in seconds) for when the run was cancelled. - - `type: "response.mcp_call.completed"` + - `completed_at: number` - The type of the event. Always 'response.mcp_call.completed'. + The Unix timestamp (in seconds) for when the run was completed. - - `agent: optional object { agent_name }` + - `created_at: number` - The agent that owns this multi-agent streaming event. + The Unix timestamp (in seconds) for when the run was created. - - `agent_name: string` + - `expires_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run will expire. - - `beta_response_mcp_call_failed_event: object { item_id, output_index, sequence_number, 2 more }` + - `failed_at: number` - Emitted when an MCP tool call has failed. + The Unix timestamp (in seconds) for when the run failed. - - `item_id: string` + - `incomplete_details: object { reason }` - The ID of the MCP tool call item that failed. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `output_index: number` + - `instructions: string` - The index of the output item that failed. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `sequence_number: number` + - `last_error: object { code, message }` - The sequence number of this event. + The last error associated with this run. Will be `null` if there are no errors. - - `type: "response.mcp_call.failed"` + - `max_completion_tokens: number` - The type of the event. Always 'response.mcp_call.failed'. + The maximum number of completion tokens specified to have been used over the course of the run. - - `agent: optional object { agent_name }` + - `max_prompt_tokens: number` - The agent that owns this multi-agent streaming event. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `agent_name: string` + - `metadata: map[string]` - The canonical name of the agent that produced this item. + 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. - - `beta_response_mcp_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Emitted when an MCP tool call is in progress. + - `model: string` - - `item_id: string` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The unique identifier of the MCP tool call item being processed. + - `object: "thread.run"` - - `output_index: number` + The object type, which is always `thread.run`. - The index of the output item in the response's output array. + - `parallel_tool_calls: boolean` - - `sequence_number: number` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The sequence number of this event. + - `required_action: object { submit_tool_outputs, type }` - - `type: "response.mcp_call.in_progress"` + Details on the action required to continue the run. Will be `null` if no action is required. - The type of the event. Always 'response.mcp_call.in_progress'. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `agent: optional object { agent_name }` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The agent that owns this multi-agent streaming event. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `agent_name: string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The canonical name of the agent that produced this item. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `beta_response_mcp_list_tools_completed_event: object { item_id, output_index, sequence_number, 2 more }` + - `started_at: number` - Emitted when the list of available MCP tools has been successfully retrieved. + The Unix timestamp (in seconds) for when the run was started. - - `item_id: string` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The ID of the MCP tool call item that produced this output. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `output_index: number` + - `thread_id: string` - The index of the output item that was processed. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `sequence_number: number` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - The sequence number of this event. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `type: "response.mcp_list_tools.completed"` + - `tools: array of AssistantTool` - The type of the event. Always 'response.mcp_list_tools.completed'. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `agent: optional object { agent_name }` + - `truncation_strategy: object { type, last_messages }` - The agent that owns this multi-agent streaming event. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `agent_name: string` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The canonical name of the agent that produced this item. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `beta_response_mcp_list_tools_failed_event: object { item_id, output_index, sequence_number, 2 more }` + - `temperature: optional number` - Emitted when the attempt to list available MCP tools has failed. + The sampling temperature used for this run. If not set, defaults to 1. - - `item_id: string` + - `top_p: optional number` - The ID of the MCP tool call item that failed. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `output_index: number` + - `event: "thread.run.expired"` - The index of the output item that failed. +### Thread Stream Event - - `sequence_number: number` +- `thread_stream_event: object { data, event, enabled }` - The sequence number of this event. + Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - - `type: "response.mcp_list_tools.failed"` + - `data: object { id, created_at, metadata, 2 more }` - The type of the event. Always 'response.mcp_list_tools.failed'. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `agent: optional object { agent_name }` + - `id: string` - The agent that owns this multi-agent streaming event. + The identifier, which can be referenced in API endpoints. - - `agent_name: string` + - `created_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the thread was created. - - `beta_response_mcp_list_tools_in_progress_event: object { item_id, output_index, sequence_number, 2 more }` + - `metadata: map[string]` - Emitted when the system is in the process of retrieving the list of available MCP tools. + 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. - - `item_id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The ID of the MCP tool call item that is being processed. + - `object: "thread"` - - `output_index: number` + The object type, which is always `thread`. - The index of the output item that is being processed. + - `tool_resources: object { code_interpreter, file_search }` - - `sequence_number: number` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The sequence number of this event. + - `code_interpreter: optional object { file_ids }` - - `type: "response.mcp_list_tools.in_progress"` + - `file_ids: optional array of string` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `agent: optional object { agent_name }` + - `file_search: optional object { vector_store_ids }` - The agent that owns this multi-agent streaming event. + - `vector_store_ids: optional array of string` - - `agent_name: string` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - The canonical name of the agent that produced this item. + - `event: "thread.created"` - - `beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }` + - `enabled: optional boolean` - Emitted when an annotation is added to output text content. + Whether to enable input audio transcription. - - `annotation: unknown` +# Threads - The annotation object being added. (See annotation schema for details.) +## Create thread - - `annotation_index: number` +`$ openai beta:threads create` - The index of the annotation within the content part. +**post** `/threads` - - `content_index: number` +Create a thread. - The index of the content part within the output item. +### Parameters - - `item_id: string` +- `--message: optional array of object { content, role, attachments, metadata }` - The unique identifier of the item to which the annotation is being added. + A list of [messages](https://platform.openai.com/docs/api-reference/messages) to start the thread with. - - `output_index: number` +- `--metadata: optional map[string]` - The index of the output item in the response's output array. + 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. - - `sequence_number: number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The sequence number of this event. +- `--tool-resources: optional object { code_interpreter, file_search }` - - `type: "response.output_text.annotation.added"` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The type of the event. Always 'response.output_text.annotation.added'. +### Returns - - `agent: optional object { agent_name }` +- `thread: object { id, created_at, metadata, 2 more }` - The agent that owns this multi-agent streaming event. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The identifier, which can be referenced in API endpoints. - - `beta_response_queued_event: object { response, sequence_number, type, agent }` + - `created_at: number` - Emitted when a response is queued and waiting to be processed. + The Unix timestamp (in seconds) for when the thread was created. - - `response: object { id, created_at, error, 31 more }` + - `metadata: map[string]` - The full response object that is queued. + 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. - - `id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Unique identifier for this Response. + - `object: "thread"` - - `created_at: number` + The object type, which is always `thread`. - Unix timestamp (in seconds) of when this Response was created. + - `tool_resources: object { code_interpreter, file_search }` - - `error: object { code, message }` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - An error object returned when the model fails to generate a Response. + - `code_interpreter: optional object { file_ids }` - - `incomplete_details: object { reason }` + - `file_ids: optional array of string` - Details about why the response is incomplete. + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `instructions: string or array of BetaResponseInputItem` + - `file_search: optional object { vector_store_ids }` - A system (or developer) message inserted into the model's context. + - `vector_store_ids: optional array of string` - When using 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. + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `metadata: map[string]` +### Example - 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. +```cli +openai beta:threads create \ + --api-key 'My API Key' +``` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. +#### Response - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - Model ID used to generate the response, like `gpt-4o` 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. +## Create thread and run - - `object: "response"` +`$ openai beta:threads create-and-run` - The object type of this resource - always set to `response`. +**post** `/threads/runs` - - `output: array of BetaResponseOutputItem` +Create a thread and run it in one request. - An array of content items generated by the model. +### Parameters - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. +- `--assistant-id: string` - - `parallel_tool_calls: boolean` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - Whether to allow the model to run tool calls in parallel. +- `--instructions: optional string` - - `temperature: number` + Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. +- `--max-completion-tokens: optional number` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. +- `--max-prompt-tokens: optional number` - - `tools: array of BetaTool` + The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. +- `--metadata: optional map[string]` - We support the following categories of tools: + 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. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) - or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use - custom tools to call your own code. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `top_p: number` +- `--model: optional string or ChatModel` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - We generally recommend altering this or `temperature` but not both. +- `--parallel-tool-calls: optional boolean` - - `background: optional boolean` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - Whether to run the model response in the background. - [Learn more](https://platform.openai.com/docs/guides/background). +- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `completed_at: optional number` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `conversation: optional object { id }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `max_output_tokens: optional number` +- `--temperature: optional number` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - `max_tool_calls: optional number` +- `--thread: optional object { messages, metadata, tool_resources }` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + Options to create a new thread. If no thread is provided when running a + request, an empty thread will be created. - - `moderation: optional object { input, output }` +- `--tool-choice: optional "none" or "auto" or "required" or AssistantToolChoice` - Moderation results for the response input and output, if moderated completions were requested. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `previous_response_id: optional string` +- `--tool-resources: optional object { code_interpreter, file_search }` - 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`. + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `prompt: optional object { id, variables, version }` +- `--tool: optional array of AssistantTool` - Reference to a prompt template and its variables. - [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - - `prompt_cache_key: optional string` +- `--top-p: optional number` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - `prompt_cache_options: optional object { mode, ttl }` + We generally recommend altering this or temperature but not both. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. +- `--truncation-strategy: optional object { type, last_messages }` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - Deprecated. Use `prompt_cache_options.ttl` instead. +### Returns - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. +- `run: object { id, assistant_id, cancelled_at, 24 more }` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `id: string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The identifier, which can be referenced in API endpoints. - **gpt-5 and o-series models only** + - `assistant_id: string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `safety_identifier: optional string` + - `cancelled_at: number` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The Unix timestamp (in seconds) for when the run was cancelled. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `completed_at: number` - Specifies the processing type used for serving the request. + The Unix timestamp (in seconds) for when the run was completed. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `created_at: number` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The Unix timestamp (in seconds) for when the run was created. - - `status: optional "completed" or "failed" or "in_progress" or 3 more` + - `expires_at: number` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The Unix timestamp (in seconds) for when the run will expire. - - `text: optional object { format, verbosity }` + - `failed_at: number` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The Unix timestamp (in seconds) for when the run failed. - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `incomplete_details: object { reason }` - - `top_logprobs: optional number` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `truncation: optional "auto" or "disabled"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The truncation strategy to use for the model response. + - `"max_completion_tokens"` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"max_prompt_tokens"` - - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }` + - `instructions: string` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `user: optional string` + - `last_error: object { code, message }` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + The last error associated with this run. Will be `null` if there are no errors. - - `sequence_number: number` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - The sequence number for this event. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `type: "response.queued"` + - `"server_error"` - The type of the event. Always 'response.queued'. + - `"rate_limit_exceeded"` - - `agent: optional object { agent_name }` + - `"invalid_prompt"` - The agent that owns this multi-agent streaming event. + - `message: string` - - `agent_name: string` + A human-readable description of the error. - The canonical name of the agent that produced this item. + - `max_completion_tokens: number` - - `beta_response_custom_tool_call_input_delta_event: object { delta, item_id, output_index, 3 more }` + The maximum number of completion tokens specified to have been used over the course of the run. - Event representing a delta (partial update) to the input of a custom tool call. + - `max_prompt_tokens: number` - - `delta: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The incremental input data (delta) for the custom tool call. + - `metadata: map[string]` - - `item_id: string` + 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. - Unique identifier for the API item associated with this event. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `output_index: number` + - `model: string` - The index of the output this delta applies to. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `sequence_number: number` + - `object: "thread.run"` - The sequence number of this event. + The object type, which is always `thread.run`. - - `type: "response.custom_tool_call_input.delta"` + - `parallel_tool_calls: boolean` - The event type identifier. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `agent: optional object { agent_name }` + - `required_action: object { submit_tool_outputs, type }` - The agent that owns this multi-agent streaming event. + Details on the action required to continue the run. Will be `null` if no action is required. - - `agent_name: string` + - `submit_tool_outputs: object { tool_calls }` - The canonical name of the agent that produced this item. + Details on the tool outputs needed for this run to continue. - - `beta_response_custom_tool_call_input_done_event: object { input, item_id, output_index, 3 more }` + - `tool_calls: array of RequiredActionFunctionToolCall` - Event indicating that input for a custom tool call is complete. + A list of the relevant tool calls. - - `input: string` + - `id: string` - The complete input data for the custom tool call. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `item_id: string` + - `function: object { arguments, name }` - Unique identifier for the API item associated with this event. + The function definition. - - `output_index: number` + - `arguments: string` - The index of the output this event applies to. + The arguments that the model expects you to pass to the function. - - `sequence_number: number` + - `name: string` - The sequence number of this event. + The name of the function. - - `type: "response.custom_tool_call_input.done"` + - `type: "function"` - The event type identifier. + The type of tool call the output is required for. For now, this is always `function`. - - `agent: optional object { agent_name }` + - `type: "submit_tool_outputs"` - The agent that owns this multi-agent streaming event. + For now, this is always `submit_tool_outputs`. - - `agent_name: string` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - The canonical name of the agent that produced this item. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `response.inject.created: object { response_id, sequence_number, type, stream_id }` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - Emitted when all injected input items were validated and committed to the - active response. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `response_id: string` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The ID of the response that accepted the input. + - `union_member_0: "auto"` - - `sequence_number: number` + `auto` is the default value - The sequence number for this event. + - `response_format_text: object { type }` - - `type: "response.inject.created"` + Default response format. Used to generate text responses. - The event discriminator. Always `response.inject.created`. + - `type: "text"` - - `stream_id: optional string` + The type of response format being defined. Always `text`. - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `response_format_json_object: object { type }` - - `response.inject.failed: object { error, input, response_id, 3 more }` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - Emitted when injected input could not be committed to a response. The event - returns the uncommitted raw input so the client can retry it in another - response when appropriate. + - `type: "json_object"` - - `error: object { code, message }` + The type of response format being defined. Always `json_object`. - Information about why the input was not committed. + - `response_format_json_schema: object { json_schema, type }` - - `code: "response_already_completed" or "response_not_found"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - A machine-readable error code. + - `json_schema: object { name, description, schema, strict }` - - `"response_already_completed"` + Structured Outputs configuration options, including a JSON Schema. - - `"response_not_found"` + - `name: string` - - `message: string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - A human-readable description of the error. + - `description: optional string` - - `input: array of BetaResponseInputItem` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The raw input items that were not committed. + - `schema: optional map[unknown]` - - `beta_easy_input_message: object { content, role, phase, type }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - 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. + - `strict: optional boolean` - - `message: object { content, role, agent, 2 more }` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - 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. + - `type: "json_schema"` - - `beta_response_output_message: object { id, content, role, 4 more }` + The type of response format being defined. Always `json_schema`. - An output message from the model. + - `started_at: number` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + The Unix timestamp (in seconds) for when the run was started. - 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. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - 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. + - `"queued"` - - `computer_call_output: object { call_id, output, type, 4 more }` + - `"in_progress"` - The output of a computer tool call. + - `"requires_action"` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + - `"cancelling"` - 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. + - `"cancelled"` - - `beta_response_function_tool_call: object { arguments, call_id, name, 6 more }` + - `"failed"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"completed"` - - `function_call_output: object { call_id, output, type, 4 more }` + - `"incomplete"` - The output of a function tool call. + - `"expired"` - - `agent_message: object { author, content, recipient, 3 more }` + - `thread_id: string` - A message routed between agents. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `multi_agent_call: object { action, arguments, call_id, 3 more }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `multi_agent_call_output: object { action, call_id, output, 3 more }` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `tool_search_call: object { arguments, type, id, 4 more }` + - `Auto: "none" or "auto" or "required"` - - `beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `additional_tools: object { role, tools, type, 2 more }` + - `"none"` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + - `"auto"` - 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). + - `"required"` - - `beta_response_compaction_item_param: object { encrypted_content, type, id, agent }` + - `assistant_tool_choice: object { type, function }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `image_generation_call: object { id, result, status, 2 more }` + - `type: "function" or "code_interpreter" or "file_search"` - An image generation request made by the model. + The type of the tool. If type is `function`, the function name must be set - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + - `"function"` - A tool call to run code. + - `"code_interpreter"` - - `local_shell_call: object { id, action, call_id, 3 more }` + - `"file_search"` - A tool call to run a command on the local shell. + - `function: optional object { name }` - - `local_shell_call_output: object { id, output, type, 2 more }` + - `name: string` - The output of a local shell tool call. + The name of the function to call. - - `shell_call: object { action, call_id, type, 5 more }` + - `tools: array of AssistantTool` - A tool representing a request to execute one or more shell commands. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `shell_call_output: object { call_id, output, type, 5 more }` + - `code_interpreter_tool: object { type }` - The streamed output items emitted by a shell tool call. + - `type: "code_interpreter"` - - `apply_patch_call: object { call_id, operation, status, 4 more }` + The type of tool being defined: `code_interpreter` - A tool call representing a request to create, delete, or update files using diff patches. + - `file_search_tool: object { type, file_search }` - - `apply_patch_call_output: object { call_id, status, type, 4 more }` + - `type: "file_search"` - The streamed output emitted by an apply patch tool call. + The type of tool being defined: `file_search` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + - `file_search: optional object { max_num_results, ranking_options }` - A list of tools available on an MCP server. + Overrides for the file search tool. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `max_num_results: optional number` - A request for human approval of a tool invocation. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `mcp_approval_response: object { approval_request_id, approve, type, 3 more }` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - A response to an MCP approval request. + - `ranking_options: optional object { score_threshold, ranker }` - - `mcp_call: object { id, arguments, name, 7 more }` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - An invocation of a tool on an MCP server. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }` + - `score_threshold: number` - The output of a custom tool call from your code, being sent back to the model. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `beta_response_custom_tool_call: object { call_id, input, name, 5 more }` + - `ranker: optional "auto" or "default_2024_08_21"` - A call to a custom tool created by the model. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `compaction_trigger: object { type, agent }` + - `"auto"` - Compacts the current context. Must be the final input item. + - `"default_2024_08_21"` - - `item_reference: object { id, agent, type }` + - `function_tool: object { function, type }` - An internal identifier for an item to reference. + - `function: object { name, description, parameters, strict }` - - `program: object { id, call_id, code, 3 more }` + - `name: string` - - `program_output: object { id, call_id, result, 3 more }` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `response_id: string` + - `description: optional string` - The ID of the response that rejected the input. + A description of what the function does, used by the model to choose when and how to call the function. - - `sequence_number: number` + - `parameters: optional map[unknown]` - The sequence number for this event. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `type: "response.inject.failed"` + Omitting `parameters` defines a function with an empty parameter list. - The event discriminator. Always `response.inject.failed`. + - `strict: optional boolean` - - `stream_id: optional string` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `type: "function"` -### Beta Skill Reference + The type of tool being defined: `function` -- `beta_skill_reference: object { skill_id, type, version }` + - `truncation_strategy: object { type, last_messages }` - - `skill_id: string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The ID of the referenced skill. + - `type: "auto" or "last_messages"` - - `type: "skill_reference"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - References a skill created with the /v1/skills endpoint. + - `"auto"` - - `version: optional string` + - `"last_messages"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `last_messages: optional number` -### Beta Tool + The number of most recent messages from the thread when constructing the context for the run. -- `beta_tool: BetaFunctionTool or BetaFileSearchTool or BetaComputerTool or 13 more` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - A tool that can be used to generate a response. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `completion_tokens: number` - 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). + Number of completion tokens used over the course of the run. - - `name: string` + - `prompt_tokens: number` - The name of the function to call. + Number of prompt tokens used over the course of the run. - - `parameters: map[unknown]` + - `total_tokens: number` - A JSON schema object describing the parameters of the function. + Total number of tokens used (prompt + completion). - - `strict: boolean` + - `temperature: optional number` - Whether strict parameter validation is enforced for this function tool. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: "function"` + - `top_p: optional number` - The type of the function tool. Always `function`. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `allowed_callers: optional array of "direct" or "programmatic"` +### Example - The tool invocation context(s). +```cli +openai beta:threads create-and-run \ + --api-key 'My API Key' \ + --assistant-id assistant_id +``` - - `"direct"` +#### Response - - `"programmatic"` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `defer_loading: optional boolean` +## Retrieve thread - Whether this function is deferred and loaded via tool search. +`$ openai beta:threads retrieve` - - `description: optional string` +**get** `/threads/{thread_id}` - A description of the function. Used by the model to determine whether or not to call the function. +Retrieves a thread. - - `output_schema: optional map[unknown]` +### Parameters - A JSON schema object describing the JSON value encoded in string outputs for this function. +- `--thread-id: string` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The ID of the thread to retrieve. - 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). +### Returns - - `type: "file_search"` +- `thread: object { id, created_at, metadata, 2 more }` - The type of the file search tool. Always `file_search`. + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `vector_store_ids: array of string` + - `id: string` - The IDs of the vector stores to search. + The identifier, which can be referenced in API endpoints. - - `filters: optional object { key, type, value } or object { filters, type }` + - `created_at: number` - A filter to apply. + The Unix timestamp (in seconds) for when the thread was created. - - `Comparison Filter: object { key, type, value }` + - `metadata: map[string]` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + 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. - - `key: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The key to compare against the value. + - `object: "thread"` - - `type: "eq" or "ne" or "gt" or 5 more` + The object type, which is always `thread`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `tool_resources: object { code_interpreter, file_search }` - - `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 + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `"eq"` + - `code_interpreter: optional object { file_ids }` - - `"ne"` + - `file_ids: optional array of string` - - `"gt"` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `"gte"` + - `file_search: optional object { vector_store_ids }` - - `"lt"` + - `vector_store_ids: optional array of string` - - `"lte"` + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `"in"` +### Example - - `"nin"` +```cli +openai beta:threads retrieve \ + --api-key 'My API Key' \ + --thread-id thread_id +``` - - `value: string or number or boolean or array of unknown` +#### Response - The value to compare against the attribute key; supports string, number, or boolean types. +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - - `union_member_0: string` +## Modify thread - - `union_member_1: number` +`$ openai beta:threads update` - - `union_member_2: boolean` +**post** `/threads/{thread_id}` - - `union_member_3: array of unknown` +Modifies a thread. - - `Compound Filter: object { filters, type }` +### Parameters - Combine multiple filters using `and` or `or`. +- `--thread-id: string` - - `filters: array of object { key, type, value } or unknown` + The ID of the thread to modify. Only the `metadata` can be modified. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. +- `--metadata: optional map[string]` - - `Comparison Filter: object { key, type, value }` + 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. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `key: string` +- `--tool-resources: optional object { code_interpreter, file_search }` - The key to compare against the value. + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `type: "eq" or "ne" or "gt" or 5 more` +### Returns - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. +- `thread: object { id, created_at, metadata, 2 more }` - - `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 + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - `"eq"` + - `id: string` - - `"ne"` + The identifier, which can be referenced in API endpoints. - - `"gt"` + - `created_at: number` - - `"gte"` + The Unix timestamp (in seconds) for when the thread was created. - - `"lt"` + - `metadata: map[string]` - - `"lte"` + 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. - - `"in"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"nin"` + - `object: "thread"` - - `value: string or number or boolean or array of unknown` + The object type, which is always `thread`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `tool_resources: object { code_interpreter, file_search }` - - `union_member_0: string` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `union_member_1: number` + - `code_interpreter: optional object { file_ids }` - - `union_member_2: boolean` + - `file_ids: optional array of string` - - `union_member_3: array of unknown` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `union_member_1: unknown` + - `file_search: optional object { vector_store_ids }` - - `type: "and" or "or"` + - `vector_store_ids: optional array of string` - Type of operation: `and` or `or`. + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `"and"` +### Example - - `"or"` +```cli +openai beta:threads update \ + --api-key 'My API Key' \ + --thread-id thread_id +``` - - `max_num_results: optional number` +#### Response - The maximum number of results to return. This number should be between 1 and 50 inclusive. +```json +{ + "id": "id", + "created_at": 0, + "metadata": { + "foo": "string" + }, + "object": "thread", + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + } +} +``` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` +## Delete thread - Ranking options for search. +`$ openai beta:threads delete` - - `hybrid_search: optional object { embedding_weight, text_weight }` +**delete** `/threads/{thread_id}` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. +Delete a thread. - - `embedding_weight: number` +### Parameters - The weight of the embedding in the reciprocal ranking fusion. +- `--thread-id: string` - - `text_weight: number` + The ID of the thread to delete. - The weight of the text in the reciprocal ranking fusion. +### Returns - - `ranker: optional "auto" or "default-2024-11-15"` +- `thread_deleted: object { id, deleted, object }` - The ranker to use for the file search. + - `id: string` - - `"auto"` + - `deleted: boolean` - - `"default-2024-11-15"` + - `object: "thread.deleted"` - - `score_threshold: optional number` +### Example - 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. +```cli +openai beta:threads delete \ + --api-key 'My API Key' \ + --thread-id thread_id +``` - - `beta_computer_tool: object { type }` +#### Response - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +```json +{ + "id": "id", + "deleted": true, + "object": "thread.deleted" +} +``` - - `type: "computer"` +## Domain Types - The type of the computer tool. Always `computer`. +### Assistant Response Format Option - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` +- `assistant_response_format_option: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `display_height: number` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - The height of the computer display. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `display_width: number` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The width of the computer display. + - `union_member_0: "auto"` - - `environment: "windows" or "mac" or "linux" or 2 more` + `auto` is the default value - The type of computer environment to control. + - `response_format_text: object { type }` - - `"windows"` + Default response format. Used to generate text responses. - - `"mac"` + - `type: "text"` - - `"linux"` + The type of response format being defined. Always `text`. - - `"ubuntu"` + - `response_format_json_object: object { type }` - - `"browser"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `type: "computer_use_preview"` + - `type: "json_object"` - The type of the computer use tool. Always `computer_use_preview`. + The type of response format being defined. Always `json_object`. - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `response_format_json_schema: object { json_schema, type }` - 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). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `type: "web_search" or "web_search_2025_08_26"` + - `json_schema: object { name, description, schema, strict }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Structured Outputs configuration options, including a JSON Schema. - - `"web_search"` + - `name: string` - - `"web_search_2025_08_26"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `filters: optional object { allowed_domains }` + - `description: optional string` - Filters for the search. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `allowed_domains: optional array of string` + - `schema: optional map[unknown]` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `strict: optional boolean` - - `search_context_size: optional "low" or "medium" or "high"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - 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. + - `type: "json_schema"` - - `"low"` + The type of response format being defined. Always `json_schema`. - - `"medium"` +### Assistant Tool Choice - - `"high"` +- `assistant_tool_choice: object { type, function }` - - `user_location: optional object { city, country, region, 2 more }` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The approximate location of the user. + - `type: "function" or "code_interpreter" or "file_search"` - - `city: optional string` + The type of the tool. If type is `function`, the function name must be set - Free text input for the city of the user, e.g. `San Francisco`. + - `"function"` - - `country: optional string` + - `"code_interpreter"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"file_search"` - - `region: optional string` + - `function: optional object { name }` - Free text input for the region of the user, e.g. `California`. + - `name: string` - - `timezone: optional string` + The name of the function to call. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +### Assistant Tool Choice Function - - `type: optional "approximate"` +- `assistant_tool_choice_function: object { name }` - The type of location approximation. Always `approximate`. + - `name: string` - - `"approximate"` + The name of the function to call. - - `mcp: object { server_label, type, allowed_callers, 9 more }` +### Assistant Tool Choice Option - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). +- `assistant_tool_choice_option: "none" or "auto" or "required" or AssistantToolChoice` - - `server_label: string` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - A label for this MCP server, used to identify it in tool calls. + - `Auto: "none" or "auto" or "required"` - - `type: "mcp"` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - The type of the MCP tool. Always `mcp`. + - `"none"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"auto"` - The tool invocation context(s). + - `"required"` - - `"direct"` + - `assistant_tool_choice: object { type, function }` - - `"programmatic"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `type: "function" or "code_interpreter" or "file_search"` - List of allowed tool names or a filter object. + The type of the tool. If type is `function`, the function name must be set - - `MCP allowed tools: array of string` + - `"function"` - A string array of allowed tool names + - `"code_interpreter"` - - `MCP tool filter: object { read_only, tool_names }` + - `"file_search"` - A filter object to specify which tools are allowed. + - `function: optional object { name }` - - `read_only: optional boolean` + - `name: string` - 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. + The name of the function to call. - - `tool_names: optional array of string` +### Thread - List of allowed tool names. +- `thread: object { id, created_at, metadata, 2 more }` - - `authorization: optional string` + Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - 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. + - `id: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The identifier, which can be referenced in API endpoints. - 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). + - `created_at: number` - Currently supported `connector_id` values are: + The Unix timestamp (in seconds) for when the thread was created. - - 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` + - `metadata: map[string]` - - `"connector_dropbox"` + 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. - - `"connector_gmail"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"connector_googlecalendar"` + - `object: "thread"` - - `"connector_googledrive"` + The object type, which is always `thread`. - - `"connector_microsoftteams"` + - `tool_resources: object { code_interpreter, file_search }` - - `"connector_outlookcalendar"` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `"connector_outlookemail"` + - `code_interpreter: optional object { file_ids }` - - `"connector_sharepoint"` + - `file_ids: optional array of string` - - `defer_loading: optional boolean` + A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - Whether this MCP tool is deferred and discovered via tool search. + - `file_search: optional object { vector_store_ids }` - - `headers: optional map[string]` + - `vector_store_ids: optional array of string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `require_approval: optional object { always, never } or "always" or "never"` +### Thread Deleted - Specify which of the MCP server's tools require approval. +- `thread_deleted: object { id, deleted, object }` - - `MCP tool approval filter: object { always, never }` + - `id: string` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `deleted: boolean` - - `always: optional object { read_only, tool_names }` + - `object: "thread.deleted"` - A filter object to specify which tools are allowed. +# Runs - - `read_only: optional boolean` +## List runs - 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. +`$ openai beta:threads:runs list` - - `tool_names: optional array of string` +**get** `/threads/{thread_id}/runs` - List of allowed tool names. +Returns a list of runs belonging to a thread. - - `never: optional object { read_only, tool_names }` +### Parameters - A filter object to specify which tools are allowed. +- `--thread-id: string` - - `read_only: optional boolean` + The ID of the thread the run belongs to. - 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. +- `--after: optional string` - - `tool_names: optional array of string` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - List of allowed tool names. +- `--before: optional string` - - `MCP tool approval setting: "always" or "never"` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - 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. +- `--limit: optional number` - - `"always"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `"never"` +- `--order: optional "asc" or "desc"` - - `server_description: optional string` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - Optional description of the MCP server, used to provide more context. +### Returns - - `server_url: optional string` +- `ListRunsResponse: object { data, first_id, has_more, 2 more }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `data: array of Run` - - `tunnel_id: optional string` + - `id: string` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The identifier, which can be referenced in API endpoints. - - `code_interpreter: object { container, type, allowed_callers }` + - `assistant_id: string` - A tool that runs Python code to help generate a response to a prompt. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `cancelled_at: number` - 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. + The Unix timestamp (in seconds) for when the run was cancelled. - - `union_member_0: string` + - `completed_at: number` - The container ID. + The Unix timestamp (in seconds) for when the run was completed. - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + - `created_at: number` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The Unix timestamp (in seconds) for when the run was created. - - `type: "auto"` + - `expires_at: number` - Always `auto`. + The Unix timestamp (in seconds) for when the run will expire. - - `file_ids: optional array of string` + - `failed_at: number` - An optional list of uploaded files to make available to your code. + The Unix timestamp (in seconds) for when the run failed. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `incomplete_details: object { reason }` - The memory limit for the code interpreter container. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"1g"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `"4g"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"16g"` + - `"max_completion_tokens"` - - `"64g"` + - `"max_prompt_tokens"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `instructions: string` - Network access policy for the container. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `beta_container_network_policy_disabled: object { type }` + - `last_error: object { code, message }` - - `type: "disabled"` + The last error associated with this run. Will be `null` if there are no errors. - Disable outbound network access. Always `disabled`. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `allowed_domains: array of string` + - `"server_error"` - A list of allowed domains when type is `allowlist`. + - `"rate_limit_exceeded"` - - `type: "allowlist"` + - `"invalid_prompt"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `message: string` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + A human-readable description of the error. - Optional domain-scoped secrets for allowlisted domains. + - `max_completion_tokens: number` - - `domain: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The domain associated with the secret. + - `max_prompt_tokens: number` - - `name: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The name of the secret to inject for the domain. + - `metadata: map[string]` - - `value: string` + 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. - The secret value to inject for the domain. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "code_interpreter"` + - `model: string` - The type of the code interpreter tool. Always `code_interpreter`. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `object: "thread.run"` - The tool invocation context(s). + The object type, which is always `thread.run`. - - `"direct"` + - `parallel_tool_calls: boolean` - - `"programmatic"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `programmatic_tool_calling: object { type }` + - `required_action: object { submit_tool_outputs, type }` - - `image_generation: object { type, action, background, 9 more }` + Details on the action required to continue the run. Will be `null` if no action is required. - A tool that generates images using the GPT image models. + - `submit_tool_outputs: object { tool_calls }` - - `type: "image_generation"` + Details on the tool outputs needed for this run to continue. - The type of the image generation tool. Always `image_generation`. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `action: optional "generate" or "edit" or "auto"` + A list of the relevant tool calls. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `id: string` - - `"generate"` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `"edit"` + - `function: object { arguments, name }` - - `"auto"` + The function definition. - - `background: optional "transparent" or "opaque" or "auto"` + - `arguments: string` - 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. + The arguments that the model expects you to pass to the function. - `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. + - `name: string` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The name of the function. - - `"transparent"` + - `type: "function"` - - `"opaque"` + The type of tool call the output is required for. For now, this is always `function`. - - `"auto"` + - `type: "submit_tool_outputs"` - - `input_fidelity: optional "high" or "low"` + For now, this is always `submit_tool_outputs`. - 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`. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `"high"` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `"low"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `input_image_mask: optional object { file_id, image_url }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `file_id: optional string` + - `union_member_0: "auto"` - File ID for the mask image. + `auto` is the default value - - `image_url: optional string` + - `response_format_text: object { type }` - Base64-encoded mask image. + Default response format. Used to generate text responses. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `type: "text"` - The image generation model to use. Default: `gpt-image-1`. + The type of response format being defined. Always `text`. - - `"gpt-image-1"` + - `response_format_json_object: object { type }` - - `"gpt-image-1-mini"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `"gpt-image-2"` + - `type: "json_object"` - - `"gpt-image-2-2026-04-21"` + The type of response format being defined. Always `json_object`. - - `"gpt-image-1.5"` + - `response_format_json_schema: object { json_schema, type }` - - `"chatgpt-image-latest"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `moderation: optional "auto" or "low"` + - `json_schema: object { name, description, schema, strict }` - Moderation level for the generated image. Default: `auto`. + Structured Outputs configuration options, including a JSON Schema. - - `"auto"` + - `name: string` - - `"low"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `output_compression: optional number` + - `description: optional string` - Compression level for the output image. Default: 100. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `output_format: optional "png" or "webp" or "jpeg"` + - `schema: optional map[unknown]` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"png"` + - `strict: optional boolean` - - `"webp"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"jpeg"` + - `type: "json_schema"` - - `partial_images: optional number` + The type of response format being defined. Always `json_schema`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `started_at: number` - - `quality: optional "low" or "medium" or "high" or "auto"` + The Unix timestamp (in seconds) for when the run was started. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `"low"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `"medium"` + - `"queued"` - - `"high"` + - `"in_progress"` - - `"auto"` + - `"requires_action"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"cancelling"` - 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`. + - `"cancelled"` - - `"1024x1024"` + - `"failed"` - - `"1024x1536"` + - `"completed"` - - `"1536x1024"` + - `"incomplete"` - - `"auto"` + - `"expired"` - - `local_shell: object { type }` + - `thread_id: string` - A tool that allows the model to execute shell commands in a local environment. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - A tool that allows the model to execute shell commands. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `type: "shell"` + - `Auto: "none" or "auto" or "required"` - The type of the shell tool. Always `shell`. + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"none"` - The tool invocation context(s). + - `"auto"` - - `"direct"` + - `"required"` - - `"programmatic"` + - `assistant_tool_choice: object { type, function }` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `type: "function" or "code_interpreter" or "file_search"` - - `type: "container_auto"` + The type of the tool. If type is `function`, the function name must be set - Automatically creates a container for this request + - `"function"` - - `file_ids: optional array of string` + - `"code_interpreter"` - An optional list of uploaded files to make available to your code. + - `"file_search"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `function: optional object { name }` - The memory limit for the container. + - `name: string` - - `"1g"` + The name of the function to call. - - `"4g"` + - `tools: array of AssistantTool` - - `"16g"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"64g"` + - `code_interpreter_tool: object { type }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `type: "code_interpreter"` - Network access policy for the container. + The type of tool being defined: `code_interpreter` - - `beta_container_network_policy_disabled: object { type }` + - `file_search_tool: object { type, file_search }` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `type: "file_search"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The type of tool being defined: `file_search` - An optional list of skills referenced by id or inline data. + - `file_search: optional object { max_num_results, ranking_options }` - - `beta_skill_reference: object { skill_id, type, version }` + Overrides for the file search tool. - - `skill_id: string` + - `max_num_results: optional number` - The ID of the referenced skill. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `type: "skill_reference"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - References a skill created with the /v1/skills endpoint. + - `ranking_options: optional object { score_threshold, ranker }` - - `version: optional string` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `beta_inline_skill: object { description, name, source, type }` + - `score_threshold: number` - - `description: string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The description of the skill. + - `ranker: optional "auto" or "default_2024_08_21"` - - `name: string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The name of the skill. + - `"auto"` - - `source: object { data, media_type, type }` + - `"default_2024_08_21"` - Inline skill payload + - `function_tool: object { function, type }` - - `data: string` + - `function: object { name, description, parameters, strict }` - Base64-encoded skill zip bundle. + - `name: string` - - `media_type: "application/zip"` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The media type of the inline skill payload. Must be `application/zip`. + - `description: optional string` - - `type: "base64"` + A description of what the function does, used by the model to choose when and how to call the function. - The type of the inline skill source. Must be `base64`. + - `parameters: optional map[unknown]` - - `type: "inline"` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - Defines an inline skill for this request. + Omitting `parameters` defines a function with an empty parameter list. - - `beta_local_environment: object { type, skills }` + - `strict: optional boolean` - - `type: "local"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - Use a local computer environment. + - `type: "function"` - - `skills: optional array of BetaLocalSkill` + The type of tool being defined: `function` - An optional list of skills. + - `truncation_strategy: object { type, last_messages }` - - `description: string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The description of the skill. + - `type: "auto" or "last_messages"` - - `name: string` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The name of the skill. + - `"auto"` - - `path: string` + - `"last_messages"` - The path to the directory containing the skill. + - `last_messages: optional number` - - `beta_container_reference: object { container_id, type }` + The number of most recent messages from the thread when constructing the context for the run. - - `container_id: string` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The ID of the referenced container. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `type: "container_reference"` + - `completion_tokens: number` - References a container created with the /v1/containers endpoint + Number of completion tokens used over the course of the run. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `prompt_tokens: number` - 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) + Number of prompt tokens used over the course of the run. - - `name: string` + - `total_tokens: number` - The name of the custom tool, used to identify it in tool calls. + Total number of tokens used (prompt + completion). - - `type: "custom"` + - `temperature: optional number` - The type of the custom tool. Always `custom`. + The sampling temperature used for this run. If not set, defaults to 1. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `top_p: optional number` - The tool invocation context(s). + The nucleus sampling value used for this run. If not set, defaults to 1. - - `"direct"` + - `first_id: string` - - `"programmatic"` + - `has_more: boolean` - - `defer_loading: optional boolean` + - `last_id: string` - Whether this tool should be deferred and discovered via tool search. + - `object: string` - - `description: optional string` +### Example - Optional description of the custom tool, used to provide more context. +```cli +openai beta:threads:runs list \ + --api-key 'My API Key' \ + --thread-id thread_id +``` - - `format: optional object { type } or object { definition, syntax, type }` +#### Response - The input format for the custom tool. Default is unconstrained text. +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 + } + ], + "first_id": "run_abc123", + "has_more": false, + "last_id": "run_abc456", + "object": "list" +} +``` - - `text: object { type }` +## Create run - Unconstrained free-form text. +`$ openai beta:threads:runs create` - - `grammar: object { definition, syntax, type }` +**post** `/threads/{thread_id}/runs` - A grammar defined by the user. +Create a run. - - `definition: string` +### Parameters - The grammar definition. +- `--thread-id: string` - - `syntax: "lark" or "regex"` + Path param: The ID of the thread to run. - The syntax of the grammar definition. One of `lark` or `regex`. +- `--assistant-id: string` - - `"lark"` + Body param: The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. - - `"regex"` +- `--include: optional array of RunStepInclude` - - `type: "grammar"` + Query param: A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - Grammar format. Always `grammar`. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `beta_namespace_tool: object { description, name, tools, type }` +- `--additional-instructions: optional string` - Groups function/custom tools under a shared namespace. + Body param: Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. - - `description: string` +- `--additional-message: optional array of object { content, role, attachments, metadata }` - A description of the namespace shown to the model. + Body param: Adds additional messages to the thread before creating the run. - - `name: string` +- `--instructions: optional string` - The namespace name used in tool calls (for example, `crm`). + Body param: Overrides the [instructions](https://platform.openai.com/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` +- `--max-completion-tokens: optional number` - The function/custom tools available inside this namespace. + Body param: The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `function: object { name, type, allowed_callers, 5 more }` +- `--max-prompt-tokens: optional number` - - `name: string` + Body param: The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `type: "function"` +- `--metadata: optional map[string]` - - `allowed_callers: optional array of "direct" or "programmatic"` + Body param: 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. - The tool invocation context(s). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"direct"` +- `--model: optional string or ChatModel` - - `"programmatic"` + Body param: The ID of the [Model](https://platform.openai.com/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - - `defer_loading: optional boolean` +- `--parallel-tool-calls: optional boolean` - Whether this function should be deferred and discovered via tool search. + Body param: Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `description: optional string` +- `--reasoning-effort: optional "none" or "minimal" or "low" or 4 more` - - `output_schema: optional map[unknown]` + Body param: Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +- `--response-format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `parameters: optional unknown` + Body param: Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `strict: optional boolean` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - 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. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - 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) +- `--temperature: optional number` - - `name: string` + Body param: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - The name of the custom tool, used to identify it in tool calls. +- `--tool-choice: optional "none" or "auto" or "required" or AssistantToolChoice` - - `type: "custom"` + Body param: Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of the custom tool. Always `custom`. +- `--tool: optional array of AssistantTool` - - `allowed_callers: optional array of "direct" or "programmatic"` + Body param: Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - The tool invocation context(s). +- `--top-p: optional number` - - `defer_loading: optional boolean` + Body param: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - Whether this tool should be deferred and discovered via tool search. + We generally recommend altering this or temperature but not both. - - `description: optional string` +- `--truncation-strategy: optional object { type, last_messages }` - Optional description of the custom tool, used to provide more context. + Body param: Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `format: optional object { type } or object { definition, syntax, type }` +### Returns - The input format for the custom tool. Default is unconstrained text. +- `run: object { id, assistant_id, cancelled_at, 24 more }` - - `type: "namespace"` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The type of the tool. Always `namespace`. + - `id: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The identifier, which can be referenced in API endpoints. - Hosted or BYOT tool search configuration for deferred tools. + - `assistant_id: string` - - `type: "tool_search"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The type of the tool. Always `tool_search`. + - `cancelled_at: number` - - `description: optional string` + The Unix timestamp (in seconds) for when the run was cancelled. - Description shown to the model for a client-executed tool search tool. + - `completed_at: number` - - `execution: optional "server" or "client"` + The Unix timestamp (in seconds) for when the run was completed. - Whether tool search is executed by the server or by the client. + - `created_at: number` - - `"server"` + The Unix timestamp (in seconds) for when the run was created. - - `"client"` + - `expires_at: number` - - `parameters: optional unknown` + The Unix timestamp (in seconds) for when the run will expire. - Parameter schema for a client-executed tool search tool. + - `failed_at: number` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The Unix timestamp (in seconds) for when the run failed. - 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). + - `incomplete_details: object { reason }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `"web_search_preview"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"web_search_preview_2025_03_11"` + - `"max_completion_tokens"` - - `search_content_types: optional array of "text" or "image"` + - `"max_prompt_tokens"` - - `"text"` + - `instructions: string` - - `"image"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `search_context_size: optional "low" or "medium" or "high"` + - `last_error: object { code, message }` - 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. + The last error associated with this run. Will be `null` if there are no errors. - - `"low"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `"medium"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `"high"` + - `"server_error"` - - `user_location: optional object { type, city, country, 2 more }` + - `"rate_limit_exceeded"` - The user's location. + - `"invalid_prompt"` - - `type: "approximate"` + - `message: string` - The type of location approximation. Always `approximate`. + A human-readable description of the error. - - `city: optional string` + - `max_completion_tokens: number` - Free text input for the city of the user, e.g. `San Francisco`. + The maximum number of completion tokens specified to have been used over the course of the run. - - `country: optional string` + - `max_prompt_tokens: number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `region: optional string` + - `metadata: map[string]` - Free text input for the region of the user, e.g. `California`. + 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. - - `timezone: optional string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `model: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Allows the assistant to create, delete, or update files using unified diffs. + - `object: "thread.run"` - - `type: "apply_patch"` + The object type, which is always `thread.run`. - The type of the tool. Always `apply_patch`. + - `parallel_tool_calls: boolean` - - `allowed_callers: optional array of "direct" or "programmatic"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The tool invocation context(s). + - `required_action: object { submit_tool_outputs, type }` - - `"direct"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `"programmatic"` + - `submit_tool_outputs: object { tool_calls }` -### Beta Tool Choice Allowed + Details on the tool outputs needed for this run to continue. -- `beta_tool_choice_allowed: object { mode, tools, type }` + - `tool_calls: array of RequiredActionFunctionToolCall` - Constrains the tools available to the model to a pre-defined set. + A list of the relevant tool calls. - - `mode: "auto" or "required"` + - `id: string` - Constrains the tools available to the model to a pre-defined set. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `function: object { arguments, name }` - `required` requires the model to call one or more of the allowed tools. + The function definition. - - `"auto"` + - `arguments: string` - - `"required"` + The arguments that the model expects you to pass to the function. - - `tools: array of map[unknown]` + - `name: string` - A list of tool definitions that the model should be allowed to call. + The name of the function. - For the Responses API, the list of tool definitions might look like: + - `type: "function"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The type of tool call the output is required for. For now, this is always `function`. - - `type: "allowed_tools"` + - `type: "submit_tool_outputs"` - Allowed tool configuration type. Always `allowed_tools`. + For now, this is always `submit_tool_outputs`. -### Beta Tool Choice Apply Patch + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` -- `beta_tool_choice_apply_patch: object { type }` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - Forces the model to call the apply_patch tool when executing a tool call. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `type: "apply_patch"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The tool to call. Always `apply_patch`. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. -### Beta Tool Choice Custom + - `union_member_0: "auto"` -- `beta_tool_choice_custom: object { name, type }` + `auto` is the default value - Use this option to force the model to call a specific custom tool. + - `response_format_text: object { type }` - - `name: string` + Default response format. Used to generate text responses. - The name of the custom tool to call. + - `type: "text"` - - `type: "custom"` + The type of response format being defined. Always `text`. - For custom tool calling, the type is always `custom`. + - `response_format_json_object: object { type }` -### Beta Tool Choice Function + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. -- `beta_tool_choice_function: object { name, type }` + - `type: "json_object"` - Use this option to force the model to call a specific function. + The type of response format being defined. Always `json_object`. - - `name: string` + - `response_format_json_schema: object { json_schema, type }` - The name of the function to call. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `type: "function"` + - `json_schema: object { name, description, schema, strict }` - For function calling, the type is always `function`. + Structured Outputs configuration options, including a JSON Schema. -### Beta Tool Choice Mcp + - `name: string` -- `beta_tool_choice_mcp: object { server_label, type, name }` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - Use this option to force the model to call a specific tool on a remote MCP server. + - `description: optional string` - - `server_label: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The label of the MCP server to use. + - `schema: optional map[unknown]` - - `type: "mcp"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - For MCP tools, the type is always `mcp`. + - `strict: optional boolean` - - `name: optional string` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The name of the tool to call on the server. + - `type: "json_schema"` -### Beta Tool Choice Options + The type of response format being defined. Always `json_schema`. -- `beta_tool_choice_options: "none" or "auto" or "required"` + - `started_at: number` - Controls which (if any) tool is called by the model. + The Unix timestamp (in seconds) for when the run was started. - `none` means the model will not call any tool and instead generates a message. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - `auto` means the model can pick between generating a message or calling one or - more tools. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - `required` means the model must call one or more tools. + - `"queued"` - - `"none"` + - `"in_progress"` - - `"auto"` + - `"requires_action"` - - `"required"` + - `"cancelling"` -### Beta Tool Choice Shell + - `"cancelled"` -- `beta_tool_choice_shell: object { type }` + - `"failed"` - Forces the model to call the shell tool when a tool call is required. + - `"completed"` - - `type: "shell"` + - `"incomplete"` - The tool to call. Always `shell`. + - `"expired"` -### Beta Tool Choice Types + - `thread_id: string` -- `beta_tool_choice_types: object { type }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools). + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://platform.openai.com/docs/guides/tools). + - `Auto: "none" or "auto" or "required"` - Allowed values are: + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"none"` - - `"file_search"` + - `"auto"` - - `"web_search_preview"` + - `"required"` - - `"computer"` + - `assistant_tool_choice: object { type, function }` - - `"computer_use_preview"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `"computer_use"` + - `type: "function" or "code_interpreter" or "file_search"` - - `"web_search_preview_2025_03_11"` + The type of the tool. If type is `function`, the function name must be set - - `"image_generation"` + - `"function"` - `"code_interpreter"` -### Beta Tool Search Tool + - `"file_search"` -- `beta_tool_search_tool: object { type, description, execution, parameters }` + - `function: optional object { name }` - Hosted or BYOT tool search configuration for deferred tools. + - `name: string` - - `type: "tool_search"` + The name of the function to call. - The type of the tool. Always `tool_search`. + - `tools: array of AssistantTool` - - `description: optional string` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - Description shown to the model for a client-executed tool search tool. + - `code_interpreter_tool: object { type }` - - `execution: optional "server" or "client"` + - `type: "code_interpreter"` - Whether tool search is executed by the server or by the client. + The type of tool being defined: `code_interpreter` - - `"server"` + - `file_search_tool: object { type, file_search }` - - `"client"` + - `type: "file_search"` - - `parameters: optional unknown` + The type of tool being defined: `file_search` - Parameter schema for a client-executed tool search tool. + - `file_search: optional object { max_num_results, ranking_options }` -### Beta Web Search Preview Tool + Overrides for the file search tool. -- `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `max_num_results: optional number` - 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). + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `ranking_options: optional object { score_threshold, ranker }` - - `"web_search_preview"` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"web_search_preview_2025_03_11"` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `search_content_types: optional array of "text" or "image"` + - `score_threshold: number` - - `"text"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"image"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `search_context_size: optional "low" or "medium" or "high"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - 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. + - `"auto"` - - `"low"` + - `"default_2024_08_21"` - - `"medium"` + - `function_tool: object { function, type }` - - `"high"` + - `function: object { name, description, parameters, strict }` - - `user_location: optional object { type, city, country, 2 more }` + - `name: string` - The user's location. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `type: "approximate"` + - `description: optional string` - The type of location approximation. Always `approximate`. + A description of what the function does, used by the model to choose when and how to call the function. - - `city: optional string` + - `parameters: optional map[unknown]` - Free text input for the city of the user, e.g. `San Francisco`. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `country: optional string` + Omitting `parameters` defines a function with an empty parameter list. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `strict: optional boolean` - - `region: optional string` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - Free text input for the region of the user, e.g. `California`. + - `type: "function"` - - `timezone: optional string` + The type of tool being defined: `function` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `truncation_strategy: object { type, last_messages }` -### Beta Web Search Tool + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. -- `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `type: "auto" or "last_messages"` - 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). + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `type: "web_search" or "web_search_2025_08_26"` + - `"auto"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"last_messages"` - - `"web_search"` + - `last_messages: optional number` - - `"web_search_2025_08_26"` + The number of most recent messages from the thread when constructing the context for the run. - - `filters: optional object { allowed_domains }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Filters for the search. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `allowed_domains: optional array of string` + - `completion_tokens: number` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + Number of completion tokens used over the course of the run. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `prompt_tokens: number` - - `search_context_size: optional "low" or "medium" or "high"` + Number of prompt tokens used over the course of the run. - 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. + - `total_tokens: number` - - `"low"` + Total number of tokens used (prompt + completion). - - `"medium"` + - `temperature: optional number` - - `"high"` + The sampling temperature used for this run. If not set, defaults to 1. - - `user_location: optional object { city, country, region, 2 more }` + - `top_p: optional number` - The approximate location of the user. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `city: optional string` +### Example - Free text input for the city of the user, e.g. `San Francisco`. +```cli +openai beta:threads:runs create \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --assistant-id assistant_id +``` - - `country: optional string` +#### Response - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `region: optional string` +## Retrieve run - Free text input for the region of the user, e.g. `California`. +`$ openai beta:threads:runs retrieve` - - `timezone: optional string` +**get** `/threads/{thread_id}/runs/{run_id}` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. +Retrieves a run. - - `type: optional "approximate"` +### Parameters - The type of location approximation. Always `approximate`. +- `--thread-id: string` - - `"approximate"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. -# Input Items +- `--run-id: string` -## List input items + The ID of the run to retrieve. -`$ openai beta:responses:input-items list` +### Returns -**get** `/responses/{response_id}/input_items?beta=true` +- `run: object { id, assistant_id, cancelled_at, 24 more }` -List input items + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). -### Parameters + - `id: string` -- `--response-id: string` + The identifier, which can be referenced in API endpoints. - Path param: The ID of the response to retrieve input items for. + - `assistant_id: string` -- `--after: optional string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - Query param: An item ID to list items after, used in pagination. + - `cancelled_at: number` -- `--include: optional array of BetaResponseIncludable` + The Unix timestamp (in seconds) for when the run was cancelled. - Query param: Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `completed_at: number` -- `--limit: optional number` + The Unix timestamp (in seconds) for when the run was completed. - Query param: A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. + - `created_at: number` -- `--order: optional "asc" or "desc"` + The Unix timestamp (in seconds) for when the run was created. - Query param: The order to return the input items in. Default is `desc`. + - `expires_at: number` - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. + The Unix timestamp (in seconds) for when the run will expire. -- `--beta: optional array of "responses_multi_agent=v1"` + - `failed_at: number` - Header param: Optional beta features to enable for this request. + The Unix timestamp (in seconds) for when the run failed. -### Returns + - `incomplete_details: object { reason }` -- `beta_responseItemList: object { data, first_id, has_more, 2 more }` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - A list of Response items. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `data: array of BetaResponseItem` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - A list of items used to generate this response. + - `"max_completion_tokens"` - - `beta_response_input_message_item: object { id, content, role, 3 more }` + - `"max_prompt_tokens"` - - `id: string` + - `instructions: string` - The unique ID of the message input. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `content: array of BetaResponseInputContent` + - `last_error: object { code, message }` - A list of one or many input items to the model, containing different content - types. + The last error associated with this run. Will be `null` if there are no errors. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - A text input to the model. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `text: string` + - `"server_error"` - The text input to the model. + - `"rate_limit_exceeded"` - - `type: "input_text"` + - `"invalid_prompt"` - The type of the input item. Always `input_text`. + - `message: string` - - `prompt_cache_breakpoint: optional object { mode }` + A human-readable description of the error. - 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. + - `max_completion_tokens: number` - - `mode: "explicit"` + The maximum number of completion tokens specified to have been used over the course of the run. - The breakpoint mode. Always `explicit`. + - `max_prompt_tokens: number` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The maximum number of prompt tokens specified to have been used over the course of the run. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `metadata: map[string]` - - `detail: "low" or "high" or "auto" or "original"` + 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. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"low"` + - `model: string` - - `"high"` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"auto"` + - `object: "thread.run"` - - `"original"` + The object type, which is always `thread.run`. - - `type: "input_image"` + - `parallel_tool_calls: boolean` - The type of the input item. Always `input_image`. + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `file_id: optional string` + - `required_action: object { submit_tool_outputs, type }` - The ID of the file to be sent to the model. + Details on the action required to continue the run. Will be `null` if no action is required. - - `image_url: optional string` + - `submit_tool_outputs: object { tool_calls }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Details on the tool outputs needed for this run to continue. - - `prompt_cache_breakpoint: optional object { mode }` + - `tool_calls: array of RequiredActionFunctionToolCall` - 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. + A list of the relevant tool calls. - - `mode: "explicit"` + - `id: string` - The breakpoint mode. Always `explicit`. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `function: object { arguments, name }` - A file input to the model. + The function definition. - - `type: "input_file"` + - `arguments: string` - The type of the input item. Always `input_file`. + The arguments that the model expects you to pass to the function. - - `detail: optional "auto" or "low" or "high"` + - `name: string` - 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`. + The name of the function. - - `"auto"` + - `type: "function"` - - `"low"` + The type of tool call the output is required for. For now, this is always `function`. - - `"high"` + - `type: "submit_tool_outputs"` - - `file_data: optional string` + For now, this is always `submit_tool_outputs`. - The content of the file to be sent to the model. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `file_id: optional string` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The ID of the file to be sent to the model. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `file_url: optional string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The URL of the file to be sent to the model. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `filename: optional string` + - `union_member_0: "auto"` - The name of the file to be sent to the model. + `auto` is the default value - - `prompt_cache_breakpoint: optional object { mode }` + - `response_format_text: object { type }` - 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. + Default response format. Used to generate text responses. - - `mode: "explicit"` + - `type: "text"` - The breakpoint mode. Always `explicit`. + The type of response format being defined. Always `text`. - - `role: "user" or "system" or "developer"` + - `response_format_json_object: object { type }` - The role of the message input. One of `user`, `system`, or `developer`. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `"user"` + - `type: "json_object"` - - `"system"` + The type of response format being defined. Always `json_object`. - - `"developer"` + - `response_format_json_schema: object { json_schema, type }` - - `type: "message"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The type of the message input. Always set to `message`. + - `json_schema: object { name, description, schema, strict }` - - `agent: optional object { agent_name }` + Structured Outputs configuration options, including a JSON Schema. - The agent that produced this item. + - `name: string` - - `agent_name: string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - The canonical name of the agent that produced this item. + - `description: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `schema: optional map[unknown]` - - `"in_progress"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"completed"` + - `strict: optional boolean` - - `"incomplete"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `beta_response_output_message: object { id, content, role, 4 more }` + - `type: "json_schema"` - An output message from the model. + The type of response format being defined. Always `json_schema`. - - `id: string` + - `started_at: number` - The unique ID of the output message. + The Unix timestamp (in seconds) for when the run was started. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - The content of the output message. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `"queued"` - A text output from the model. + - `"in_progress"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"requires_action"` - The annotations of the text output. + - `"cancelling"` - - `file_citation: object { file_id, filename, index, type }` + - `"cancelled"` - A citation to a file. + - `"failed"` - - `file_id: string` + - `"completed"` - The ID of the file. + - `"incomplete"` - - `filename: string` + - `"expired"` - The filename of the file cited. + - `thread_id: string` - - `index: number` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - The index of the file in the list of files. + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `type: "file_citation"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of the file citation. Always `file_citation`. + - `Auto: "none" or "auto" or "required"` - - `url_citation: object { end_index, start_index, title, 2 more }` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - A citation for a web resource used to generate a model response. + - `"none"` - - `end_index: number` + - `"auto"` - The index of the last character of the URL citation in the message. + - `"required"` - - `start_index: number` + - `assistant_tool_choice: object { type, function }` - The index of the first character of the URL citation in the message. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `title: string` + - `type: "function" or "code_interpreter" or "file_search"` - The title of the web resource. + The type of the tool. If type is `function`, the function name must be set - - `type: "url_citation"` + - `"function"` - The type of the URL citation. Always `url_citation`. + - `"code_interpreter"` - - `url: string` + - `"file_search"` - The URL of the web resource. + - `function: optional object { name }` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + - `name: string` - A citation for a container file used to generate a model response. + The name of the function to call. - - `container_id: string` + - `tools: array of AssistantTool` - The ID of the container file. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `end_index: number` + - `code_interpreter_tool: object { type }` - The index of the last character of the container file citation in the message. + - `type: "code_interpreter"` - - `file_id: string` + The type of tool being defined: `code_interpreter` - The ID of the file. + - `file_search_tool: object { type, file_search }` - - `filename: string` + - `type: "file_search"` - The filename of the container file cited. + The type of tool being defined: `file_search` - - `start_index: number` + - `file_search: optional object { max_num_results, ranking_options }` - The index of the first character of the container file citation in the message. + Overrides for the file search tool. - - `type: "container_file_citation"` + - `max_num_results: optional number` - The type of the container file citation. Always `container_file_citation`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `file_path: object { file_id, index, type }` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - A path to a file. + - `ranking_options: optional object { score_threshold, ranker }` - - `file_id: string` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The ID of the file. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `index: number` + - `score_threshold: number` - The index of the file in the list of files. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: "file_path"` + - `ranker: optional "auto" or "default_2024_08_21"` - The type of the file path. Always `file_path`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `text: string` + - `"auto"` - The text output from the model. + - `"default_2024_08_21"` - - `type: "output_text"` + - `function_tool: object { function, type }` - The type of the output text. Always `output_text`. + - `function: object { name, description, parameters, strict }` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `name: string` - - `token: string` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `bytes: array of number` + - `description: optional string` - - `logprob: number` + A description of what the function does, used by the model to choose when and how to call the function. - - `top_logprobs: array of object { token, bytes, logprob }` + - `parameters: optional map[unknown]` - - `token: string` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `bytes: array of number` + Omitting `parameters` defines a function with an empty parameter list. - - `logprob: number` + - `strict: optional boolean` - - `beta_response_output_refusal: object { refusal, type }` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - A refusal from the model. + - `type: "function"` - - `refusal: string` + The type of tool being defined: `function` - The refusal explanation from the model. + - `truncation_strategy: object { type, last_messages }` - - `type: "refusal"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The type of the refusal. Always `refusal`. + - `type: "auto" or "last_messages"` - - `role: "assistant"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The role of the output message. Always `assistant`. + - `"auto"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"last_messages"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `last_messages: optional number` - - `"in_progress"` + The number of most recent messages from the thread when constructing the context for the run. - - `"completed"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"incomplete"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `type: "message"` + - `completion_tokens: number` - The type of the output message. Always `message`. + Number of completion tokens used over the course of the run. - - `agent: optional object { agent_name }` + - `prompt_tokens: number` - The agent that produced this item. + Number of prompt tokens used over the course of the run. - - `agent_name: string` + - `total_tokens: number` - The canonical name of the agent that produced this item. + Total number of tokens used (prompt + completion). - - `phase: optional "commentary"` + - `temperature: optional number` - 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. + The sampling temperature used for this run. If not set, defaults to 1. - - `"commentary"` + - `top_p: optional number` - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + The nucleus sampling value used for this run. If not set, defaults to 1. - 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. +### Example - - `id: string` +```cli +openai beta:threads:runs retrieve \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id +``` - The unique ID of the file search tool call. +#### Response - - `queries: array of string` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - The queries used to search for files. +## Modify run - - `status: "in_progress" or "searching" or "completed" or 2 more` +`$ openai beta:threads:runs update` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, +**post** `/threads/{thread_id}/runs/{run_id}` - - `"in_progress"` +Modifies a run. - - `"searching"` +### Parameters - - `"completed"` +- `--thread-id: string` - - `"incomplete"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `"failed"` +- `--run-id: string` - - `type: "file_search_call"` + The ID of the run to modify. - The type of the file search tool call. Always `file_search_call`. +- `--metadata: optional map[string]` - - `agent: optional object { agent_name }` + 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. - The agent that produced this item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `agent_name: string` +### Returns - The canonical name of the agent that produced this item. +- `run: object { id, assistant_id, cancelled_at, 24 more }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The results of the file search tool call. + - `id: string` - - `attributes: optional map[string or number or boolean]` + The identifier, which can be referenced in API endpoints. - 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. + - `assistant_id: string` - - `union_member_0: string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `union_member_1: number` + - `cancelled_at: number` - - `union_member_2: boolean` + The Unix timestamp (in seconds) for when the run was cancelled. - - `file_id: optional string` + - `completed_at: number` - The unique ID of the file. + The Unix timestamp (in seconds) for when the run was completed. - - `filename: optional string` + - `created_at: number` - The name of the file. + The Unix timestamp (in seconds) for when the run was created. - - `score: optional number` + - `expires_at: number` - The relevance score of the file - a value between 0 and 1. + The Unix timestamp (in seconds) for when the run will expire. - - `text: optional string` + - `failed_at: number` - The text that was retrieved from the file. + The Unix timestamp (in seconds) for when the run failed. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `incomplete_details: object { reason }` - 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. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `id: string` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The unique ID of the computer call. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `call_id: string` + - `"max_completion_tokens"` - An identifier used when responding to the tool call with output. + - `"max_prompt_tokens"` - - `pending_safety_checks: array of object { id, code, message }` + - `instructions: string` - The pending safety checks for the computer call. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `id: string` + - `last_error: object { code, message }` - The ID of the pending safety check. + The last error associated with this run. Will be `null` if there are no errors. - - `code: optional string` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - The type of the pending safety check. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `message: optional string` + - `"server_error"` - Details about the pending safety check. + - `"rate_limit_exceeded"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"invalid_prompt"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `message: string` - - `"in_progress"` + A human-readable description of the error. - - `"completed"` + - `max_completion_tokens: number` - - `"incomplete"` + The maximum number of completion tokens specified to have been used over the course of the run. - - `type: "computer_call"` + - `max_prompt_tokens: number` - The type of the computer call. Always `computer_call`. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `"computer_call"` + - `metadata: map[string]` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + 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. - A click action. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `click: object { button, type, x, 2 more }` + - `model: string` - A click action. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `button: "left" or "right" or "wheel" or 2 more` + - `object: "thread.run"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The object type, which is always `thread.run`. - - `"left"` + - `parallel_tool_calls: boolean` - - `"right"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"wheel"` + - `required_action: object { submit_tool_outputs, type }` - - `"back"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `"forward"` + - `submit_tool_outputs: object { tool_calls }` - - `type: "click"` + Details on the tool outputs needed for this run to continue. - Specifies the event type. For a click action, this property is always `click`. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `x: number` + A list of the relevant tool calls. - The x-coordinate where the click occurred. + - `id: string` - - `y: number` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - The y-coordinate where the click occurred. + - `function: object { arguments, name }` - - `keys: optional array of string` + The function definition. - The keys being held while clicking. + - `arguments: string` - - `double_click: object { keys, type, x, y }` + The arguments that the model expects you to pass to the function. - A double click action. + - `name: string` - - `keys: array of string` + The name of the function. - The keys being held while double-clicking. + - `type: "function"` - - `type: "double_click"` + The type of tool call the output is required for. For now, this is always `function`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `type: "submit_tool_outputs"` - - `x: number` + For now, this is always `submit_tool_outputs`. - The x-coordinate where the double click occurred. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `y: number` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The y-coordinate where the double click occurred. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `drag: object { path, type, keys }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - A drag action. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `path: array of object { x, y }` + - `union_member_0: "auto"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + `auto` is the default value - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `response_format_text: object { type }` - - `x: number` + Default response format. Used to generate text responses. - The x-coordinate. + - `type: "text"` - - `y: number` + The type of response format being defined. Always `text`. - The y-coordinate. + - `response_format_json_object: object { type }` - - `type: "drag"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: "json_object"` - - `keys: optional array of string` + The type of response format being defined. Always `json_object`. - The keys being held while dragging the mouse. + - `response_format_json_schema: object { json_schema, type }` - - `keypress: object { keys, type }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - A collection of keypresses the model would like to perform. + - `json_schema: object { name, description, schema, strict }` - - `keys: array of string` + Structured Outputs configuration options, including a JSON Schema. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `name: string` - - `type: "keypress"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `description: optional string` - - `move: object { type, x, y, keys }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - A mouse move action. + - `schema: optional map[unknown]` - - `type: "move"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Specifies the event type. For a move action, this property is always set to `move`. + - `strict: optional boolean` - - `x: number` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The x-coordinate to move to. + - `type: "json_schema"` - - `y: number` + The type of response format being defined. Always `json_schema`. - The y-coordinate to move to. + - `started_at: number` - - `keys: optional array of string` + The Unix timestamp (in seconds) for when the run was started. - The keys being held while moving the mouse. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `screenshot: object { type }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - A screenshot action. + - `"queued"` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `"in_progress"` - A scroll action. + - `"requires_action"` - - `scroll_x: number` + - `"cancelling"` - The horizontal scroll distance. + - `"cancelled"` - - `scroll_y: number` + - `"failed"` - The vertical scroll distance. + - `"completed"` - - `type: "scroll"` + - `"incomplete"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"expired"` - - `x: number` + - `thread_id: string` - The x-coordinate where the scroll occurred. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `y: number` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - The y-coordinate where the scroll occurred. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `keys: optional array of string` + - `Auto: "none" or "auto" or "required"` - The keys being held while scrolling. + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `type: object { text, type }` + - `"none"` - An action to type in text. + - `"auto"` - - `text: string` + - `"required"` - The text to type. + - `assistant_tool_choice: object { type, function }` - - `type: "type"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - Specifies the event type. For a type action, this property is always set to `type`. + - `type: "function" or "code_interpreter" or "file_search"` - - `wait: object { type }` + The type of the tool. If type is `function`, the function name must be set - A wait action. + - `"function"` - - `actions: optional array of BetaComputerAction` + - `"code_interpreter"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"file_search"` - - `click: object { button, type, x, 2 more }` + - `function: optional object { name }` - A click action. + - `name: string` - - `double_click: object { keys, type, x, y }` + The name of the function to call. - A double click action. + - `tools: array of AssistantTool` - - `drag: object { path, type, keys }` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - A drag action. + - `code_interpreter_tool: object { type }` - - `keypress: object { keys, type }` + - `type: "code_interpreter"` - A collection of keypresses the model would like to perform. + The type of tool being defined: `code_interpreter` - - `move: object { type, x, y, keys }` + - `file_search_tool: object { type, file_search }` - A mouse move action. + - `type: "file_search"` - - `screenshot: object { type }` + The type of tool being defined: `file_search` - A screenshot action. + - `file_search: optional object { max_num_results, ranking_options }` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + Overrides for the file search tool. - A scroll action. + - `max_num_results: optional number` - - `type: object { text, type }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - An action to type in text. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `wait: object { type }` + - `ranking_options: optional object { score_threshold, ranker }` - A wait action. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `agent: optional object { agent_name }` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The agent that produced this item. + - `score_threshold: number` - - `agent_name: string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The canonical name of the agent that produced this item. + - `ranker: optional "auto" or "default_2024_08_21"` - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `id: string` + - `"auto"` - The unique ID of the computer call tool output. + - `"default_2024_08_21"` - - `call_id: string` + - `function_tool: object { function, type }` - The ID of the computer tool call that produced the output. + - `function: object { name, description, parameters, strict }` - - `output: object { type, file_id, image_url }` + - `name: string` - A computer screenshot image used with the computer use tool. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `type: "computer_screenshot"` + - `description: optional string` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + A description of what the function does, used by the model to choose when and how to call the function. - - `file_id: optional string` + - `parameters: optional map[unknown]` - The identifier of an uploaded file that contains the screenshot. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `image_url: optional string` + Omitting `parameters` defines a function with an empty parameter list. - The URL of the screenshot image. + - `strict: optional boolean` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "function"` - - `"completed"` + The type of tool being defined: `function` - - `"incomplete"` + - `truncation_strategy: object { type, last_messages }` - - `"failed"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"in_progress"` + - `type: "auto" or "last_messages"` - - `type: "computer_call_output"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The type of the computer tool call output. Always `computer_call_output`. + - `"auto"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"last_messages"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `last_messages: optional number` - - `id: string` + The number of most recent messages from the thread when constructing the context for the run. - The ID of the pending safety check. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `code: optional string` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The type of the pending safety check. + - `completion_tokens: number` - - `message: optional string` + Number of completion tokens used over the course of the run. - Details about the pending safety check. + - `prompt_tokens: number` - - `agent: optional object { agent_name }` + Number of prompt tokens used over the course of the run. - The agent that produced this item. + - `total_tokens: number` - - `agent_name: string` + Total number of tokens used (prompt + completion). - The canonical name of the agent that produced this item. + - `temperature: optional number` - - `created_by: optional string` + The sampling temperature used for this run. If not set, defaults to 1. - The identifier of the actor that created the item. + - `top_p: optional number` - - `beta_response_function_web_search: object { id, action, status, 2 more }` + The nucleus sampling value used for this run. If not set, defaults to 1. - 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. +### Example - - `id: string` +```cli +openai beta:threads:runs update \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id +``` - The unique ID of the web search tool call. +#### Response - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - 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). +## Submit tool outputs to run - - `search: object { type, queries, query, sources }` +`$ openai beta:threads:runs submit-tool-outputs` - Action type "search" - Performs a web search query. +**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` - - `type: "search"` +When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. - The action type. +### Parameters - - `queries: optional array of string` +- `--thread-id: string` - The search queries. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to which this run belongs. - - `query: optional string` +- `--run-id: string` - The search query. + The ID of the run that requires the tool output submission. - - `sources: optional array of object { type, url }` +- `--tool-output: array of object { output, tool_call_id }` - The sources used in the search. + A list of tools for which the outputs are being submitted. - - `type: "url"` +### Returns - The type of source. Always `url`. +- `run: object { id, assistant_id, cancelled_at, 24 more }` - - `url: string` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - The URL of the source. + - `id: string` - - `open_page: object { type, url }` + The identifier, which can be referenced in API endpoints. - Action type "open_page" - Opens a specific URL from search results. + - `assistant_id: string` - - `type: "open_page"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - The action type. + - `cancelled_at: number` - - `url: optional string` + The Unix timestamp (in seconds) for when the run was cancelled. - The URL opened by the model. + - `completed_at: number` - - `find_in_page: object { pattern, type, url }` + The Unix timestamp (in seconds) for when the run was completed. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `created_at: number` - - `pattern: string` + The Unix timestamp (in seconds) for when the run was created. - The pattern or text to search for within the page. + - `expires_at: number` - - `type: "find_in_page"` + The Unix timestamp (in seconds) for when the run will expire. - The action type. + - `failed_at: number` - - `url: string` + The Unix timestamp (in seconds) for when the run failed. - The URL of the page searched for the pattern. + - `incomplete_details: object { reason }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The status of the web search tool call. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `"in_progress"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"searching"` + - `"max_completion_tokens"` - - `"completed"` + - `"max_prompt_tokens"` - - `"failed"` + - `instructions: string` - - `type: "web_search_call"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the web search tool call. Always `web_search_call`. + - `last_error: object { code, message }` - - `agent: optional object { agent_name }` + The last error associated with this run. Will be `null` if there are no errors. - The agent that produced this item. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `agent_name: string` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The canonical name of the agent that produced this item. + - `"server_error"` - - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` + - `"rate_limit_exceeded"` - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `"invalid_prompt"` - - `id: string` + - `message: string` - The unique ID of the function tool call. + A human-readable description of the error. - - `status: "in_progress" or "completed" or "incomplete"` + - `max_completion_tokens: number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The maximum number of completion tokens specified to have been used over the course of the run. - - `"in_progress"` + - `max_prompt_tokens: number` - - `"completed"` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `"incomplete"` + - `metadata: map[string]` - - `created_by: optional string` + 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. - The identifier of the actor that created the item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + - `model: string` - - `id: string` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The unique ID of the function call tool output. + - `object: "thread.run"` - - `call_id: string` + The object type, which is always `thread.run`. - The unique ID of the function tool call generated by the model. + - `parallel_tool_calls: boolean` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `required_action: object { submit_tool_outputs, type }` - - `string output: string` + Details on the action required to continue the run. Will be `null` if no action is required. - A string of the output of the function call. + - `submit_tool_outputs: object { tool_calls }` - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Details on the tool outputs needed for this run to continue. - Text, image, or file output of the function call. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + A list of the relevant tool calls. - A text input to the model. + - `id: string` - - `text: string` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - The text input to the model. + - `function: object { arguments, name }` - - `type: "input_text"` + The function definition. - The type of the input item. Always `input_text`. + - `arguments: string` - - `prompt_cache_breakpoint: optional object { mode }` + The arguments that the model expects you to pass to the function. - 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. + - `name: string` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The name of the function. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `type: "function"` - - `detail: "low" or "high" or "auto" or "original"` + The type of tool call the output is required for. For now, this is always `function`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "submit_tool_outputs"` - - `type: "input_image"` + For now, this is always `submit_tool_outputs`. - The type of the input item. Always `input_image`. + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `file_id: optional string` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The ID of the file to be sent to the model. + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `image_url: optional string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `prompt_cache_breakpoint: optional object { mode }` + - `union_member_0: "auto"` - 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. + `auto` is the default value - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `response_format_text: object { type }` - A file input to the model. + Default response format. Used to generate text responses. - - `type: "input_file"` + - `type: "text"` - The type of the input item. Always `input_file`. + The type of response format being defined. Always `text`. - - `detail: optional "auto" or "low" or "high"` + - `response_format_json_object: object { type }` - 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`. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `file_data: optional string` + - `type: "json_object"` - The content of the file to be sent to the model. + The type of response format being defined. Always `json_object`. - - `file_id: optional string` + - `response_format_json_schema: object { json_schema, type }` - The ID of the file to be sent to the model. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `file_url: optional string` + - `json_schema: object { name, description, schema, strict }` - The URL of the file to be sent to the model. + Structured Outputs configuration options, including a JSON Schema. - - `filename: optional string` + - `name: string` - The name of the file to be sent to the model. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `prompt_cache_breakpoint: optional object { mode }` + - `description: optional string` - 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. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `status: "in_progress" or "completed" or "incomplete"` + - `schema: optional map[unknown]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"in_progress"` + - `strict: optional boolean` - - `"completed"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"incomplete"` + - `type: "json_schema"` - - `type: "function_call_output"` + The type of response format being defined. Always `json_schema`. - The type of the function tool call output. Always `function_call_output`. + - `started_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run was started. - The agent that produced this item. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `agent_name: string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The canonical name of the agent that produced this item. + - `"queued"` - - `caller: optional object { type } or object { caller_id, type }` + - `"in_progress"` - The execution context that produced this tool call. + - `"requires_action"` - - `direct: object { type }` + - `"cancelling"` - - `program: object { caller_id, type }` + - `"cancelled"` - - `caller_id: string` + - `"failed"` - The call ID of the program item that produced this tool call. + - `"completed"` - - `type: "program"` + - `"incomplete"` - The caller type. Always `program`. + - `"expired"` - - `created_by: optional string` + - `thread_id: string` - The identifier of the actor that created the item. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `agent_message: object { id, author, content, 3 more }` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `id: string` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The unique ID of the agent message. + - `Auto: "none" or "auto" or "required"` - - `author: string` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - The sending agent identity. + - `"none"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"auto"` - Encrypted content sent between agents. + - `"required"` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + - `assistant_tool_choice: object { type, function }` - A text input to the model. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `type: "function" or "code_interpreter" or "file_search"` - A text output from the model. + The type of the tool. If type is `function`, the function name must be set - - `text: object { text, type }` + - `"function"` - A text content. + - `"code_interpreter"` - - `text: string` + - `"file_search"` - - `type: "text"` + - `function: optional object { name }` - - `summary_text: object { text, type }` + - `name: string` - A summary text from the model. + The name of the function to call. - - `text: string` + - `tools: array of AssistantTool` - A summary of the reasoning output from the model so far. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `type: "summary_text"` + - `code_interpreter_tool: object { type }` - The type of the object. Always `summary_text`. + - `type: "code_interpreter"` - - `reasoning_text: object { text, type }` + The type of tool being defined: `code_interpreter` - Reasoning text from the model. + - `file_search_tool: object { type, file_search }` - - `text: string` + - `type: "file_search"` - The reasoning text from the model. + The type of tool being defined: `file_search` - - `type: "reasoning_text"` + - `file_search: optional object { max_num_results, ranking_options }` - The type of the reasoning text. Always `reasoning_text`. + Overrides for the file search tool. - - `beta_response_output_refusal: object { refusal, type }` + - `max_num_results: optional number` - A refusal from the model. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `ranking_options: optional object { score_threshold, ranker }` - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - A screenshot of a computer. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `detail: "low" or "high" or "auto" or "original"` + - `score_threshold: number` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"low"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"high"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - `"auto"` - - `"original"` + - `"default_2024_08_21"` - - `file_id: string` + - `function_tool: object { function, type }` - The identifier of an uploaded file that contains the screenshot. + - `function: object { name, description, parameters, strict }` - - `image_url: string` + - `name: string` - The URL of the screenshot image. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `type: "computer_screenshot"` + - `description: optional string` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + A description of what the function does, used by the model to choose when and how to call the function. - - `prompt_cache_breakpoint: optional object { mode }` + - `parameters: optional map[unknown]` - 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. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `mode: "explicit"` + Omitting `parameters` defines a function with an empty parameter list. - The breakpoint mode. Always `explicit`. + - `strict: optional boolean` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - A file input to the model. + - `type: "function"` - - `encrypted_content: object { encrypted_content, type }` + The type of tool being defined: `function` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `truncation_strategy: object { type, last_messages }` - - `encrypted_content: string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - Opaque encrypted content. + - `type: "auto" or "last_messages"` - - `type: "encrypted_content"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The type of the input item. Always `encrypted_content`. + - `"auto"` - - `recipient: string` + - `"last_messages"` - The destination agent identity. + - `last_messages: optional number` - - `type: "agent_message"` + The number of most recent messages from the thread when constructing the context for the run. - The type of the item. Always `agent_message`. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `agent: optional object { agent_name }` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The agent that produced this item. + - `completion_tokens: number` - - `agent_name: string` + Number of completion tokens used over the course of the run. - The canonical name of the agent that produced this item. + - `prompt_tokens: number` - - `multi_agent_call: object { id, action, arguments, 3 more }` + Number of prompt tokens used over the course of the run. - - `id: string` + - `total_tokens: number` - The unique ID of the multi-agent call item. + Total number of tokens used (prompt + completion). - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `temperature: optional number` - The multi-agent action to execute. + The sampling temperature used for this run. If not set, defaults to 1. - - `"spawn_agent"` + - `top_p: optional number` - - `"interrupt_agent"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `"list_agents"` +### Example - - `"send_message"` +```cli +openai beta:threads:runs submit-tool-outputs \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id \ + --tool-output '{}' +``` - - `"followup_task"` +#### Response - - `"wait_agent"` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `arguments: string` +## Cancel a run - The JSON string of arguments generated for the action. +`$ openai beta:threads:runs cancel` - - `call_id: string` +**post** `/threads/{thread_id}/runs/{run_id}/cancel` - The unique ID linking this call to its output. +Cancels a run that is `in_progress`. - - `type: "multi_agent_call"` +### Parameters - The type of the multi-agent call. Always `multi_agent_call`. +- `--thread-id: string` - - `agent: optional object { agent_name }` + The ID of the thread to which this run belongs. - The agent that produced this item. +- `--run-id: string` - - `agent_name: string` + The ID of the run to cancel. - The canonical name of the agent that produced this item. +### Returns - - `multi_agent_call_output: object { id, action, call_id, 3 more }` +- `run: object { id, assistant_id, cancelled_at, 24 more }` + + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - `id: string` - The unique ID of the multi-agent call output item. + The identifier, which can be referenced in API endpoints. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `assistant_id: string` - The multi-agent action that produced this result. + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - `"spawn_agent"` + - `cancelled_at: number` - - `"interrupt_agent"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `"list_agents"` + - `completed_at: number` - - `"send_message"` + The Unix timestamp (in seconds) for when the run was completed. - - `"followup_task"` + - `created_at: number` - - `"wait_agent"` + The Unix timestamp (in seconds) for when the run was created. - - `call_id: string` + - `expires_at: number` - The unique ID of the multi-agent call. + The Unix timestamp (in seconds) for when the run will expire. - - `output: array of BetaResponseOutputText` + - `failed_at: number` - Text output returned by the multi-agent action. + The Unix timestamp (in seconds) for when the run failed. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `incomplete_details: object { reason }` - The annotations of the text output. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `text: string` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The text output from the model. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `type: "output_text"` + - `"max_completion_tokens"` - The type of the output text. Always `output_text`. + - `"max_prompt_tokens"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `instructions: string` - - `type: "multi_agent_call_output"` + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `last_error: object { code, message }` - - `agent: optional object { agent_name }` + The last error associated with this run. Will be `null` if there are no errors. - The agent that produced this item. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `agent_name: string` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The canonical name of the agent that produced this item. + - `"server_error"` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + - `"rate_limit_exceeded"` - - `id: string` + - `"invalid_prompt"` - The unique ID of the tool search call item. + - `message: string` - - `arguments: unknown` + A human-readable description of the error. - Arguments used for the tool search call. + - `max_completion_tokens: number` - - `call_id: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The unique ID of the tool search call generated by the model. + - `max_prompt_tokens: number` - - `execution: "server" or "client"` + The maximum number of prompt tokens specified to have been used over the course of the run. - Whether tool search was executed by the server or by the client. + - `metadata: map[string]` - - `"server"` + 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. - - `"client"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `status: "in_progress" or "completed" or "incomplete"` + - `model: string` - The status of the tool search call item that was recorded. + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"in_progress"` + - `object: "thread.run"` - - `"completed"` + The object type, which is always `thread.run`. - - `"incomplete"` + - `parallel_tool_calls: boolean` - - `type: "tool_search_call"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The type of the item. Always `tool_search_call`. + - `required_action: object { submit_tool_outputs, type }` - - `agent: optional object { agent_name }` + Details on the action required to continue the run. Will be `null` if no action is required. - The agent that produced this item. + - `submit_tool_outputs: object { tool_calls }` - - `agent_name: string` + Details on the tool outputs needed for this run to continue. - The canonical name of the agent that produced this item. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `created_by: optional string` + A list of the relevant tool calls. - The identifier of the actor that created the item. + - `id: string` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `id: string` + - `function: object { arguments, name }` - The unique ID of the tool search output item. + The function definition. - - `call_id: string` + - `arguments: string` - The unique ID of the tool search call generated by the model. + The arguments that the model expects you to pass to the function. - - `execution: "server" or "client"` + - `name: string` - Whether tool search was executed by the server or by the client. + The name of the function. - - `"server"` + - `type: "function"` - - `"client"` + The type of tool call the output is required for. For now, this is always `function`. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "submit_tool_outputs"` - The status of the tool search output item that was recorded. + For now, this is always `submit_tool_outputs`. - - `"in_progress"` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - - `"completed"` + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `"incomplete"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - `tools: array of BetaTool` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The loaded tool definitions returned by tool search. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `union_member_0: "auto"` - 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). + `auto` is the default value - - `name: string` + - `response_format_text: object { type }` - The name of the function to call. + Default response format. Used to generate text responses. - - `parameters: map[unknown]` + - `type: "text"` - A JSON schema object describing the parameters of the function. + The type of response format being defined. Always `text`. - - `strict: boolean` + - `response_format_json_object: object { type }` - Whether strict parameter validation is enforced for this function tool. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `type: "function"` + - `type: "json_object"` - The type of the function tool. Always `function`. + The type of response format being defined. Always `json_object`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `response_format_json_schema: object { json_schema, type }` - The tool invocation context(s). + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - `"direct"` + - `json_schema: object { name, description, schema, strict }` - - `"programmatic"` + Structured Outputs configuration options, including a JSON Schema. - - `defer_loading: optional boolean` + - `name: string` - Whether this function is deferred and loaded via tool search. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - `description: optional string` - A description of the function. Used by the model to determine whether or not to call the function. - - - `output_schema: optional map[unknown]` + A description of what the response format is for, used by the model to + determine how to respond in the format. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `schema: optional map[unknown]` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - 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). + - `strict: optional boolean` - - `type: "file_search"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - The type of the file search tool. Always `file_search`. + - `type: "json_schema"` - - `vector_store_ids: array of string` + The type of response format being defined. Always `json_schema`. - The IDs of the vector stores to search. + - `started_at: number` - - `filters: optional object { key, type, value } or object { filters, type }` + The Unix timestamp (in seconds) for when the run was started. - A filter to apply. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `Comparison Filter: object { key, type, value }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"queued"` - - `key: string` + - `"in_progress"` - The key to compare against the value. + - `"requires_action"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"cancelling"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"cancelled"` - - `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 + - `"failed"` - - `"eq"` + - `"completed"` - - `"ne"` + - `"incomplete"` - - `"gt"` + - `"expired"` - - `"gte"` + - `thread_id: string` - - `"lt"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `"lte"` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - - `"in"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `"nin"` + - `Auto: "none" or "auto" or "required"` - - `value: string or number or boolean or array of unknown` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"none"` - - `union_member_0: string` + - `"auto"` - - `union_member_1: number` + - `"required"` - - `union_member_2: boolean` + - `assistant_tool_choice: object { type, function }` - - `union_member_3: array of unknown` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `Compound Filter: object { filters, type }` + - `type: "function" or "code_interpreter" or "file_search"` - Combine multiple filters using `and` or `or`. + The type of the tool. If type is `function`, the function name must be set - - `filters: array of object { key, type, value } or unknown` + - `"function"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"code_interpreter"` - - `Comparison Filter: object { key, type, value }` + - `"file_search"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `function: optional object { name }` - - `key: string` + - `name: string` - The key to compare against the value. + The name of the function to call. - - `type: "eq" or "ne" or "gt" or 5 more` + - `tools: array of AssistantTool` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `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 + - `code_interpreter_tool: object { type }` - - `"eq"` + - `type: "code_interpreter"` - - `"ne"` + The type of tool being defined: `code_interpreter` - - `"gt"` + - `file_search_tool: object { type, file_search }` - - `"gte"` + - `type: "file_search"` - - `"lt"` + The type of tool being defined: `file_search` - - `"lte"` + - `file_search: optional object { max_num_results, ranking_options }` - - `"in"` + Overrides for the file search tool. - - `"nin"` + - `max_num_results: optional number` - - `value: string or number or boolean or array of unknown` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The value to compare against the attribute key; supports string, number, or boolean types. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `union_member_0: string` + - `ranking_options: optional object { score_threshold, ranker }` - - `union_member_1: number` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `union_member_2: boolean` + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `union_member_3: array of unknown` + - `score_threshold: number` - - `union_member_1: unknown` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: "and" or "or"` + - `ranker: optional "auto" or "default_2024_08_21"` - Type of operation: `and` or `or`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"and"` + - `"auto"` - - `"or"` + - `"default_2024_08_21"` - - `max_num_results: optional number` + - `function_tool: object { function, type }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `function: object { name, description, parameters, strict }` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `name: string` - Ranking options for search. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `description: optional string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + A description of what the function does, used by the model to choose when and how to call the function. - - `embedding_weight: number` + - `parameters: optional map[unknown]` - The weight of the embedding in the reciprocal ranking fusion. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `text_weight: number` + Omitting `parameters` defines a function with an empty parameter list. - The weight of the text in the reciprocal ranking fusion. + - `strict: optional boolean` - - `ranker: optional "auto" or "default-2024-11-15"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - The ranker to use for the file search. + - `type: "function"` - - `"auto"` + The type of tool being defined: `function` - - `"default-2024-11-15"` + - `truncation_strategy: object { type, last_messages }` - - `score_threshold: optional number` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - 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. + - `type: "auto" or "last_messages"` - - `beta_computer_tool: object { type }` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"auto"` - - `type: "computer"` + - `"last_messages"` - The type of the computer tool. Always `computer`. + - `last_messages: optional number` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The number of most recent messages from the thread when constructing the context for the run. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `display_height: number` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The height of the computer display. + - `completion_tokens: number` - - `display_width: number` + Number of completion tokens used over the course of the run. - The width of the computer display. + - `prompt_tokens: number` - - `environment: "windows" or "mac" or "linux" or 2 more` + Number of prompt tokens used over the course of the run. - The type of computer environment to control. + - `total_tokens: number` - - `"windows"` + Total number of tokens used (prompt + completion). - - `"mac"` + - `temperature: optional number` - - `"linux"` + The sampling temperature used for this run. If not set, defaults to 1. - - `"ubuntu"` + - `top_p: optional number` - - `"browser"` + The nucleus sampling value used for this run. If not set, defaults to 1. - - `type: "computer_use_preview"` +### Example - The type of the computer use tool. Always `computer_use_preview`. +```cli +openai beta:threads:runs cancel \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id +``` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` +#### Response - 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). +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - - `type: "web_search" or "web_search_2025_08_26"` +## Domain Types - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. +### Required Action Function Tool Call - - `"web_search"` +- `required_action_function_tool_call: object { id, function, type }` - - `"web_search_2025_08_26"` + Tool call objects - - `filters: optional object { allowed_domains }` + - `id: string` - Filters for the search. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `allowed_domains: optional array of string` + - `function: object { arguments, name }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The function definition. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `arguments: string` - - `search_context_size: optional "low" or "medium" or "high"` + The arguments that the model expects you to pass to the function. - 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. + - `name: string` - - `"low"` + The name of the function. - - `"medium"` + - `type: "function"` - - `"high"` + The type of tool call the output is required for. For now, this is always `function`. - - `user_location: optional object { city, country, region, 2 more }` +### Run - The approximate location of the user. +- `run: object { id, assistant_id, cancelled_at, 24 more }` - - `city: optional string` + Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - Free text input for the city of the user, e.g. `San Francisco`. + - `id: string` - - `country: optional string` + The identifier, which can be referenced in API endpoints. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `assistant_id: string` - - `region: optional string` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - Free text input for the region of the user, e.g. `California`. + - `cancelled_at: number` - - `timezone: optional string` + The Unix timestamp (in seconds) for when the run was cancelled. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `completed_at: number` - - `type: optional "approximate"` + The Unix timestamp (in seconds) for when the run was completed. - The type of location approximation. Always `approximate`. + - `created_at: number` - - `"approximate"` + The Unix timestamp (in seconds) for when the run was created. - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `expires_at: number` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The Unix timestamp (in seconds) for when the run will expire. - - `server_label: string` + - `failed_at: number` - A label for this MCP server, used to identify it in tool calls. + The Unix timestamp (in seconds) for when the run failed. - - `type: "mcp"` + - `incomplete_details: object { reason }` - The type of the MCP tool. Always `mcp`. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The tool invocation context(s). + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"direct"` + - `"max_completion_tokens"` - - `"programmatic"` + - `"max_prompt_tokens"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `instructions: string` - List of allowed tool names or a filter object. + The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `MCP allowed tools: array of string` + - `last_error: object { code, message }` - A string array of allowed tool names + The last error associated with this run. Will be `null` if there are no errors. - - `MCP tool filter: object { read_only, tool_names }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - A filter object to specify which tools are allowed. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `read_only: optional boolean` + - `"server_error"` - 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. + - `"rate_limit_exceeded"` - - `tool_names: optional array of string` + - `"invalid_prompt"` - List of allowed tool names. + - `message: string` - - `authorization: optional string` + A human-readable description of the error. - 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. + - `max_completion_tokens: number` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The maximum number of completion tokens specified to have been used over the course of the run. - 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). + - `max_prompt_tokens: number` - Currently supported `connector_id` values are: + The maximum number of prompt tokens specified to have been used over the course of the run. - - 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` + - `metadata: map[string]` - - `"connector_dropbox"` + 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. - - `"connector_gmail"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"connector_googlecalendar"` + - `model: string` - - `"connector_googledrive"` + The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"connector_microsoftteams"` + - `object: "thread.run"` - - `"connector_outlookcalendar"` + The object type, which is always `thread.run`. - - `"connector_outlookemail"` + - `parallel_tool_calls: boolean` - - `"connector_sharepoint"` + Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `defer_loading: optional boolean` + - `required_action: object { submit_tool_outputs, type }` - Whether this MCP tool is deferred and discovered via tool search. + Details on the action required to continue the run. Will be `null` if no action is required. - - `headers: optional map[string]` + - `submit_tool_outputs: object { tool_calls }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Details on the tool outputs needed for this run to continue. - - `require_approval: optional object { always, never } or "always" or "never"` + - `tool_calls: array of RequiredActionFunctionToolCall` - Specify which of the MCP server's tools require approval. + A list of the relevant tool calls. - - `MCP tool approval filter: object { always, never }` + - `id: string` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - `always: optional object { read_only, tool_names }` + - `function: object { arguments, name }` - A filter object to specify which tools are allowed. + The function definition. - - `read_only: optional boolean` + - `arguments: string` - 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. + The arguments that the model expects you to pass to the function. - - `tool_names: optional array of string` + - `name: string` - List of allowed tool names. + The name of the function. - - `never: optional object { read_only, tool_names }` + - `type: "function"` - A filter object to specify which tools are allowed. + The type of tool call the output is required for. For now, this is always `function`. - - `read_only: optional boolean` + - `type: "submit_tool_outputs"` - 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. + For now, this is always `submit_tool_outputs`. - - `tool_names: optional array of string` + - `response_format: "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema` - List of allowed tool names. + Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `MCP tool approval setting: "always" or "never"` + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - 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. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"always"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `"never"` + - `union_member_0: "auto"` - - `server_description: optional string` + `auto` is the default value - Optional description of the MCP server, used to provide more context. + - `response_format_text: object { type }` - - `server_url: optional string` + Default response format. Used to generate text responses. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `type: "text"` - - `tunnel_id: optional string` + The type of response format being defined. Always `text`. - 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. + - `response_format_json_object: object { type }` - - `code_interpreter: object { container, type, allowed_callers }` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - A tool that runs Python code to help generate a response to a prompt. + - `type: "json_object"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The type of response format being defined. Always `json_object`. - 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. + - `response_format_json_schema: object { json_schema, type }` - - `union_member_0: string` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - The container ID. + - `json_schema: object { name, description, schema, strict }` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` + Structured Outputs configuration options, including a JSON Schema. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `name: string` - - `type: "auto"` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - Always `auto`. + - `description: optional string` - - `file_ids: optional array of string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - An optional list of uploaded files to make available to your code. + - `schema: optional map[unknown]` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The memory limit for the code interpreter container. + - `strict: optional boolean` - - `"1g"` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://platform.openai.com/docs/guides/structured-outputs). - - `"4g"` + - `type: "json_schema"` - - `"16g"` + The type of response format being defined. Always `json_schema`. - - `"64g"` + - `started_at: number` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The Unix timestamp (in seconds) for when the run was started. - Network access policy for the container. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `beta_container_network_policy_disabled: object { type }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `type: "disabled"` + - `"queued"` - Disable outbound network access. Always `disabled`. + - `"in_progress"` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + - `"requires_action"` - - `allowed_domains: array of string` + - `"cancelling"` - A list of allowed domains when type is `allowlist`. + - `"cancelled"` - - `type: "allowlist"` + - `"failed"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `"completed"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `"incomplete"` - Optional domain-scoped secrets for allowlisted domains. + - `"expired"` - - `domain: string` + - `thread_id: string` - The domain associated with the secret. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - `name: string` + - `tool_choice: "none" or "auto" or "required" or AssistantToolChoice` - The name of the secret to inject for the domain. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `value: string` + - `Auto: "none" or "auto" or "required"` - The secret value to inject for the domain. + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `type: "code_interpreter"` + - `"none"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"auto"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"required"` - The tool invocation context(s). + - `assistant_tool_choice: object { type, function }` - - `"direct"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `"programmatic"` + - `type: "function" or "code_interpreter" or "file_search"` - - `programmatic_tool_calling: object { type }` + The type of the tool. If type is `function`, the function name must be set - - `image_generation: object { type, action, background, 9 more }` + - `"function"` - A tool that generates images using the GPT image models. + - `"code_interpreter"` - - `type: "image_generation"` + - `"file_search"` - The type of the image generation tool. Always `image_generation`. + - `function: optional object { name }` - - `action: optional "generate" or "edit" or "auto"` + - `name: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The name of the function to call. - - `"generate"` + - `tools: array of AssistantTool` - - `"edit"` + The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `"auto"` + - `code_interpreter_tool: object { type }` - - `background: optional "transparent" or "opaque" or "auto"` + - `type: "code_interpreter"` - 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. + The type of tool being defined: `code_interpreter` - `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. + - `file_search_tool: object { type, file_search }` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `type: "file_search"` - - `"transparent"` + The type of tool being defined: `file_search` - - `"opaque"` + - `file_search: optional object { max_num_results, ranking_options }` - - `"auto"` + Overrides for the file search tool. - - `input_fidelity: optional "high" or "low"` + - `max_num_results: optional number` - 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`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `"high"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"low"` + - `ranking_options: optional object { score_threshold, ranker }` - - `input_image_mask: optional object { file_id, image_url }` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `file_id: optional string` + - `score_threshold: number` - File ID for the mask image. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `image_url: optional string` + - `ranker: optional "auto" or "default_2024_08_21"` - Base64-encoded mask image. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"auto"` - The image generation model to use. Default: `gpt-image-1`. + - `"default_2024_08_21"` - - `"gpt-image-1"` + - `function_tool: object { function, type }` - - `"gpt-image-1-mini"` + - `function: object { name, description, parameters, strict }` - - `"gpt-image-2"` + - `name: string` - - `"gpt-image-2-2026-04-21"` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `"gpt-image-1.5"` + - `description: optional string` - - `"chatgpt-image-latest"` + A description of what the function does, used by the model to choose when and how to call the function. - - `moderation: optional "auto" or "low"` + - `parameters: optional map[unknown]` - Moderation level for the generated image. Default: `auto`. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `"auto"` + Omitting `parameters` defines a function with an empty parameter list. - - `"low"` + - `strict: optional boolean` - - `output_compression: optional number` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - Compression level for the output image. Default: 100. + - `type: "function"` - - `output_format: optional "png" or "webp" or "jpeg"` + The type of tool being defined: `function` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `truncation_strategy: object { type, last_messages }` - - `"png"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"webp"` + - `type: "auto" or "last_messages"` - - `"jpeg"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `partial_images: optional number` + - `"auto"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"last_messages"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `last_messages: optional number` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The number of most recent messages from the thread when constructing the context for the run. - - `"low"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"medium"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `"high"` + - `completion_tokens: number` - - `"auto"` + Number of completion tokens used over the course of the run. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `prompt_tokens: number` - 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`. + Number of prompt tokens used over the course of the run. - - `"1024x1024"` + - `total_tokens: number` - - `"1024x1536"` + Total number of tokens used (prompt + completion). - - `"1536x1024"` + - `temperature: optional number` - - `"auto"` + The sampling temperature used for this run. If not set, defaults to 1. - - `local_shell: object { type }` + - `top_p: optional number` - A tool that allows the model to execute shell commands in a local environment. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `beta_function_shell_tool: object { type, allowed_callers, environment }` +### Run Status - A tool that allows the model to execute shell commands. +- `run_status: "queued" or "in_progress" or "requires_action" or 6 more` - - `type: "shell"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The type of the shell tool. Always `shell`. + - `"queued"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"in_progress"` - The tool invocation context(s). + - `"requires_action"` - - `"direct"` + - `"cancelling"` - - `"programmatic"` + - `"cancelled"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"failed"` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + - `"completed"` - - `type: "container_auto"` + - `"incomplete"` - Automatically creates a container for this request + - `"expired"` - - `file_ids: optional array of string` +# Steps - An optional list of uploaded files to make available to your code. +## List run steps - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` +`$ openai beta:threads:runs:steps list` - The memory limit for the container. +**get** `/threads/{thread_id}/runs/{run_id}/steps` - - `"1g"` +Returns a list of run steps belonging to a run. - - `"4g"` +### Parameters - - `"16g"` +- `--thread-id: string` - - `"64g"` + The ID of the thread the run and run steps belong to. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` +- `--run-id: string` - Network access policy for the container. + The ID of the run the run steps belong to. - - `beta_container_network_policy_disabled: object { type }` +- `--after: optional string` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` +- `--before: optional string` - An optional list of skills referenced by id or inline data. + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - - `beta_skill_reference: object { skill_id, type, version }` +- `--include: optional array of RunStepInclude` - - `skill_id: string` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - The ID of the referenced skill. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "skill_reference"` +- `--limit: optional number` - References a skill created with the /v1/skills endpoint. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `version: optional string` +- `--order: optional "asc" or "desc"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `beta_inline_skill: object { description, name, source, type }` +### Returns - - `description: string` +- `ListRunStepsResponse: object { data, first_id, has_more, 2 more }` - The description of the skill. + - `data: array of RunStep` - - `name: string` + - `id: string` - The name of the skill. + The identifier of the run step, which can be referenced in API endpoints. - - `source: object { data, media_type, type }` + - `assistant_id: string` - Inline skill payload + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `data: string` + - `cancelled_at: number` - Base64-encoded skill zip bundle. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `media_type: "application/zip"` + - `completed_at: number` - The media type of the inline skill payload. Must be `application/zip`. + The Unix timestamp (in seconds) for when the run step completed. - - `type: "base64"` + - `created_at: number` - The type of the inline skill source. Must be `base64`. + The Unix timestamp (in seconds) for when the run step was created. - - `type: "inline"` + - `expired_at: number` - Defines an inline skill for this request. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `beta_local_environment: object { type, skills }` + - `failed_at: number` - - `type: "local"` + The Unix timestamp (in seconds) for when the run step failed. - Use a local computer environment. + - `last_error: object { code, message }` - - `skills: optional array of BetaLocalSkill` + The last error associated with this run step. Will be `null` if there are no errors. - An optional list of skills. + - `code: "server_error" or "rate_limit_exceeded"` - - `description: string` + One of `server_error` or `rate_limit_exceeded`. - The description of the skill. + - `"server_error"` - - `name: string` + - `"rate_limit_exceeded"` - The name of the skill. + - `message: string` - - `path: string` + A human-readable description of the error. - The path to the directory containing the skill. + - `metadata: map[string]` - - `beta_container_reference: object { container_id, type }` + 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. - - `container_id: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The ID of the referenced container. + - `object: "thread.run.step"` - - `type: "container_reference"` + The object type, which is always `thread.run.step`. - References a container created with the /v1/containers endpoint + - `run_id: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - 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) + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `name: string` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The name of the custom tool, used to identify it in tool calls. + - `"in_progress"` - - `type: "custom"` + - `"cancelled"` - The type of the custom tool. Always `custom`. + - `"failed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"completed"` - The tool invocation context(s). + - `"expired"` - - `"direct"` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `"programmatic"` + The details of the run step. - - `defer_loading: optional boolean` + - `message_creation_step_details: object { message_creation, type }` - Whether this tool should be deferred and discovered via tool search. + Details of the message creation by the run step. - - `description: optional string` + - `message_creation: object { message_id }` - Optional description of the custom tool, used to provide more context. + - `message_id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The ID of the message that was created by this run step. - The input format for the custom tool. Default is unconstrained text. + - `type: "message_creation"` - - `text: object { type }` + Always `message_creation`. - Unconstrained free-form text. + - `tool_calls_step_details: object { tool_calls, type }` - - `grammar: object { definition, syntax, type }` + Details of the tool call. - A grammar defined by the user. + - `tool_calls: array of ToolCall` - - `definition: string` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The grammar definition. + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - - `syntax: "lark" or "regex"` + Details of the Code Interpreter tool call the run step was involved in. - The syntax of the grammar definition. One of `lark` or `regex`. + - `id: string` - - `"lark"` + The ID of the tool call. - - `"regex"` + - `code_interpreter: object { input, outputs }` - - `type: "grammar"` + The Code Interpreter tool call definition. - Grammar format. Always `grammar`. + - `input: string` - - `beta_namespace_tool: object { description, name, tools, type }` + The input to the Code Interpreter tool call. - Groups function/custom tools under a shared namespace. + - `outputs: array of object { logs, type } or object { image, type }` - - `description: string` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - A description of the namespace shown to the model. + - `logs: object { logs, type }` - - `name: string` + Text output from the Code Interpreter tool call as part of a run step. - The namespace name used in tool calls (for example, `crm`). + - `logs: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + The text output from the Code Interpreter tool call. - The function/custom tools available inside this namespace. + - `type: "logs"` - - `function: object { name, type, allowed_callers, 5 more }` + Always `logs`. - - `name: string` + - `image: object { image, type }` - - `type: "function"` + - `image: object { file_id }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `file_id: string` - The tool invocation context(s). + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `"direct"` + - `type: "image"` - - `"programmatic"` + Always `image`. - - `defer_loading: optional boolean` + - `type: "code_interpreter"` - Whether this function should be deferred and discovered via tool search. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `description: optional string` + - `file_search_tool_call: object { id, file_search, type }` - - `output_schema: optional map[unknown]` + - `id: string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The ID of the tool call object. - - `parameters: optional unknown` + - `file_search: object { ranking_options, results }` - - `strict: optional boolean` + For now, this is always going to be an empty object. - 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. + - `ranking_options: optional object { ranker, score_threshold }` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The ranking options for the file search. - 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) + - `ranker: "auto" or "default_2024_08_21"` - - `name: string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The name of the custom tool, used to identify it in tool calls. + - `"auto"` - - `type: "custom"` + - `"default_2024_08_21"` - The type of the custom tool. Always `custom`. + - `score_threshold: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The tool invocation context(s). + - `results: optional array of object { file_id, file_name, score, content }` - - `defer_loading: optional boolean` + The results of the file search. - Whether this tool should be deferred and discovered via tool search. + - `file_id: string` - - `description: optional string` + The ID of the file that result was found in. - Optional description of the custom tool, used to provide more context. + - `file_name: string` - - `format: optional object { type } or object { definition, syntax, type }` + The name of the file that result was found in. - The input format for the custom tool. Default is unconstrained text. + - `score: number` - - `type: "namespace"` + The score of the result. All values must be a floating point number between 0 and 1. - The type of the tool. Always `namespace`. + - `content: optional array of object { text, type }` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + The content of the result that was found. The content is only included if requested via the include query parameter. - Hosted or BYOT tool search configuration for deferred tools. + - `text: optional string` - - `type: "tool_search"` + The text content of the file. - The type of the tool. Always `tool_search`. + - `type: optional "text"` - - `description: optional string` + The type of the content. - Description shown to the model for a client-executed tool search tool. + - `"text"` - - `execution: optional "server" or "client"` + - `type: "file_search"` - Whether tool search is executed by the server or by the client. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"server"` + - `function_tool_call: object { id, function, type }` - - `"client"` + - `id: string` - - `parameters: optional unknown` + The ID of the tool call object. - Parameter schema for a client-executed tool search tool. + - `function: object { arguments, name, output }` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The definition of the function that was called. - 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). + - `arguments: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The arguments passed to the function. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `name: string` - - `"web_search_preview"` + The name of the function. - - `"web_search_preview_2025_03_11"` + - `output: string` - - `search_content_types: optional array of "text" or "image"` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `"text"` + - `type: "function"` - - `"image"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "tool_calls"` - 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. + Always `tool_calls`. - - `"low"` + - `thread_id: string` - - `"medium"` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `"high"` + - `type: "message_creation" or "tool_calls"` - - `user_location: optional object { type, city, country, 2 more }` + The type of run step, which can be either `message_creation` or `tool_calls`. - The user's location. + - `"message_creation"` - - `type: "approximate"` + - `"tool_calls"` - The type of location approximation. Always `approximate`. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `city: optional string` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - Free text input for the city of the user, e.g. `San Francisco`. + - `completion_tokens: number` - - `country: optional string` + Number of completion tokens used over the course of the run step. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `prompt_tokens: number` - - `region: optional string` + Number of prompt tokens used over the course of the run step. - Free text input for the region of the user, e.g. `California`. + - `total_tokens: number` - - `timezone: optional string` + Total number of tokens used (prompt + completion). - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `first_id: string` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `has_more: boolean` - Allows the assistant to create, delete, or update files using unified diffs. + - `last_id: string` - - `type: "apply_patch"` + - `object: string` - The type of the tool. Always `apply_patch`. +### Example - - `allowed_callers: optional array of "direct" or "programmatic"` +```cli +openai beta:threads:runs:steps list \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id +``` - The tool invocation context(s). +#### Response - - `"direct"` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } + } + ], + "first_id": "step_abc123", + "has_more": false, + "last_id": "step_abc456", + "object": "list" +} +``` - - `"programmatic"` +## Retrieve run step - - `type: "tool_search_output"` +`$ openai beta:threads:runs:steps retrieve` - The type of the item. Always `tool_search_output`. +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` - - `agent: optional object { agent_name }` +Retrieves a run step. - The agent that produced this item. +### Parameters - - `agent_name: string` +- `--thread-id: string` - The canonical name of the agent that produced this item. + The ID of the thread to which the run and run step belongs. - - `created_by: optional string` +- `--run-id: string` - The identifier of the actor that created the item. + The ID of the run to which the run step belongs. - - `additional_tools: object { id, role, tools, 2 more }` +- `--step-id: string` - - `id: string` + The ID of the run step to retrieve. - The unique ID of the additional tools item. +- `--include: optional array of RunStepInclude` - - `role: "unknown" or "user" or "assistant" or 5 more` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - The role that provided the additional tools. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"unknown"` +### Returns - - `"user"` +- `run_step: object { id, assistant_id, cancelled_at, 13 more }` - - `"assistant"` + Represents a step in execution of a run. - - `"system"` + - `id: string` - - `"critic"` + The identifier of the run step, which can be referenced in API endpoints. - - `"discriminator"` + - `assistant_id: string` - - `"developer"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `"tool"` + - `cancelled_at: number` - - `tools: array of BetaTool` + The Unix timestamp (in seconds) for when the run step was cancelled. - The additional tool definitions made available at this item. + - `completed_at: number` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The Unix timestamp (in seconds) for when the run step completed. - 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). + - `created_at: number` - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + The Unix timestamp (in seconds) for when the run step was created. - 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). + - `expired_at: number` - - `beta_computer_tool: object { type }` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `failed_at: number` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + The Unix timestamp (in seconds) for when the run step failed. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `last_error: object { code, message }` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The last error associated with this run step. Will be `null` if there are no errors. - 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). + - `code: "server_error" or "rate_limit_exceeded"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + One of `server_error` or `rate_limit_exceeded`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `"server_error"` - - `code_interpreter: object { container, type, allowed_callers }` + - `"rate_limit_exceeded"` - A tool that runs Python code to help generate a response to a prompt. + - `message: string` - - `programmatic_tool_calling: object { type }` + A human-readable description of the error. - - `image_generation: object { type, action, background, 9 more }` + - `metadata: map[string]` - A tool that generates images using the GPT image models. + 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. - - `local_shell: object { type }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A tool that allows the model to execute shell commands in a local environment. + - `object: "thread.run.step"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + The object type, which is always `thread.run.step`. - A tool that allows the model to execute shell commands. + - `run_id: string` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - 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) + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `beta_namespace_tool: object { description, name, tools, type }` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - Groups function/custom tools under a shared namespace. + - `"in_progress"` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `"cancelled"` - Hosted or BYOT tool search configuration for deferred tools. + - `"failed"` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `"completed"` - 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). + - `"expired"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - Allows the assistant to create, delete, or update files using unified diffs. + The details of the run step. - - `type: "additional_tools"` + - `message_creation_step_details: object { message_creation, type }` - The type of the item. Always `additional_tools`. + Details of the message creation by the run step. - - `agent: optional object { agent_name }` + - `message_creation: object { message_id }` - The agent that produced this item. + - `message_id: string` - - `agent_name: string` + The ID of the message that was created by this run step. - The canonical name of the agent that produced this item. + - `type: "message_creation"` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + Always `message_creation`. - 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). + - `tool_calls_step_details: object { tool_calls, type }` - - `id: string` + Details of the tool call. - The unique identifier of the reasoning content. + - `tool_calls: array of ToolCall` - - `summary: array of object { text, type }` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - Reasoning summary content. + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - - `text: string` + Details of the Code Interpreter tool call the run step was involved in. - A summary of the reasoning output from the model so far. + - `id: string` - - `type: "summary_text"` + The ID of the tool call. - The type of the object. Always `summary_text`. + - `code_interpreter: object { input, outputs }` - - `type: "reasoning"` + The Code Interpreter tool call definition. - The type of the object. Always `reasoning`. + - `input: string` - - `agent: optional object { agent_name }` + The input to the Code Interpreter tool call. - The agent that produced this item. + - `outputs: array of object { logs, type } or object { image, type }` - - `agent_name: string` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The canonical name of the agent that produced this item. + - `logs: object { logs, type }` - - `content: optional array of object { text, type }` + Text output from the Code Interpreter tool call as part of a run step. - Reasoning text content. + - `logs: string` - - `text: string` + The text output from the Code Interpreter tool call. - The reasoning text from the model. + - `type: "logs"` - - `type: "reasoning_text"` + Always `logs`. - The type of the reasoning text. Always `reasoning_text`. + - `image: object { image, type }` - - `encrypted_content: optional string` + - `image: object { file_id }` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `file_id: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "image"` - - `"in_progress"` + Always `image`. - - `"completed"` + - `type: "code_interpreter"` - - `"incomplete"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `program: object { id, call_id, code, 3 more }` + - `file_search_tool_call: object { id, file_search, type }` - `id: string` - The unique ID of the program item. + The ID of the tool call object. - - `call_id: string` + - `file_search: object { ranking_options, results }` - The stable call ID of the program item. + For now, this is always going to be an empty object. - - `code: string` + - `ranking_options: optional object { ranker, score_threshold }` - The JavaScript source executed by programmatic tool calling. + The ranking options for the file search. - - `fingerprint: string` + - `ranker: "auto" or "default_2024_08_21"` - Opaque program replay fingerprint that must be round-tripped. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `type: "program"` + - `"auto"` - The type of the item. Always `program`. + - `"default_2024_08_21"` - - `agent: optional object { agent_name }` + - `score_threshold: number` - The agent that produced this item. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `agent_name: string` + - `results: optional array of object { file_id, file_name, score, content }` - The canonical name of the agent that produced this item. + The results of the file search. - - `program_output: object { id, call_id, result, 3 more }` + - `file_id: string` - - `id: string` + The ID of the file that result was found in. - The unique ID of the program output item. + - `file_name: string` - - `call_id: string` + The name of the file that result was found in. - The call ID of the program item. + - `score: number` - - `result: string` + The score of the result. All values must be a floating point number between 0 and 1. - The result produced by the program item. + - `content: optional array of object { text, type }` - - `status: "completed" or "incomplete"` + The content of the result that was found. The content is only included if requested via the include query parameter. - The terminal status of the program output item. + - `text: optional string` - - `"completed"` + The text content of the file. - - `"incomplete"` + - `type: optional "text"` - - `type: "program_output"` + The type of the content. - The type of the item. Always `program_output`. + - `"text"` - - `agent: optional object { agent_name }` + - `type: "file_search"` - The agent that produced this item. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `agent_name: string` + - `function_tool_call: object { id, function, type }` - The canonical name of the agent that produced this item. + - `id: string` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + The ID of the tool call object. - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + - `function: object { arguments, name, output }` - - `id: string` + The definition of the function that was called. - The unique ID of the compaction item. + - `arguments: string` - - `encrypted_content: string` + The arguments passed to the function. - The encrypted content that was produced by compaction. + - `name: string` - - `type: "compaction"` + The name of the function. - The type of the item. Always `compaction`. + - `output: string` - - `agent: optional object { agent_name }` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The agent that produced this item. + - `type: "function"` - - `agent_name: string` + The type of tool call. This is always going to be `function` for this type of tool call. - The canonical name of the agent that produced this item. + - `type: "tool_calls"` - - `created_by: optional string` + Always `tool_calls`. - The identifier of the actor that created the item. + - `thread_id: string` - - `image_generation_call: object { id, result, status, 2 more }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - An image generation request made by the model. + - `type: "message_creation" or "tool_calls"` - - `id: string` + The type of run step, which can be either `message_creation` or `tool_calls`. - The unique ID of the image generation call. + - `"message_creation"` - - `result: string` + - `"tool_calls"` - The generated image encoded in base64. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The status of the image generation call. + - `completion_tokens: number` - - `"in_progress"` + Number of completion tokens used over the course of the run step. - - `"completed"` + - `prompt_tokens: number` - - `"generating"` + Number of prompt tokens used over the course of the run step. - - `"failed"` + - `total_tokens: number` - - `type: "image_generation_call"` + Total number of tokens used (prompt + completion). - The type of the image generation call. Always `image_generation_call`. +### Example - - `agent: optional object { agent_name }` +```cli +openai beta:threads:runs:steps retrieve \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id \ + --step-id step_id +``` - The agent that produced this item. +#### Response - - `agent_name: string` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` - The canonical name of the agent that produced this item. +## Domain Types - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` +### Code Interpreter Logs - A tool call to run code. +- `code_interpreter_logs: object { index, type, logs }` - - `id: string` + Text output from the Code Interpreter tool call as part of a run step. - The unique ID of the code interpreter tool call. + - `index: number` - - `code: string` + The index of the output in the outputs array. - The code to run, or null if not available. + - `type: "logs"` - - `container_id: string` + Always `logs`. - The ID of the container used to run the code. + - `logs: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + The text output from the Code Interpreter tool call. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. +### Code Interpreter Output Image - - `logs: object { logs, type }` +- `code_interpreter_output_image: object { index, type, image }` - The logs output from the code interpreter. + - `index: number` - - `logs: string` + The index of the output in the outputs array. - The logs output from the code interpreter. + - `type: "image"` - - `type: "logs"` + Always `image`. - The type of the output. Always `logs`. + - `image: optional object { file_id }` - - `image: object { type, url }` + - `file_id: optional string` - The image output from the code interpreter. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `type: "image"` +### Code Interpreter Tool Call - The type of the output. Always `image`. +- `code_interpreter_tool_call: object { id, code_interpreter, type }` - - `url: string` + Details of the Code Interpreter tool call the run step was involved in. - The URL of the image output from the code interpreter. + - `id: string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The ID of the tool call. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `code_interpreter: object { input, outputs }` - - `"in_progress"` + The Code Interpreter tool call definition. - - `"completed"` + - `input: string` - - `"incomplete"` + The input to the Code Interpreter tool call. - - `"interpreting"` + - `outputs: array of object { logs, type } or object { image, type }` - - `"failed"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `type: "code_interpreter_call"` + - `logs: object { logs, type }` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Text output from the Code Interpreter tool call as part of a run step. - - `agent: optional object { agent_name }` + - `logs: string` - The agent that produced this item. + The text output from the Code Interpreter tool call. - - `agent_name: string` + - `type: "logs"` - The canonical name of the agent that produced this item. + Always `logs`. - - `local_shell_call: object { id, action, call_id, 3 more }` + - `image: object { image, type }` - A tool call to run a command on the local shell. + - `image: object { file_id }` - - `id: string` + - `file_id: string` - The unique ID of the local shell call. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `action: object { command, env, type, 3 more }` + - `type: "image"` - Execute a shell command on the server. + Always `image`. - - `command: array of string` + - `type: "code_interpreter"` - The command to run. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `env: map[string]` +### Code Interpreter Tool Call Delta - Environment variables to set for the command. +- `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - - `type: "exec"` + Details of the Code Interpreter tool call the run step was involved in. - The type of the local shell action. Always `exec`. + - `index: number` - - `timeout_ms: optional number` + The index of the tool call in the tool calls array. - Optional timeout in milliseconds for the command. + - `type: "code_interpreter"` - - `user: optional string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - Optional user to run the command as. + - `id: optional string` - - `working_directory: optional string` + The ID of the tool call. - Optional working directory to run the command in. + - `code_interpreter: optional object { input, outputs }` - - `call_id: string` + The Code Interpreter tool call definition. - The unique ID of the local shell tool call generated by the model. + - `input: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The input to the Code Interpreter tool call. - The status of the local shell call. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `"in_progress"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `"completed"` + - `code_interpreter_logs: object { index, type, logs }` - - `"incomplete"` + Text output from the Code Interpreter tool call as part of a run step. - - `type: "local_shell_call"` + - `index: number` - The type of the local shell call. Always `local_shell_call`. + The index of the output in the outputs array. - - `agent: optional object { agent_name }` + - `type: "logs"` - The agent that produced this item. + Always `logs`. - - `agent_name: string` + - `logs: optional string` - The canonical name of the agent that produced this item. + The text output from the Code Interpreter tool call. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `code_interpreter_output_image: object { index, type, image }` - The output of a local shell tool call. + - `index: number` - - `id: string` + The index of the output in the outputs array. - The unique ID of the local shell tool call generated by the model. + - `type: "image"` - - `output: string` + Always `image`. - A JSON string of the output of the local shell tool call. + - `image: optional object { file_id }` - - `type: "local_shell_call_output"` + - `file_id: optional string` - The type of the local shell tool call output. Always `local_shell_call_output`. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `agent: optional object { agent_name }` +### File Search Tool Call - The agent that produced this item. +- `file_search_tool_call: object { id, file_search, type }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The ID of the tool call object. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `file_search: object { ranking_options, results }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + For now, this is always going to be an empty object. - - `"in_progress"` + - `ranking_options: optional object { ranker, score_threshold }` - - `"completed"` + The ranking options for the file search. - - `"incomplete"` + - `ranker: "auto" or "default_2024_08_21"` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + The ranker to use for the file search. If not specified will use the `auto` ranker. - A tool call that executes one or more shell commands in a managed environment. + - `"auto"` - - `id: string` + - `"default_2024_08_21"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `score_threshold: number` - - `action: object { commands, max_output_length, timeout_ms }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The shell commands and limits that describe how to run the tool call. + - `results: optional array of object { file_id, file_name, score, content }` - - `commands: array of string` + The results of the file search. - - `max_output_length: number` + - `file_id: string` - Optional maximum number of characters to return from each command. + The ID of the file that result was found in. - - `timeout_ms: number` + - `file_name: string` - Optional timeout in milliseconds for the commands. + The name of the file that result was found in. - - `call_id: string` + - `score: number` - The unique ID of the shell tool call generated by the model. + The score of the result. All values must be a floating point number between 0 and 1. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `content: optional array of object { text, type }` - Represents the use of a local environment to perform shell actions. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `beta_response_local_environment: object { type }` + - `text: optional string` - Represents the use of a local environment to perform shell actions. + The text content of the file. - - `type: "local"` + - `type: optional "text"` - The environment type. Always `local`. + The type of the content. - - `beta_response_container_reference: object { container_id, type }` + - `"text"` - Represents a container created with /v1/containers. + - `type: "file_search"` - - `container_id: string` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `type: "container_reference"` +### File Search Tool Call Delta - The environment type. Always `container_reference`. +- `file_search_tool_call_delta: object { file_search, index, type, id }` - - `status: "in_progress" or "completed" or "incomplete"` + - `file_search: unknown` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + For now, this is always going to be an empty object. - - `"in_progress"` + - `index: number` - - `"completed"` + The index of the tool call in the tool calls array. - - `"incomplete"` + - `type: "file_search"` - - `type: "shell_call"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The type of the item. Always `shell_call`. + - `id: optional string` + + The ID of the tool call object. + +### Function Tool Call - - `agent: optional object { agent_name }` +- `function_tool_call: object { id, function, type }` - The agent that produced this item. + - `id: string` - - `agent_name: string` + The ID of the tool call object. - The canonical name of the agent that produced this item. + - `function: object { arguments, name, output }` - - `caller: optional object { type } or object { caller_id, type }` + The definition of the function that was called. - The execution context that produced this tool call. + - `arguments: string` - - `direct: object { type }` + The arguments passed to the function. - - `program: object { caller_id, type }` + - `name: string` - - `caller_id: string` + The name of the function. - The call ID of the program item that produced this tool call. + - `output: string` - - `type: "program"` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `created_by: optional string` + - `type: "function"` - The ID of the entity that created this tool call. + The type of tool call. This is always going to be `function` for this type of tool call. - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` +### Function Tool Call Delta - The output of a shell tool call that was emitted. +- `function_tool_call_delta: object { index, type, id, function }` - - `id: string` + - `index: number` - The unique ID of the shell call output. Populated when this item is returned via API. + The index of the tool call in the tool calls array. - - `call_id: string` + - `type: "function"` - The unique ID of the shell tool call generated by the model. + The type of tool call. This is always going to be `function` for this type of tool call. - - `max_output_length: number` + - `id: optional string` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The ID of the tool call object. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `function: optional object { arguments, name, output }` - An array of shell call output contents + The definition of the function that was called. - - `outcome: object { type } or object { exit_code, type }` + - `arguments: optional string` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The arguments passed to the function. - - `timeout: object { type }` + - `name: optional string` - Indicates that the shell call exceeded its configured time limit. + The name of the function. - - `exit: object { exit_code, type }` + - `output: optional string` - Indicates that the shell commands finished and returned an exit code. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `exit_code: number` +### Message Creation Step Details - Exit code from the shell process. +- `message_creation_step_details: object { message_creation, type }` - - `type: "exit"` + Details of the message creation by the run step. - The outcome type. Always `exit`. + - `message_creation: object { message_id }` - - `stderr: string` + - `message_id: string` - The standard error output that was captured. + The ID of the message that was created by this run step. - - `stdout: string` + - `type: "message_creation"` - The standard output that was captured. + Always `message_creation`. - - `created_by: optional string` +### Run Step - The identifier of the actor that created the item. +- `run_step: object { id, assistant_id, cancelled_at, 13 more }` - - `status: "in_progress" or "completed" or "incomplete"` + Represents a step in execution of a run. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `id: string` - - `"in_progress"` + The identifier of the run step, which can be referenced in API endpoints. - - `"completed"` + - `assistant_id: string` - - `"incomplete"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `type: "shell_call_output"` + - `cancelled_at: number` - The type of the shell call output. Always `shell_call_output`. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `agent: optional object { agent_name }` + - `completed_at: number` - The agent that produced this item. + The Unix timestamp (in seconds) for when the run step completed. - - `agent_name: string` + - `created_at: number` - The canonical name of the agent that produced this item. + The Unix timestamp (in seconds) for when the run step was created. - - `caller: optional object { type } or object { caller_id, type }` + - `expired_at: number` - The execution context that produced this tool call. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `direct: object { type }` + - `failed_at: number` - - `program: object { caller_id, type }` + The Unix timestamp (in seconds) for when the run step failed. - - `caller_id: string` + - `last_error: object { code, message }` - The call ID of the program item that produced this tool call. + The last error associated with this run step. Will be `null` if there are no errors. - - `type: "program"` + - `code: "server_error" or "rate_limit_exceeded"` - - `created_by: optional string` + One of `server_error` or `rate_limit_exceeded`. - The identifier of the actor that created the item. + - `"server_error"` - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `"rate_limit_exceeded"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `message: string` - - `id: string` + A human-readable description of the error. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `metadata: map[string]` - - `call_id: string` + 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. - The unique ID of the apply patch tool call generated by the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `object: "thread.run.step"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The object type, which is always `thread.run.step`. - - `create_file: object { diff, path, type }` + - `run_id: string` - Instruction describing how to create a file via the apply_patch tool. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - `diff: string` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - Diff to apply. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `path: string` + - `"in_progress"` - Path of the file to create. + - `"cancelled"` - - `type: "create_file"` + - `"failed"` - Create a new file with the provided diff. + - `"completed"` - - `delete_file: object { path, type }` + - `"expired"` - Instruction describing how to delete a file via the apply_patch tool. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `path: string` + The details of the run step. - Path of the file to delete. + - `message_creation_step_details: object { message_creation, type }` - - `type: "delete_file"` + Details of the message creation by the run step. - Delete the specified file. + - `message_creation: object { message_id }` - - `update_file: object { diff, path, type }` + - `message_id: string` - Instruction describing how to update a file via the apply_patch tool. + The ID of the message that was created by this run step. - - `diff: string` + - `type: "message_creation"` - Diff to apply. + Always `message_creation`. - - `path: string` + - `tool_calls_step_details: object { tool_calls, type }` - Path of the file to update. + Details of the tool call. - - `type: "update_file"` + - `tool_calls: array of ToolCall` - Update an existing file with the provided diff. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `status: "in_progress" or "completed"` + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Details of the Code Interpreter tool call the run step was involved in. - - `"in_progress"` + - `id: string` - - `"completed"` + The ID of the tool call. - - `type: "apply_patch_call"` + - `code_interpreter: object { input, outputs }` - The type of the item. Always `apply_patch_call`. + The Code Interpreter tool call definition. - - `agent: optional object { agent_name }` + - `input: string` - The agent that produced this item. + The input to the Code Interpreter tool call. - - `agent_name: string` + - `outputs: array of object { logs, type } or object { image, type }` - The canonical name of the agent that produced this item. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `caller: optional object { type } or object { caller_id, type }` + - `logs: object { logs, type }` - The execution context that produced this tool call. + Text output from the Code Interpreter tool call as part of a run step. - - `direct: object { type }` + - `logs: string` - - `program: object { caller_id, type }` + The text output from the Code Interpreter tool call. - - `caller_id: string` + - `type: "logs"` - The call ID of the program item that produced this tool call. + Always `logs`. - - `type: "program"` + - `image: object { image, type }` - - `created_by: optional string` + - `image: object { file_id }` - The ID of the entity that created this tool call. + - `file_id: string` - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The output emitted by an apply patch tool call. + - `type: "image"` - - `id: string` + Always `image`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `type: "code_interpreter"` - - `call_id: string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The unique ID of the apply patch tool call generated by the model. + - `file_search_tool_call: object { id, file_search, type }` - - `status: "completed" or "failed"` + - `id: string` - The status of the apply patch tool call output. One of `completed` or `failed`. + The ID of the tool call object. - - `"completed"` + - `file_search: object { ranking_options, results }` - - `"failed"` + For now, this is always going to be an empty object. - - `type: "apply_patch_call_output"` + - `ranking_options: optional object { ranker, score_threshold }` - The type of the item. Always `apply_patch_call_output`. + The ranking options for the file search. - - `agent: optional object { agent_name }` + - `ranker: "auto" or "default_2024_08_21"` - The agent that produced this item. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"default_2024_08_21"` - - `caller: optional object { type } or object { caller_id, type }` + - `score_threshold: number` - The execution context that produced this tool call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `direct: object { type }` + - `results: optional array of object { file_id, file_name, score, content }` - - `program: object { caller_id, type }` + The results of the file search. - - `caller_id: string` + - `file_id: string` - The call ID of the program item that produced this tool call. + The ID of the file that result was found in. - - `type: "program"` + - `file_name: string` - - `created_by: optional string` + The name of the file that result was found in. - The ID of the entity that created this tool call output. + - `score: number` - - `output: optional string` + The score of the result. All values must be a floating point number between 0 and 1. - Optional textual output returned by the apply patch tool. + - `content: optional array of object { text, type }` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + The content of the result that was found. The content is only included if requested via the include query parameter. - A list of tools available on an MCP server. + - `text: optional string` - - `id: string` + The text content of the file. - The unique ID of the list. + - `type: optional "text"` - - `server_label: string` + The type of the content. - The label of the MCP server. + - `"text"` - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "file_search"` - The tools available on the server. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `input_schema: unknown` + - `function_tool_call: object { id, function, type }` - The JSON schema describing the tool's input. + - `id: string` - - `name: string` + The ID of the tool call object. - The name of the tool. + - `function: object { arguments, name, output }` - - `annotations: optional unknown` + The definition of the function that was called. - Additional annotations about the tool. + - `arguments: string` - - `description: optional string` + The arguments passed to the function. - The description of the tool. + - `name: string` - - `type: "mcp_list_tools"` + The name of the function. - The type of the item. Always `mcp_list_tools`. + - `output: string` - - `agent: optional object { agent_name }` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The agent that produced this item. + - `type: "function"` - - `agent_name: string` + The type of tool call. This is always going to be `function` for this type of tool call. - The canonical name of the agent that produced this item. + - `type: "tool_calls"` - - `error: optional string` + Always `tool_calls`. - Error message if the server could not list tools. + - `thread_id: string` - - `mcp_approval_request: object { id, arguments, name, 3 more }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - A request for human approval of a tool invocation. + - `type: "message_creation" or "tool_calls"` - - `id: string` + The type of run step, which can be either `message_creation` or `tool_calls`. - The unique ID of the approval request. + - `"message_creation"` - - `arguments: string` + - `"tool_calls"` - A JSON string of arguments for the tool. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `name: string` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The name of the tool to run. + - `completion_tokens: number` - - `server_label: string` + Number of completion tokens used over the course of the run step. - The label of the MCP server making the request. + - `prompt_tokens: number` - - `type: "mcp_approval_request"` + Number of prompt tokens used over the course of the run step. - The type of the item. Always `mcp_approval_request`. + - `total_tokens: number` - - `agent: optional object { agent_name }` + Total number of tokens used (prompt + completion). - The agent that produced this item. +### Run Step Delta - - `agent_name: string` +- `run_step_delta: object { step_details }` - The canonical name of the agent that produced this item. + The delta containing the fields that have changed on the run step. - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - A response to an MCP approval request. + The details of the run step. - - `id: string` + - `run_step_delta_message_delta: object { type, message_creation }` - The unique ID of the approval response + Details of the message creation by the run step. - - `approval_request_id: string` + - `type: "message_creation"` - The ID of the approval request being answered. + Always `message_creation`. - - `approve: boolean` + - `message_creation: optional object { message_id }` - Whether the request was approved. + - `message_id: optional string` - - `type: "mcp_approval_response"` + The ID of the message that was created by this run step. - The type of the item. Always `mcp_approval_response`. + - `tool_call_delta_object: object { type, tool_calls }` - - `agent: optional object { agent_name }` + Details of the tool call. - The agent that produced this item. + - `type: "tool_calls"` - - `agent_name: string` + Always `tool_calls`. - The canonical name of the agent that produced this item. + - `tool_calls: optional array of ToolCallDelta` - - `reason: optional string` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - Optional reason for the decision. + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - - `mcp_call: object { id, arguments, name, 7 more }` + Details of the Code Interpreter tool call the run step was involved in. - An invocation of a tool on an MCP server. + - `index: number` - - `id: string` + The index of the tool call in the tool calls array. - The unique ID of the tool call. + - `type: "code_interpreter"` - - `arguments: string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - A JSON string of the arguments passed to the tool. + - `id: optional string` - - `name: string` + The ID of the tool call. - The name of the tool that was run. + - `code_interpreter: optional object { input, outputs }` - - `server_label: string` + The Code Interpreter tool call definition. - The label of the MCP server running the tool. + - `input: optional string` - - `type: "mcp_call"` + The input to the Code Interpreter tool call. - The type of the item. Always `mcp_call`. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `agent: optional object { agent_name }` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The agent that produced this item. + - `code_interpreter_logs: object { index, type, logs }` - - `agent_name: string` + Text output from the Code Interpreter tool call as part of a run step. - The canonical name of the agent that produced this item. + - `index: number` - - `approval_request_id: optional string` + The index of the output in the outputs array. - 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. + - `type: "logs"` - - `error: optional string` + Always `logs`. - The error from the tool call, if any. + - `logs: optional string` - - `output: optional string` + The text output from the Code Interpreter tool call. - The output from the tool call. + - `code_interpreter_output_image: object { index, type, image }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `index: number` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The index of the output in the outputs array. - - `"in_progress"` + - `type: "image"` - - `"completed"` + Always `image`. - - `"incomplete"` + - `image: optional object { file_id }` - - `"calling"` + - `file_id: optional string` - - `"failed"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` + - `file_search_tool_call_delta: object { file_search, index, type, id }` - A call to a custom tool created by the model. + - `file_search: unknown` - - `id: string` + For now, this is always going to be an empty object. - The unique ID of the custom tool call item. + - `index: number` - - `status: "in_progress" or "completed" or "incomplete"` + The index of the tool call in the tool calls array. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "file_search"` - - `"in_progress"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"completed"` + - `id: optional string` - - `"incomplete"` + The ID of the tool call object. - - `created_by: optional string` + - `function_tool_call_delta: object { index, type, id, function }` - The identifier of the actor that created the item. + - `index: number` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The index of the tool call in the tool calls array. - The output of a custom tool call from your code, being sent back to the model. + - `type: "function"` - - `id: string` + The type of tool call. This is always going to be `function` for this type of tool call. - The unique ID of the custom tool call output item. + - `id: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The ID of the tool call object. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `function: optional object { arguments, name, output }` - - `"in_progress"` + The definition of the function that was called. - - `"completed"` + - `arguments: optional string` - - `"incomplete"` + The arguments passed to the function. - - `created_by: optional string` + - `name: optional string` - The identifier of the actor that created the item. + The name of the function. - - `first_id: string` + - `output: optional string` - The ID of the first item in the list. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `has_more: boolean` +### Run Step Delta Event - Whether there are more items available. +- `run_step_delta_event: object { id, delta, object }` - - `last_id: string` + Represents a run step delta i.e. any changed fields on a run step during streaming. - The ID of the last item in the list. + - `id: string` - - `object: "list"` + The identifier of the run step, which can be referenced in API endpoints. - The type of object returned, must be `list`. + - `delta: object { step_details }` -### Example + The delta containing the fields that have changed on the run step. -```cli -openai beta:responses:input-items list \ - --api-key 'My API Key' \ - --response-id response_id -``` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` -#### Response + The details of the run step. -```json -{ - "data": [ - { - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text", - "prompt_cache_breakpoint": { - "mode": "explicit" - } - } - ], - "role": "user", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "status": "in_progress" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `run_step_delta_message_delta: object { type, message_creation }` -## Domain Types + Details of the message creation by the run step. -### Beta Response Item List + - `type: "message_creation"` -- `beta_responseItemList: object { data, first_id, has_more, 2 more }` + Always `message_creation`. - A list of Response items. + - `message_creation: optional object { message_id }` - - `data: array of BetaResponseItem` + - `message_id: optional string` - A list of items used to generate this response. + The ID of the message that was created by this run step. - - `beta_response_input_message_item: object { id, content, role, 3 more }` + - `tool_call_delta_object: object { type, tool_calls }` - - `id: string` + Details of the tool call. - The unique ID of the message input. + - `type: "tool_calls"` - - `content: array of BetaResponseInputContent` + Always `tool_calls`. - A list of one or many input items to the model, containing different content - types. + - `tool_calls: optional array of ToolCallDelta` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - A text input to the model. + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - - `text: string` + Details of the Code Interpreter tool call the run step was involved in. - The text input to the model. + - `index: number` - - `type: "input_text"` + The index of the tool call in the tool calls array. - The type of the input item. Always `input_text`. + - `type: "code_interpreter"` - - `prompt_cache_breakpoint: optional object { mode }` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - 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. + - `id: optional string` - - `mode: "explicit"` + The ID of the tool call. - The breakpoint mode. Always `explicit`. + - `code_interpreter: optional object { input, outputs }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The Code Interpreter tool call definition. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `input: optional string` - - `detail: "low" or "high" or "auto" or "original"` + The input to the Code Interpreter tool call. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `"low"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `"high"` + - `code_interpreter_logs: object { index, type, logs }` - - `"auto"` + Text output from the Code Interpreter tool call as part of a run step. - - `"original"` + - `index: number` - - `type: "input_image"` + The index of the output in the outputs array. - The type of the input item. Always `input_image`. + - `type: "logs"` - - `file_id: optional string` + Always `logs`. - The ID of the file to be sent to the model. + - `logs: optional string` - - `image_url: optional string` + The text output from the Code Interpreter tool call. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `code_interpreter_output_image: object { index, type, image }` - - `prompt_cache_breakpoint: optional object { mode }` + - `index: number` - 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. + The index of the output in the outputs array. - - `mode: "explicit"` + - `type: "image"` - The breakpoint mode. Always `explicit`. + Always `image`. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `image: optional object { file_id }` - A file input to the model. + - `file_id: optional string` - - `type: "input_file"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The type of the input item. Always `input_file`. + - `file_search_tool_call_delta: object { file_search, index, type, id }` - - `detail: optional "auto" or "low" or "high"` + - `file_search: unknown` - 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`. + For now, this is always going to be an empty object. - - `"auto"` + - `index: number` - - `"low"` + The index of the tool call in the tool calls array. - - `"high"` + - `type: "file_search"` - - `file_data: optional string` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The content of the file to be sent to the model. + - `id: optional string` - - `file_id: optional string` + The ID of the tool call object. - The ID of the file to be sent to the model. + - `function_tool_call_delta: object { index, type, id, function }` - - `file_url: optional string` + - `index: number` - The URL of the file to be sent to the model. + The index of the tool call in the tool calls array. - - `filename: optional string` + - `type: "function"` - The name of the file to be sent to the model. + The type of tool call. This is always going to be `function` for this type of tool call. - - `prompt_cache_breakpoint: optional object { mode }` + - `id: optional string` - 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. + The ID of the tool call object. - - `mode: "explicit"` + - `function: optional object { arguments, name, output }` - The breakpoint mode. Always `explicit`. + The definition of the function that was called. - - `role: "user" or "system" or "developer"` + - `arguments: optional string` - The role of the message input. One of `user`, `system`, or `developer`. + The arguments passed to the function. - - `"user"` + - `name: optional string` - - `"system"` + The name of the function. - - `"developer"` + - `output: optional string` - - `type: "message"` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The type of the message input. Always set to `message`. + - `object: "thread.run.step.delta"` - - `agent: optional object { agent_name }` + The object type, which is always `thread.run.step.delta`. - The agent that produced this item. +### Run Step Delta Message Delta - - `agent_name: string` +- `run_step_delta_message_delta: object { type, message_creation }` - The canonical name of the agent that produced this item. + Details of the message creation by the run step. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "message_creation"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Always `message_creation`. - - `"in_progress"` + - `message_creation: optional object { message_id }` - - `"completed"` + - `message_id: optional string` - - `"incomplete"` + The ID of the message that was created by this run step. - - `beta_response_output_message: object { id, content, role, 4 more }` +### Run Step Include - An output message from the model. +- `run_step_include: "step_details.tool_calls[*].file_search.results[*].content"` - - `id: string` + - `"step_details.tool_calls[*].file_search.results[*].content"` - The unique ID of the output message. +### Tool Call - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` +- `tool_call: CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - The content of the output message. + Details of the Code Interpreter tool call the run step was involved in. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - A text output from the model. + Details of the Code Interpreter tool call the run step was involved in. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `id: string` - The annotations of the text output. + The ID of the tool call. - - `file_citation: object { file_id, filename, index, type }` + - `code_interpreter: object { input, outputs }` - A citation to a file. + The Code Interpreter tool call definition. - - `file_id: string` + - `input: string` - The ID of the file. + The input to the Code Interpreter tool call. - - `filename: string` + - `outputs: array of object { logs, type } or object { image, type }` - The filename of the file cited. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `index: number` + - `logs: object { logs, type }` - The index of the file in the list of files. + Text output from the Code Interpreter tool call as part of a run step. - - `type: "file_citation"` + - `logs: string` - The type of the file citation. Always `file_citation`. + The text output from the Code Interpreter tool call. - - `url_citation: object { end_index, start_index, title, 2 more }` + - `type: "logs"` - A citation for a web resource used to generate a model response. + Always `logs`. - - `end_index: number` + - `image: object { image, type }` - The index of the last character of the URL citation in the message. + - `image: object { file_id }` - - `start_index: number` + - `file_id: string` - The index of the first character of the URL citation in the message. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `title: string` + - `type: "image"` - The title of the web resource. + Always `image`. - - `type: "url_citation"` + - `type: "code_interpreter"` - The type of the URL citation. Always `url_citation`. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `url: string` + - `file_search_tool_call: object { id, file_search, type }` - The URL of the web resource. + - `id: string` - - `container_file_citation: object { container_id, end_index, file_id, 3 more }` + The ID of the tool call object. - A citation for a container file used to generate a model response. + - `file_search: object { ranking_options, results }` - - `container_id: string` + For now, this is always going to be an empty object. - The ID of the container file. + - `ranking_options: optional object { ranker, score_threshold }` - - `end_index: number` + The ranking options for the file search. - The index of the last character of the container file citation in the message. + - `ranker: "auto" or "default_2024_08_21"` - - `file_id: string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The ID of the file. + - `"auto"` - - `filename: string` + - `"default_2024_08_21"` - The filename of the container file cited. + - `score_threshold: number` - - `start_index: number` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The index of the first character of the container file citation in the message. + - `results: optional array of object { file_id, file_name, score, content }` - - `type: "container_file_citation"` + The results of the file search. - The type of the container file citation. Always `container_file_citation`. + - `file_id: string` - - `file_path: object { file_id, index, type }` + The ID of the file that result was found in. - A path to a file. + - `file_name: string` - - `file_id: string` + The name of the file that result was found in. - The ID of the file. + - `score: number` - - `index: number` + The score of the result. All values must be a floating point number between 0 and 1. - The index of the file in the list of files. + - `content: optional array of object { text, type }` - - `type: "file_path"` + The content of the result that was found. The content is only included if requested via the include query parameter. - The type of the file path. Always `file_path`. + - `text: optional string` - - `text: string` + The text content of the file. - The text output from the model. + - `type: optional "text"` - - `type: "output_text"` + The type of the content. - The type of the output text. Always `output_text`. + - `"text"` - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `type: "file_search"` - - `token: string` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `bytes: array of number` + - `function_tool_call: object { id, function, type }` - - `logprob: number` + - `id: string` - - `top_logprobs: array of object { token, bytes, logprob }` + The ID of the tool call object. - - `token: string` + - `function: object { arguments, name, output }` - - `bytes: array of number` + The definition of the function that was called. - - `logprob: number` + - `arguments: string` - - `beta_response_output_refusal: object { refusal, type }` + The arguments passed to the function. - A refusal from the model. + - `name: string` - - `refusal: string` + The name of the function. - The refusal explanation from the model. + - `output: string` - - `type: "refusal"` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The type of the refusal. Always `refusal`. + - `type: "function"` - - `role: "assistant"` + The type of tool call. This is always going to be `function` for this type of tool call. - The role of the output message. Always `assistant`. +### Tool Call Delta - - `status: "in_progress" or "completed" or "incomplete"` +- `tool_call_delta: CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Details of the Code Interpreter tool call the run step was involved in. - - `"in_progress"` + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - - `"completed"` + Details of the Code Interpreter tool call the run step was involved in. - - `"incomplete"` + - `index: number` - - `type: "message"` + The index of the tool call in the tool calls array. - The type of the output message. Always `message`. + - `type: "code_interpreter"` - - `agent: optional object { agent_name }` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The agent that produced this item. + - `id: optional string` - - `agent_name: string` + The ID of the tool call. - The canonical name of the agent that produced this item. + - `code_interpreter: optional object { input, outputs }` - - `phase: optional "commentary"` + The Code Interpreter tool call definition. - 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. + - `input: optional string` - - `"commentary"` + The input to the Code Interpreter tool call. - - `beta_response_file_search_tool_call: object { id, queries, status, 3 more }` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - 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. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `id: string` + - `code_interpreter_logs: object { index, type, logs }` - The unique ID of the file search tool call. + Text output from the Code Interpreter tool call as part of a run step. - - `queries: array of string` + - `index: number` - The queries used to search for files. + The index of the output in the outputs array. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `type: "logs"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Always `logs`. - - `"in_progress"` + - `logs: optional string` - - `"searching"` + The text output from the Code Interpreter tool call. - - `"completed"` + - `code_interpreter_output_image: object { index, type, image }` - - `"incomplete"` + - `index: number` - - `"failed"` + The index of the output in the outputs array. - - `type: "file_search_call"` + - `type: "image"` - The type of the file search tool call. Always `file_search_call`. + Always `image`. - - `agent: optional object { agent_name }` + - `image: optional object { file_id }` - The agent that produced this item. + - `file_id: optional string` - - `agent_name: string` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - The canonical name of the agent that produced this item. + - `file_search_tool_call_delta: object { file_search, index, type, id }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `file_search: unknown` - The results of the file search tool call. + For now, this is always going to be an empty object. - - `attributes: optional map[string or number or boolean]` + - `index: number` - 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. + The index of the tool call in the tool calls array. - - `union_member_0: string` + - `type: "file_search"` - - `union_member_1: number` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `union_member_2: boolean` + - `id: optional string` - - `file_id: optional string` + The ID of the tool call object. - The unique ID of the file. + - `function_tool_call_delta: object { index, type, id, function }` - - `filename: optional string` + - `index: number` - The name of the file. + The index of the tool call in the tool calls array. - - `score: optional number` + - `type: "function"` - The relevance score of the file - a value between 0 and 1. + The type of tool call. This is always going to be `function` for this type of tool call. - - `text: optional string` + - `id: optional string` - The text that was retrieved from the file. + The ID of the tool call object. - - `beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }` + - `function: optional object { arguments, name, output }` - 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. + The definition of the function that was called. - - `id: string` + - `arguments: optional string` - The unique ID of the computer call. + The arguments passed to the function. - - `call_id: string` + - `name: optional string` - An identifier used when responding to the tool call with output. + The name of the function. - - `pending_safety_checks: array of object { id, code, message }` + - `output: optional string` - The pending safety checks for the computer call. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `id: string` +### Tool Call Delta Object - The ID of the pending safety check. +- `tool_call_delta_object: object { type, tool_calls }` - - `code: optional string` + Details of the tool call. - The type of the pending safety check. + - `type: "tool_calls"` - - `message: optional string` + Always `tool_calls`. - Details about the pending safety check. + - `tool_calls: optional array of ToolCallDelta` - - `status: "in_progress" or "completed" or "incomplete"` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - - `"in_progress"` + Details of the Code Interpreter tool call the run step was involved in. - - `"completed"` + - `index: number` - - `"incomplete"` + The index of the tool call in the tool calls array. - - `type: "computer_call"` + - `type: "code_interpreter"` - The type of the computer call. Always `computer_call`. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"computer_call"` + - `id: optional string` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + The ID of the tool call. - A click action. + - `code_interpreter: optional object { input, outputs }` - - `click: object { button, type, x, 2 more }` + The Code Interpreter tool call definition. - A click action. + - `input: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + The input to the Code Interpreter tool call. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `"left"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `"right"` + - `code_interpreter_logs: object { index, type, logs }` - - `"wheel"` + Text output from the Code Interpreter tool call as part of a run step. - - `"back"` + - `index: number` - - `"forward"` + The index of the output in the outputs array. - - `type: "click"` + - `type: "logs"` - Specifies the event type. For a click action, this property is always `click`. + Always `logs`. - - `x: number` + - `logs: optional string` - The x-coordinate where the click occurred. + The text output from the Code Interpreter tool call. - - `y: number` + - `code_interpreter_output_image: object { index, type, image }` - The y-coordinate where the click occurred. + - `index: number` - - `keys: optional array of string` + The index of the output in the outputs array. - The keys being held while clicking. + - `type: "image"` - - `double_click: object { keys, type, x, y }` + Always `image`. - A double click action. + - `image: optional object { file_id }` - - `keys: array of string` + - `file_id: optional string` - The keys being held while double-clicking. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `type: "double_click"` + - `file_search_tool_call_delta: object { file_search, index, type, id }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `file_search: unknown` - - `x: number` + For now, this is always going to be an empty object. - The x-coordinate where the double click occurred. + - `index: number` - - `y: number` + The index of the tool call in the tool calls array. - The y-coordinate where the double click occurred. + - `type: "file_search"` - - `drag: object { path, type, keys }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - A drag action. + - `id: optional string` - - `path: array of object { x, y }` + The ID of the tool call object. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `function_tool_call_delta: object { index, type, id, function }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `index: number` - - `x: number` + The index of the tool call in the tool calls array. - The x-coordinate. + - `type: "function"` - - `y: number` + The type of tool call. This is always going to be `function` for this type of tool call. - The y-coordinate. + - `id: optional string` - - `type: "drag"` + The ID of the tool call object. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `function: optional object { arguments, name, output }` - - `keys: optional array of string` + The definition of the function that was called. - The keys being held while dragging the mouse. + - `arguments: optional string` - - `keypress: object { keys, type }` + The arguments passed to the function. - A collection of keypresses the model would like to perform. + - `name: optional string` - - `keys: array of string` + The name of the function. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `output: optional string` - - `type: "keypress"` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - Specifies the event type. For a keypress action, this property is always set to `keypress`. +### Tool Calls Step Details - - `move: object { type, x, y, keys }` +- `tool_calls_step_details: object { tool_calls, type }` - A mouse move action. + Details of the tool call. - - `type: "move"` + - `tool_calls: array of ToolCall` - Specifies the event type. For a move action, this property is always set to `move`. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `x: number` + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - The x-coordinate to move to. + Details of the Code Interpreter tool call the run step was involved in. - - `y: number` + - `id: string` - The y-coordinate to move to. + The ID of the tool call. - - `keys: optional array of string` + - `code_interpreter: object { input, outputs }` - The keys being held while moving the mouse. + The Code Interpreter tool call definition. - - `screenshot: object { type }` + - `input: string` - A screenshot action. + The input to the Code Interpreter tool call. - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + - `outputs: array of object { logs, type } or object { image, type }` - A scroll action. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `scroll_x: number` + - `logs: object { logs, type }` - The horizontal scroll distance. + Text output from the Code Interpreter tool call as part of a run step. - - `scroll_y: number` + - `logs: string` - The vertical scroll distance. + The text output from the Code Interpreter tool call. - - `type: "scroll"` + - `type: "logs"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Always `logs`. - - `x: number` + - `image: object { image, type }` - The x-coordinate where the scroll occurred. + - `image: object { file_id }` - - `y: number` + - `file_id: string` - The y-coordinate where the scroll occurred. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `keys: optional array of string` + - `type: "image"` - The keys being held while scrolling. + Always `image`. - - `type: object { text, type }` + - `type: "code_interpreter"` - An action to type in text. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `text: string` + - `file_search_tool_call: object { id, file_search, type }` - The text to type. + - `id: string` - - `type: "type"` + The ID of the tool call object. - Specifies the event type. For a type action, this property is always set to `type`. + - `file_search: object { ranking_options, results }` - - `wait: object { type }` + For now, this is always going to be an empty object. - A wait action. + - `ranking_options: optional object { ranker, score_threshold }` - - `actions: optional array of BetaComputerAction` + The ranking options for the file search. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `ranker: "auto" or "default_2024_08_21"` - - `click: object { button, type, x, 2 more }` + The ranker to use for the file search. If not specified will use the `auto` ranker. - A click action. + - `"auto"` - - `double_click: object { keys, type, x, y }` + - `"default_2024_08_21"` - A double click action. + - `score_threshold: number` - - `drag: object { path, type, keys }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - A drag action. + - `results: optional array of object { file_id, file_name, score, content }` - - `keypress: object { keys, type }` + The results of the file search. - A collection of keypresses the model would like to perform. + - `file_id: string` - - `move: object { type, x, y, keys }` + The ID of the file that result was found in. - A mouse move action. + - `file_name: string` - - `screenshot: object { type }` + The name of the file that result was found in. - A screenshot action. + - `score: number` - - `scroll: object { scroll_x, scroll_y, type, 3 more }` + The score of the result. All values must be a floating point number between 0 and 1. - A scroll action. + - `content: optional array of object { text, type }` - - `type: object { text, type }` + The content of the result that was found. The content is only included if requested via the include query parameter. - An action to type in text. + - `text: optional string` - - `wait: object { type }` + The text content of the file. - A wait action. + - `type: optional "text"` - - `agent: optional object { agent_name }` + The type of the content. - The agent that produced this item. + - `"text"` - - `agent_name: string` + - `type: "file_search"` - The canonical name of the agent that produced this item. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }` + - `function_tool_call: object { id, function, type }` - `id: string` - The unique ID of the computer call tool output. - - - `call_id: string` + The ID of the tool call object. - The ID of the computer tool call that produced the output. + - `function: object { arguments, name, output }` - - `output: object { type, file_id, image_url }` + The definition of the function that was called. - A computer screenshot image used with the computer use tool. + - `arguments: string` - - `type: "computer_screenshot"` + The arguments passed to the function. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `name: string` - - `file_id: optional string` + The name of the function. - The identifier of an uploaded file that contains the screenshot. + - `output: string` - - `image_url: optional string` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - The URL of the screenshot image. + - `type: "function"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + The type of tool call. This is always going to be `function` for this type of tool call. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "tool_calls"` - - `"completed"` + Always `tool_calls`. - - `"incomplete"` +# Messages - - `"failed"` +## List messages - - `"in_progress"` +`$ openai beta:threads:messages list` - - `type: "computer_call_output"` +**get** `/threads/{thread_id}/messages` - The type of the computer tool call output. Always `computer_call_output`. +Returns a list of messages for a given thread. - - `acknowledged_safety_checks: optional array of object { id, code, message }` +### Parameters - The safety checks reported by the API that have been acknowledged by the - developer. +- `--thread-id: string` - - `id: string` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) the messages belong to. - The ID of the pending safety check. +- `--after: optional string` - - `code: optional string` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - The type of the pending safety check. +- `--before: optional string` - - `message: optional string` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - Details about the pending safety check. +- `--limit: optional number` - - `agent: optional object { agent_name }` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The agent that produced this item. +- `--order: optional "asc" or "desc"` - - `agent_name: string` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - The canonical name of the agent that produced this item. +- `--run-id: optional string` - - `created_by: optional string` + Filter messages by the run ID that generated them. - The identifier of the actor that created the item. +### Returns - - `beta_response_function_web_search: object { id, action, status, 2 more }` +- `ListMessagesResponse: object { data, first_id, has_more, 2 more }` - 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. + - `data: array of Message` - `id: string` - The unique ID of the web search tool call. - - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The identifier, which can be referenced in API endpoints. - 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). + - `assistant_id: string` - - `search: object { type, queries, query, sources }` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - Action type "search" - Performs a web search query. + - `attachments: array of object { file_id, tools }` - - `type: "search"` + A list of files attached to the message, and the tools they were added to. - The action type. + - `file_id: optional string` - - `queries: optional array of string` + The ID of the file to attach to the message. - The search queries. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `query: optional string` + The tools to add this file to. - The search query. + - `code_interpreter_tool: object { type }` - - `sources: optional array of object { type, url }` + - `type: "code_interpreter"` - The sources used in the search. + The type of tool being defined: `code_interpreter` - - `type: "url"` + - `AssistantToolsFileSearchTypeOnly: object { type }` - The type of source. Always `url`. + - `completed_at: number` - - `url: string` + The Unix timestamp (in seconds) for when the message was completed. - The URL of the source. + - `content: array of MessageContent` - - `open_page: object { type, url }` + The content of the message in array of text and/or images. - Action type "open_page" - Opens a specific URL from search results. + - `image_file_content_block: object { image_file, type }` - - `type: "open_page"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The action type. + - `image_file: object { file_id, detail }` - - `url: optional string` + - `file_id: string` - The URL opened by the model. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `find_in_page: object { pattern, type, url }` + - `detail: optional "auto" or "low" or "high"` - Action type "find_in_page": Searches for a pattern within a loaded page. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `pattern: string` + - `"auto"` - The pattern or text to search for within the page. + - `"low"` - - `type: "find_in_page"` + - `"high"` - The action type. + - `type: "image_file"` - - `url: string` + Always `image_file`. - The URL of the page searched for the pattern. + - `image_url_content_block: object { image_url, type }` - - `status: "in_progress" or "searching" or "completed" or "failed"` + References an image URL in the content of a message. - The status of the web search tool call. + - `image_url: object { url, detail }` - - `"in_progress"` + - `url: string` - - `"searching"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"completed"` + - `detail: optional "auto" or "low" or "high"` - - `"failed"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: "web_search_call"` + - `"auto"` - The type of the web search tool call. Always `web_search_call`. + - `"low"` - - `agent: optional object { agent_name }` + - `"high"` - The agent that produced this item. + - `type: "image_url"` - - `agent_name: string` + The type of the content part. - The canonical name of the agent that produced this item. + - `text_content_block: object { text, type }` - - `beta_response_function_tool_call_item: BetaResponseFunctionToolCall` + The text content that is part of a message. - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + - `text: object { annotations, value }` - - `id: string` + - `annotations: array of Annotation` - The unique ID of the function tool call. + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - - `status: "in_progress" or "completed" or "incomplete"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `end_index: number` - - `"in_progress"` + - `file_citation: object { file_id }` - - `"completed"` + - `file_id: string` - - `"incomplete"` + The ID of the specific File the citation is from. - - `created_by: optional string` + - `start_index: number` - The identifier of the actor that created the item. + - `text: string` - - `beta_response_function_tool_call_output_item: object { id, call_id, output, 5 more }` + The text in the message content that needs to be replaced. - - `id: string` + - `type: "file_citation"` - The unique ID of the function call tool output. + Always `file_citation`. - - `call_id: string` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - The unique ID of the function tool call generated by the model. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `end_index: number` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `file_path: object { file_id }` - - `string output: string` + - `file_id: string` - A string of the output of the function call. + The ID of the file that was generated. - - `output content list: array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `start_index: number` - Text, image, or file output of the function call. + - `text: string` - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` + The text in the message content that needs to be replaced. - A text input to the model. + - `type: "file_path"` - - `text: string` + Always `file_path`. - The text input to the model. + - `value: string` - - `type: "input_text"` + The data that makes up the text. - The type of the input item. Always `input_text`. + - `type: "text"` - - `prompt_cache_breakpoint: optional object { mode }` + Always `text`. - 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. + - `refusal_content_block: object { refusal, type }` - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + The refusal content generated by the assistant. - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + - `refusal: string` - - `detail: "low" or "high" or "auto" or "original"` + - `type: "refusal"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Always `refusal`. - - `type: "input_image"` + - `created_at: number` - The type of the input item. Always `input_image`. + The Unix timestamp (in seconds) for when the message was created. - - `file_id: optional string` + - `incomplete_at: number` - The ID of the file to be sent to the model. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `image_url: optional string` + - `incomplete_details: object { reason }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + On an incomplete message, details about why the message is incomplete. - - `prompt_cache_breakpoint: optional object { mode }` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - 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. + The reason the message is incomplete. - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"content_filter"` - A file input to the model. + - `"max_tokens"` - - `type: "input_file"` + - `"run_cancelled"` - The type of the input item. Always `input_file`. + - `"run_expired"` - - `detail: optional "auto" or "low" or "high"` + - `"run_failed"` - 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`. + - `metadata: map[string]` - - `file_data: optional string` + 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. - The content of the file to be sent to the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `file_id: optional string` + - `object: "thread.message"` - The ID of the file to be sent to the model. + The object type, which is always `thread.message`. - - `file_url: optional string` + - `role: "user" or "assistant"` - The URL of the file to be sent to the model. + The entity that produced the message. One of `user` or `assistant`. - - `filename: optional string` + - `"user"` - The name of the file to be sent to the model. + - `"assistant"` - - `prompt_cache_breakpoint: optional object { mode }` + - `run_id: string` - 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. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "incomplete" or "completed"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - `"in_progress"` + - `"incomplete"` + - `"completed"` - - `"incomplete"` + - `thread_id: string` - - `type: "function_call_output"` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The type of the function tool call output. Always `function_call_output`. + - `first_id: string` - - `agent: optional object { agent_name }` + - `has_more: boolean` - The agent that produced this item. + - `last_id: string` - - `agent_name: string` + - `object: string` - The canonical name of the agent that produced this item. +### Example - - `caller: optional object { type } or object { caller_id, type }` +```cli +openai beta:threads:messages list \ + --api-key 'My API Key' \ + --thread-id thread_id +``` - The execution context that produced this tool call. +#### Response - - `direct: object { type }` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" + } + ], + "first_id": "msg_abc123", + "has_more": false, + "last_id": "msg_abc123", + "object": "list" +} +``` - - `program: object { caller_id, type }` +## Create message - - `caller_id: string` +`$ openai beta:threads:messages create` - The call ID of the program item that produced this tool call. +**post** `/threads/{thread_id}/messages` - - `type: "program"` +Create a message. - The caller type. Always `program`. +### Parameters - - `created_by: optional string` +- `--thread-id: string` - The identifier of the actor that created the item. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to create a message for. - - `agent_message: object { id, author, content, 3 more }` +- `--content: string or array of MessageContentPartParam` - - `id: string` + The text contents of the message. - The unique ID of the agent message. +- `--role: "user" or "assistant"` - - `author: string` + The role of the entity that is creating the message. Allowed values include: - The sending agent identity. + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` +- `--attachment: optional array of object { file_id, tools }` - Encrypted content sent between agents. + A list of files attached to the message, and the tools they should be added to. - - `beta_response_input_text: object { text, type, prompt_cache_breakpoint }` +- `--metadata: optional map[string]` - A text input to the model. + 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. - - `beta_response_output_text: object { annotations, text, type, logprobs }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A text output from the model. +### Returns - - `text: object { text, type }` +- `message: object { id, assistant_id, attachments, 11 more }` - A text content. + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `text: string` + - `id: string` - - `type: "text"` + The identifier, which can be referenced in API endpoints. - - `summary_text: object { text, type }` + - `assistant_id: string` - A summary text from the model. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `text: string` + - `attachments: array of object { file_id, tools }` - A summary of the reasoning output from the model so far. + A list of files attached to the message, and the tools they were added to. - - `type: "summary_text"` + - `file_id: optional string` - The type of the object. Always `summary_text`. + The ID of the file to attach to the message. - - `reasoning_text: object { text, type }` + - `tools: optional array of CodeInterpreterTool or object { type }` - Reasoning text from the model. + The tools to add this file to. - - `text: string` + - `code_interpreter_tool: object { type }` - The reasoning text from the model. + - `type: "code_interpreter"` - - `type: "reasoning_text"` + The type of tool being defined: `code_interpreter` - The type of the reasoning text. Always `reasoning_text`. + - `AssistantToolsFileSearchTypeOnly: object { type }` - - `beta_response_output_refusal: object { refusal, type }` + - `completed_at: number` - A refusal from the model. + The Unix timestamp (in seconds) for when the message was completed. - - `beta_response_input_image: object { detail, type, file_id, 2 more }` + - `content: array of MessageContent` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + The content of the message in array of text and/or images. - - `computer_screenshot: object { detail, file_id, image_url, 2 more }` + - `image_file_content_block: object { image_file, type }` - A screenshot of a computer. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `detail: "low" or "high" or "auto" or "original"` + - `image_file: object { file_id, detail }` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `file_id: string` - - `"low"` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `"high"` + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - `"auto"` - - `"original"` + - `"low"` - - `file_id: string` + - `"high"` - The identifier of an uploaded file that contains the screenshot. + - `type: "image_file"` - - `image_url: string` + Always `image_file`. - The URL of the screenshot image. + - `image_url_content_block: object { image_url, type }` - - `type: "computer_screenshot"` + References an image URL in the content of a message. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `image_url: object { url, detail }` - - `prompt_cache_breakpoint: optional object { mode }` + - `url: string` - 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. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `mode: "explicit"` + - `detail: optional "auto" or "low" or "high"` - The breakpoint mode. Always `explicit`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `beta_response_input_file: object { type, detail, file_data, 4 more }` + - `"auto"` - A file input to the model. + - `"low"` - - `encrypted_content: object { encrypted_content, type }` + - `"high"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `type: "image_url"` - - `encrypted_content: string` + The type of the content part. - Opaque encrypted content. + - `text_content_block: object { text, type }` - - `type: "encrypted_content"` + The text content that is part of a message. - The type of the input item. Always `encrypted_content`. + - `text: object { annotations, value }` - - `recipient: string` + - `annotations: array of Annotation` - The destination agent identity. + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - - `type: "agent_message"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The type of the item. Always `agent_message`. + - `end_index: number` - - `agent: optional object { agent_name }` + - `file_citation: object { file_id }` - The agent that produced this item. + - `file_id: string` - - `agent_name: string` + The ID of the specific File the citation is from. - The canonical name of the agent that produced this item. + - `start_index: number` - - `multi_agent_call: object { id, action, arguments, 3 more }` + - `text: string` - - `id: string` + The text in the message content that needs to be replaced. - The unique ID of the multi-agent call item. + - `type: "file_citation"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Always `file_citation`. - The multi-agent action to execute. + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `"spawn_agent"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"interrupt_agent"` + - `end_index: number` - - `"list_agents"` + - `file_path: object { file_id }` - - `"send_message"` + - `file_id: string` - - `"followup_task"` + The ID of the file that was generated. - - `"wait_agent"` + - `start_index: number` - - `arguments: string` + - `text: string` - The JSON string of arguments generated for the action. + The text in the message content that needs to be replaced. - - `call_id: string` + - `type: "file_path"` - The unique ID linking this call to its output. + Always `file_path`. - - `type: "multi_agent_call"` + - `value: string` - The type of the multi-agent call. Always `multi_agent_call`. + The data that makes up the text. - - `agent: optional object { agent_name }` + - `type: "text"` - The agent that produced this item. + Always `text`. - - `agent_name: string` + - `refusal_content_block: object { refusal, type }` - The canonical name of the agent that produced this item. + The refusal content generated by the assistant. - - `multi_agent_call_output: object { id, action, call_id, 3 more }` + - `refusal: string` - - `id: string` + - `type: "refusal"` - The unique ID of the multi-agent call output item. + Always `refusal`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `created_at: number` - The multi-agent action that produced this result. + The Unix timestamp (in seconds) for when the message was created. - - `"spawn_agent"` + - `incomplete_at: number` - - `"interrupt_agent"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"list_agents"` + - `incomplete_details: object { reason }` - - `"send_message"` + On an incomplete message, details about why the message is incomplete. - - `"followup_task"` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `"wait_agent"` + The reason the message is incomplete. - - `call_id: string` + - `"content_filter"` - The unique ID of the multi-agent call. + - `"max_tokens"` - - `output: array of BetaResponseOutputText` + - `"run_cancelled"` - Text output returned by the multi-agent action. + - `"run_expired"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"run_failed"` - The annotations of the text output. + - `metadata: map[string]` - - `text: string` + 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. - The text output from the model. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "output_text"` + - `object: "thread.message"` - The type of the output text. Always `output_text`. + The object type, which is always `thread.message`. - - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` + - `role: "user" or "assistant"` - - `type: "multi_agent_call_output"` + The entity that produced the message. One of `user` or `assistant`. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"user"` - - `agent: optional object { agent_name }` + - `"assistant"` - The agent that produced this item. + - `run_id: string` - - `agent_name: string` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - The canonical name of the agent that produced this item. + - `status: "in_progress" or "incomplete" or "completed"` - - `beta_response_tool_search_call: object { id, arguments, call_id, 5 more }` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `id: string` + - `"in_progress"` - The unique ID of the tool search call item. + - `"incomplete"` - - `arguments: unknown` + - `"completed"` - Arguments used for the tool search call. + - `thread_id: string` - - `call_id: string` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - The unique ID of the tool search call generated by the model. +### Example - - `execution: "server" or "client"` +```cli +openai beta:threads:messages create \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --content string \ + --role user +``` - Whether tool search was executed by the server or by the client. +#### Response - - `"server"` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `"client"` +## Modify message - - `status: "in_progress" or "completed" or "incomplete"` +`$ openai beta:threads:messages update` - The status of the tool search call item that was recorded. +**post** `/threads/{thread_id}/messages/{message_id}` - - `"in_progress"` +Modifies a message. - - `"completed"` +### Parameters - - `"incomplete"` +- `--thread-id: string` - - `type: "tool_search_call"` + The ID of the thread to which this message belongs. - The type of the item. Always `tool_search_call`. +- `--message-id: string` - - `agent: optional object { agent_name }` + The ID of the message to modify. - The agent that produced this item. +- `--metadata: optional map[string]` - - `agent_name: string` + 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. - The canonical name of the agent that produced this item. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `created_by: optional string` +### Returns - The identifier of the actor that created the item. +- `message: object { id, assistant_id, attachments, 11 more }` - - `beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - `id: string` - The unique ID of the tool search output item. + The identifier, which can be referenced in API endpoints. - - `call_id: string` + - `assistant_id: string` - The unique ID of the tool search call generated by the model. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `execution: "server" or "client"` + - `attachments: array of object { file_id, tools }` - Whether tool search was executed by the server or by the client. + A list of files attached to the message, and the tools they were added to. - - `"server"` + - `file_id: optional string` - - `"client"` + The ID of the file to attach to the message. - - `status: "in_progress" or "completed" or "incomplete"` + - `tools: optional array of CodeInterpreterTool or object { type }` - The status of the tool search output item that was recorded. + The tools to add this file to. - - `"in_progress"` + - `code_interpreter_tool: object { type }` - - `"completed"` + - `type: "code_interpreter"` - - `"incomplete"` + The type of tool being defined: `code_interpreter` - - `tools: array of BetaTool` + - `AssistantToolsFileSearchTypeOnly: object { type }` - The loaded tool definitions returned by tool search. + - `completed_at: number` - - `beta_function_tool: object { name, parameters, strict, 5 more }` + The Unix timestamp (in seconds) for when the message was completed. - 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). + - `content: array of MessageContent` - - `name: string` + The content of the message in array of text and/or images. - The name of the function to call. + - `image_file_content_block: object { image_file, type }` - - `parameters: map[unknown]` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - A JSON schema object describing the parameters of the function. + - `image_file: object { file_id, detail }` - - `strict: boolean` + - `file_id: string` - Whether strict parameter validation is enforced for this function tool. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `type: "function"` + - `detail: optional "auto" or "low" or "high"` - The type of the function tool. Always `function`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"auto"` - The tool invocation context(s). + - `"low"` - - `"direct"` + - `"high"` - - `"programmatic"` + - `type: "image_file"` - - `defer_loading: optional boolean` + Always `image_file`. - Whether this function is deferred and loaded via tool search. + - `image_url_content_block: object { image_url, type }` - - `description: optional string` + References an image URL in the content of a message. - A description of the function. Used by the model to determine whether or not to call the function. + - `image_url: object { url, detail }` - - `output_schema: optional map[unknown]` + - `url: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `detail: optional "auto" or "low" or "high"` - 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). + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: "file_search"` + - `"auto"` - The type of the file search tool. Always `file_search`. + - `"low"` - - `vector_store_ids: array of string` + - `"high"` - The IDs of the vector stores to search. + - `type: "image_url"` - - `filters: optional object { key, type, value } or object { filters, type }` + The type of the content part. - A filter to apply. + - `text_content_block: object { text, type }` - - `Comparison Filter: object { key, type, value }` + The text content that is part of a message. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `text: object { annotations, value }` - - `key: string` + - `annotations: array of Annotation` - The key to compare against the value. + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - - `type: "eq" or "ne" or "gt" or 5 more` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `end_index: number` - - `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 + - `file_citation: object { file_id }` - - `"eq"` + - `file_id: string` - - `"ne"` + The ID of the specific File the citation is from. - - `"gt"` + - `start_index: number` - - `"gte"` + - `text: string` - - `"lt"` + The text in the message content that needs to be replaced. - - `"lte"` + - `type: "file_citation"` - - `"in"` + Always `file_citation`. - - `"nin"` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `value: string or number or boolean or array of unknown` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The value to compare against the attribute key; supports string, number, or boolean types. + - `end_index: number` - - `union_member_0: string` + - `file_path: object { file_id }` - - `union_member_1: number` + - `file_id: string` - - `union_member_2: boolean` + The ID of the file that was generated. - - `union_member_3: array of unknown` + - `start_index: number` - - `Compound Filter: object { filters, type }` + - `text: string` - Combine multiple filters using `and` or `or`. + The text in the message content that needs to be replaced. - - `filters: array of object { key, type, value } or unknown` + - `type: "file_path"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Always `file_path`. - - `Comparison Filter: object { key, type, value }` + - `value: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The data that makes up the text. - - `key: string` + - `type: "text"` - The key to compare against the value. + Always `text`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `refusal_content_block: object { refusal, type }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The refusal content generated by the assistant. - - `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 + - `refusal: string` - - `"eq"` + - `type: "refusal"` - - `"ne"` + Always `refusal`. - - `"gt"` + - `created_at: number` - - `"gte"` + The Unix timestamp (in seconds) for when the message was created. - - `"lt"` + - `incomplete_at: number` - - `"lte"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"in"` + - `incomplete_details: object { reason }` + + On an incomplete message, details about why the message is incomplete. + + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + + The reason the message is incomplete. + + - `"content_filter"` + + - `"max_tokens"` + + - `"run_cancelled"` + + - `"run_expired"` + + - `"run_failed"` - - `"nin"` + - `metadata: map[string]` - - `value: string or number or boolean or array of unknown` + 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. - The value to compare against the attribute key; supports string, number, or boolean types. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `union_member_0: string` + - `object: "thread.message"` - - `union_member_1: number` + The object type, which is always `thread.message`. - - `union_member_2: boolean` + - `role: "user" or "assistant"` - - `union_member_3: array of unknown` + The entity that produced the message. One of `user` or `assistant`. - - `union_member_1: unknown` + - `"user"` - - `type: "and" or "or"` + - `"assistant"` - Type of operation: `and` or `or`. + - `run_id: string` - - `"and"` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `"or"` + - `status: "in_progress" or "incomplete" or "completed"` - - `max_num_results: optional number` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"in_progress"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"incomplete"` - Ranking options for search. + - `"completed"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `thread_id: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `embedding_weight: number` +### Example - The weight of the embedding in the reciprocal ranking fusion. +```cli +openai beta:threads:messages update \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --message-id message_id +``` - - `text_weight: number` +#### Response - The weight of the text in the reciprocal ranking fusion. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `ranker: optional "auto" or "default-2024-11-15"` +## Retrieve message - The ranker to use for the file search. +`$ openai beta:threads:messages retrieve` - - `"auto"` +**get** `/threads/{thread_id}/messages/{message_id}` - - `"default-2024-11-15"` +Retrieve a message. - - `score_threshold: optional number` +### Parameters - 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. +- `--thread-id: string` - - `beta_computer_tool: object { type }` + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to which this message belongs. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +- `--message-id: string` - - `type: "computer"` + The ID of the message to retrieve. - The type of the computer tool. Always `computer`. +### Returns - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` +- `message: object { id, assistant_id, attachments, 11 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - `display_height: number` + - `id: string` - The height of the computer display. + The identifier, which can be referenced in API endpoints. - - `display_width: number` + - `assistant_id: string` - The width of the computer display. + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `attachments: array of object { file_id, tools }` - The type of computer environment to control. + A list of files attached to the message, and the tools they were added to. - - `"windows"` + - `file_id: optional string` - - `"mac"` + The ID of the file to attach to the message. - - `"linux"` + - `tools: optional array of CodeInterpreterTool or object { type }` - - `"ubuntu"` + The tools to add this file to. - - `"browser"` + - `code_interpreter_tool: object { type }` - - `type: "computer_use_preview"` + - `type: "code_interpreter"` - The type of the computer use tool. Always `computer_use_preview`. + The type of tool being defined: `code_interpreter` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + - `AssistantToolsFileSearchTypeOnly: object { type }` - 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). + - `completed_at: number` - - `type: "web_search" or "web_search_2025_08_26"` + The Unix timestamp (in seconds) for when the message was completed. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `content: array of MessageContent` - - `"web_search"` + The content of the message in array of text and/or images. - - `"web_search_2025_08_26"` + - `image_file_content_block: object { image_file, type }` - - `filters: optional object { allowed_domains }` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - Filters for the search. + - `image_file: object { file_id, detail }` - - `allowed_domains: optional array of string` + - `file_id: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `detail: optional "auto" or "low" or "high"` - - `search_context_size: optional "low" or "medium" or "high"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"auto"` - `"low"` - - `"medium"` - - `"high"` - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. + - `type: "image_file"` - - `city: optional string` + Always `image_file`. - Free text input for the city of the user, e.g. `San Francisco`. + - `image_url_content_block: object { image_url, type }` - - `country: optional string` + References an image URL in the content of a message. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `image_url: object { url, detail }` - - `region: optional string` + - `url: string` - Free text input for the region of the user, e.g. `California`. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `timezone: optional string` + - `detail: optional "auto" or "low" or "high"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: optional "approximate"` + - `"auto"` - The type of location approximation. Always `approximate`. + - `"low"` - - `"approximate"` + - `"high"` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + - `type: "image_url"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + The type of the content part. - - `server_label: string` + - `text_content_block: object { text, type }` - A label for this MCP server, used to identify it in tool calls. + The text content that is part of a message. - - `type: "mcp"` + - `text: object { annotations, value }` - The type of the MCP tool. Always `mcp`. + - `annotations: array of Annotation` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - The tool invocation context(s). + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"direct"` + - `end_index: number` - - `"programmatic"` + - `file_citation: object { file_id }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `file_id: string` - List of allowed tool names or a filter object. + The ID of the specific File the citation is from. - - `MCP allowed tools: array of string` + - `start_index: number` - A string array of allowed tool names + - `text: string` - - `MCP tool filter: object { read_only, tool_names }` + The text in the message content that needs to be replaced. - A filter object to specify which tools are allowed. + - `type: "file_citation"` - - `read_only: optional boolean` + Always `file_citation`. - 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. + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `tool_names: optional array of string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - List of allowed tool names. + - `end_index: number` - - `authorization: optional string` + - `file_path: object { file_id }` - 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. + - `file_id: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The ID of the file that was generated. - 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). + - `start_index: number` - Currently supported `connector_id` values are: + - `text: string` - - 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` + The text in the message content that needs to be replaced. - - `"connector_dropbox"` + - `type: "file_path"` - - `"connector_gmail"` + Always `file_path`. - - `"connector_googlecalendar"` + - `value: string` - - `"connector_googledrive"` + The data that makes up the text. - - `"connector_microsoftteams"` + - `type: "text"` - - `"connector_outlookcalendar"` + Always `text`. - - `"connector_outlookemail"` + - `refusal_content_block: object { refusal, type }` - - `"connector_sharepoint"` + The refusal content generated by the assistant. - - `defer_loading: optional boolean` + - `refusal: string` - Whether this MCP tool is deferred and discovered via tool search. + - `type: "refusal"` - - `headers: optional map[string]` + Always `refusal`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `created_at: number` - - `require_approval: optional object { always, never } or "always" or "never"` + The Unix timestamp (in seconds) for when the message was created. - Specify which of the MCP server's tools require approval. + - `incomplete_at: number` - - `MCP tool approval filter: object { always, never }` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `incomplete_details: object { reason }` - - `always: optional object { read_only, tool_names }` + On an incomplete message, details about why the message is incomplete. - A filter object to specify which tools are allowed. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `read_only: optional boolean` + The reason the message is incomplete. - 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. + - `"content_filter"` - - `tool_names: optional array of string` + - `"max_tokens"` - List of allowed tool names. + - `"run_cancelled"` - - `never: optional object { read_only, tool_names }` + - `"run_expired"` - A filter object to specify which tools are allowed. + - `"run_failed"` - - `read_only: optional boolean` + - `metadata: map[string]` - 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. + 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. - - `tool_names: optional array of string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - List of allowed tool names. + - `object: "thread.message"` - - `MCP tool approval setting: "always" or "never"` + The object type, which is always `thread.message`. - 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. + - `role: "user" or "assistant"` - - `"always"` + The entity that produced the message. One of `user` or `assistant`. - - `"never"` + - `"user"` - - `server_description: optional string` + - `"assistant"` - Optional description of the MCP server, used to provide more context. + - `run_id: string` - - `server_url: optional string` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `status: "in_progress" or "incomplete" or "completed"` - - `tunnel_id: optional string` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - 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. + - `"in_progress"` - - `code_interpreter: object { container, type, allowed_callers }` + - `"incomplete"` - A tool that runs Python code to help generate a response to a prompt. + - `"completed"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `thread_id: string` - 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. + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - `union_member_0: string` +### Example - The container ID. +```cli +openai beta:threads:messages retrieve \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --message-id message_id +``` - - `CodeInterpreterToolAuto: object { type, file_ids, memory_limit, network_policy }` +#### Response - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `type: "auto"` +## Delete message - Always `auto`. +`$ openai beta:threads:messages delete` - - `file_ids: optional array of string` +**delete** `/threads/{thread_id}/messages/{message_id}` - An optional list of uploaded files to make available to your code. +Deletes a message. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` +### Parameters - The memory limit for the code interpreter container. +- `--thread-id: string` - - `"1g"` + The ID of the thread to which this message belongs. - - `"4g"` +- `--message-id: string` - - `"16g"` + The ID of the message to delete. - - `"64g"` +### Returns - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` +- `message_deleted: object { id, deleted, object }` - Network access policy for the container. + - `id: string` - - `beta_container_network_policy_disabled: object { type }` + - `deleted: boolean` - - `type: "disabled"` + - `object: "thread.message.deleted"` - Disable outbound network access. Always `disabled`. +### Example - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` +```cli +openai beta:threads:messages delete \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --message-id message_id +``` - - `allowed_domains: array of string` +#### Response - A list of allowed domains when type is `allowlist`. +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` - - `type: "allowlist"` +## Domain Types - Allow outbound network access only to specified domains. Always `allowlist`. +### Annotation - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` +- `annotation: FileCitationAnnotation or FilePathAnnotation` - Optional domain-scoped secrets for allowlisted domains. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `domain: string` + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - The domain associated with the secret. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `name: string` + - `end_index: number` - The name of the secret to inject for the domain. + - `file_citation: object { file_id }` - - `value: string` + - `file_id: string` - The secret value to inject for the domain. + The ID of the specific File the citation is from. - - `type: "code_interpreter"` + - `start_index: number` - The type of the code interpreter tool. Always `code_interpreter`. + - `text: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The text in the message content that needs to be replaced. - The tool invocation context(s). + - `type: "file_citation"` - - `"direct"` + Always `file_citation`. - - `"programmatic"` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `programmatic_tool_calling: object { type }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `image_generation: object { type, action, background, 9 more }` + - `end_index: number` - A tool that generates images using the GPT image models. + - `file_path: object { file_id }` - - `type: "image_generation"` + - `file_id: string` - The type of the image generation tool. Always `image_generation`. + The ID of the file that was generated. - - `action: optional "generate" or "edit" or "auto"` + - `start_index: number` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `text: string` - - `"generate"` + The text in the message content that needs to be replaced. - - `"edit"` + - `type: "file_path"` - - `"auto"` + Always `file_path`. - - `background: optional "transparent" or "opaque" or "auto"` +### Annotation Delta - 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. +- `annotation_delta: FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - `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. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - - `"transparent"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"opaque"` + - `index: number` - - `"auto"` + The index of the annotation in the text content part. - - `input_fidelity: optional "high" or "low"` + - `type: "file_citation"` - 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`. + Always `file_citation`. - - `"high"` + - `end_index: optional number` - - `"low"` + - `file_citation: optional object { file_id, quote }` - - `input_image_mask: optional object { file_id, image_url }` + - `file_id: optional string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The ID of the specific File the citation is from. - - `file_id: optional string` + - `quote: optional string` - File ID for the mask image. + The specific quote in the file. - - `image_url: optional string` + - `start_index: optional number` - Base64-encoded mask image. + - `text: optional string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + The text in the message content that needs to be replaced. - The image generation model to use. Default: `gpt-image-1`. + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - - `"gpt-image-1"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"gpt-image-1-mini"` + - `index: number` - - `"gpt-image-2"` + The index of the annotation in the text content part. - - `"gpt-image-2-2026-04-21"` + - `type: "file_path"` - - `"gpt-image-1.5"` + Always `file_path`. - - `"chatgpt-image-latest"` + - `end_index: optional number` - - `moderation: optional "auto" or "low"` + - `file_path: optional object { file_id }` - Moderation level for the generated image. Default: `auto`. + - `file_id: optional string` - - `"auto"` + The ID of the file that was generated. - - `"low"` + - `start_index: optional number` - - `output_compression: optional number` + - `text: optional string` - Compression level for the output image. Default: 100. + The text in the message content that needs to be replaced. - - `output_format: optional "png" or "webp" or "jpeg"` +### File Citation Annotation - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. +- `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - - `"png"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"webp"` + - `end_index: number` - - `"jpeg"` + - `file_citation: object { file_id }` - - `partial_images: optional number` + - `file_id: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The ID of the specific File the citation is from. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `start_index: number` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `text: string` - - `"low"` + The text in the message content that needs to be replaced. - - `"medium"` + - `type: "file_citation"` - - `"high"` + Always `file_citation`. - - `"auto"` +### File Citation Delta Annotation - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` +- `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - 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`. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"1024x1024"` + - `index: number` - - `"1024x1536"` + The index of the annotation in the text content part. - - `"1536x1024"` + - `type: "file_citation"` - - `"auto"` + Always `file_citation`. - - `local_shell: object { type }` + - `end_index: optional number` - A tool that allows the model to execute shell commands in a local environment. + - `file_citation: optional object { file_id, quote }` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `file_id: optional string` - A tool that allows the model to execute shell commands. + The ID of the specific File the citation is from. - - `type: "shell"` + - `quote: optional string` - The type of the shell tool. Always `shell`. + The specific quote in the file. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `start_index: optional number` - The tool invocation context(s). + - `text: optional string` - - `"direct"` + The text in the message content that needs to be replaced. - - `"programmatic"` +### File Path Annotation - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` +- `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `beta_container_auto: object { type, file_ids, memory_limit, 2 more }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `type: "container_auto"` + - `end_index: number` - Automatically creates a container for this request + - `file_path: object { file_id }` - - `file_ids: optional array of string` + - `file_id: string` - An optional list of uploaded files to make available to your code. + The ID of the file that was generated. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `start_index: number` - The memory limit for the container. + - `text: string` - - `"1g"` + The text in the message content that needs to be replaced. - - `"4g"` + - `type: "file_path"` - - `"16g"` + Always `file_path`. - - `"64g"` +### File Path Delta Annotation - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` +- `file_path_delta_annotation: object { index, type, end_index, 3 more }` - Network access policy for the container. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `beta_container_network_policy_disabled: object { type }` + - `index: number` - - `beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }` + The index of the annotation in the text content part. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `type: "file_path"` - An optional list of skills referenced by id or inline data. + Always `file_path`. - - `beta_skill_reference: object { skill_id, type, version }` + - `end_index: optional number` - - `skill_id: string` + - `file_path: optional object { file_id }` - The ID of the referenced skill. + - `file_id: optional string` - - `type: "skill_reference"` + The ID of the file that was generated. - References a skill created with the /v1/skills endpoint. + - `start_index: optional number` - - `version: optional string` + - `text: optional string` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The text in the message content that needs to be replaced. - - `beta_inline_skill: object { description, name, source, type }` +### Image File - - `description: string` +- `image_file: object { file_id, detail }` - The description of the skill. + - `file_id: string` - - `name: string` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The name of the skill. + - `detail: optional "auto" or "low" or "high"` - - `source: object { data, media_type, type }` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Inline skill payload + - `"auto"` - - `data: string` + - `"low"` - Base64-encoded skill zip bundle. + - `"high"` - - `media_type: "application/zip"` +### Image File Content Block - The media type of the inline skill payload. Must be `application/zip`. +- `image_file_content_block: object { image_file, type }` - - `type: "base64"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The type of the inline skill source. Must be `base64`. + - `image_file: object { file_id, detail }` - - `type: "inline"` + - `file_id: string` - Defines an inline skill for this request. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `beta_local_environment: object { type, skills }` + - `detail: optional "auto" or "low" or "high"` - - `type: "local"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Use a local computer environment. + - `"auto"` - - `skills: optional array of BetaLocalSkill` + - `"low"` - An optional list of skills. + - `"high"` - - `description: string` + - `type: "image_file"` - The description of the skill. + Always `image_file`. - - `name: string` +### Image File Delta - The name of the skill. +- `image_file_delta: object { detail, file_id }` - - `path: string` + - `detail: optional "auto" or "low" or "high"` - The path to the directory containing the skill. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `beta_container_reference: object { container_id, type }` + - `"auto"` - - `container_id: string` + - `"low"` - The ID of the referenced container. + - `"high"` - - `type: "container_reference"` + - `file_id: optional string` - References a container created with the /v1/containers endpoint + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` +### Image File Delta Block - 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) +- `image_file_delta_block: object { index, type, image_file }` - - `name: string` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The name of the custom tool, used to identify it in tool calls. + - `index: number` - - `type: "custom"` + The index of the content part in the message. - The type of the custom tool. Always `custom`. + - `type: "image_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Always `image_file`. - The tool invocation context(s). + - `image_file: optional object { detail, file_id }` - - `"direct"` + - `detail: optional "auto" or "low" or "high"` - - `"programmatic"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `defer_loading: optional boolean` + - `"auto"` - Whether this tool should be deferred and discovered via tool search. + - `"low"` - - `description: optional string` + - `"high"` - Optional description of the custom tool, used to provide more context. + - `file_id: optional string` - - `format: optional object { type } or object { definition, syntax, type }` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The input format for the custom tool. Default is unconstrained text. +### Image URL - - `text: object { type }` +- `image_url: object { url, detail }` - Unconstrained free-form text. + - `url: string` - - `grammar: object { definition, syntax, type }` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - A grammar defined by the user. + - `detail: optional "auto" or "low" or "high"` - - `definition: string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The grammar definition. + - `"auto"` - - `syntax: "lark" or "regex"` + - `"low"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"high"` - - `"lark"` +### Image URL Content Block - - `"regex"` +- `image_url_content_block: object { image_url, type }` - - `type: "grammar"` + References an image URL in the content of a message. - Grammar format. Always `grammar`. + - `image_url: object { url, detail }` - - `beta_namespace_tool: object { description, name, tools, type }` + - `url: string` - Groups function/custom tools under a shared namespace. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `description: string` + - `detail: optional "auto" or "low" or "high"` - A description of the namespace shown to the model. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `name: string` + - `"auto"` - The namespace name used in tool calls (for example, `crm`). + - `"low"` - - `tools: array of object { name, type, allowed_callers, 5 more } or BetaCustomTool` + - `"high"` - The function/custom tools available inside this namespace. + - `type: "image_url"` - - `function: object { name, type, allowed_callers, 5 more }` + The type of the content part. - - `name: string` +### Image URL Delta - - `type: "function"` +- `image_url_delta: object { detail, url }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `detail: optional "auto" or "low" or "high"` - The tool invocation context(s). + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"direct"` + - `"auto"` - - `"programmatic"` + - `"low"` - - `defer_loading: optional boolean` + - `"high"` - Whether this function should be deferred and discovered via tool search. + - `url: optional string` - - `description: optional string` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `output_schema: optional map[unknown]` +### Image URL Delta Block - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +- `image_url_delta_block: object { index, type, image_url }` - - `parameters: optional unknown` + References an image URL in the content of a message. - - `strict: optional boolean` + - `index: number` - 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. + The index of the content part in the message. - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + - `type: "image_url"` - 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) + Always `image_url`. - - `name: string` + - `image_url: optional object { detail, url }` - The name of the custom tool, used to identify it in tool calls. + - `detail: optional "auto" or "low" or "high"` - - `type: "custom"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The type of the custom tool. Always `custom`. + - `"auto"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"low"` - The tool invocation context(s). + - `"high"` - - `defer_loading: optional boolean` + - `url: optional string` - Whether this tool should be deferred and discovered via tool search. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `description: optional string` +### Message - Optional description of the custom tool, used to provide more context. +- `message: object { id, assistant_id, attachments, 11 more }` - - `format: optional object { type } or object { definition, syntax, type }` + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - The input format for the custom tool. Default is unconstrained text. + - `id: string` - - `type: "namespace"` + The identifier, which can be referenced in API endpoints. - The type of the tool. Always `namespace`. + - `assistant_id: string` - - `beta_tool_search_tool: object { type, description, execution, parameters }` + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - Hosted or BYOT tool search configuration for deferred tools. + - `attachments: array of object { file_id, tools }` - - `type: "tool_search"` + A list of files attached to the message, and the tools they were added to. - The type of the tool. Always `tool_search`. + - `file_id: optional string` - - `description: optional string` + The ID of the file to attach to the message. - Description shown to the model for a client-executed tool search tool. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `execution: optional "server" or "client"` + The tools to add this file to. - Whether tool search is executed by the server or by the client. + - `code_interpreter_tool: object { type }` - - `"server"` + - `type: "code_interpreter"` - - `"client"` + The type of tool being defined: `code_interpreter` - - `parameters: optional unknown` + - `AssistantToolsFileSearchTypeOnly: object { type }` - Parameter schema for a client-executed tool search tool. + - `completed_at: number` - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + The Unix timestamp (in seconds) for when the message was completed. - 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). + - `content: array of MessageContent` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The content of the message in array of text and/or images. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `image_file_content_block: object { image_file, type }` - - `"web_search_preview"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `"web_search_preview_2025_03_11"` + - `image_file: object { file_id, detail }` - - `search_content_types: optional array of "text" or "image"` + - `file_id: string` - - `"text"` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `"image"` + - `detail: optional "auto" or "low" or "high"` - - `search_context_size: optional "low" or "medium" or "high"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"auto"` - `"low"` - - `"medium"` - - `"high"` - - `user_location: optional object { type, city, country, 2 more }` - - The user's location. + - `type: "image_file"` - - `type: "approximate"` + Always `image_file`. - The type of location approximation. Always `approximate`. + - `image_url_content_block: object { image_url, type }` - - `city: optional string` + References an image URL in the content of a message. - Free text input for the city of the user, e.g. `San Francisco`. + - `image_url: object { url, detail }` - - `country: optional string` + - `url: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `region: optional string` + - `detail: optional "auto" or "low" or "high"` - Free text input for the region of the user, e.g. `California`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `timezone: optional string` + - `"auto"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"low"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `"high"` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "image_url"` - - `type: "apply_patch"` + The type of the content part. - The type of the tool. Always `apply_patch`. + - `text_content_block: object { text, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The text content that is part of a message. - The tool invocation context(s). + - `text: object { annotations, value }` - - `"direct"` + - `annotations: array of Annotation` - - `"programmatic"` + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - - `type: "tool_search_output"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The type of the item. Always `tool_search_output`. + - `end_index: number` - - `agent: optional object { agent_name }` + - `file_citation: object { file_id }` - The agent that produced this item. + - `file_id: string` - - `agent_name: string` + The ID of the specific File the citation is from. - The canonical name of the agent that produced this item. + - `start_index: number` - - `created_by: optional string` + - `text: string` - The identifier of the actor that created the item. + The text in the message content that needs to be replaced. - - `additional_tools: object { id, role, tools, 2 more }` + - `type: "file_citation"` - - `id: string` + Always `file_citation`. - The unique ID of the additional tools item. + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `role: "unknown" or "user" or "assistant" or 5 more` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The role that provided the additional tools. + - `end_index: number` - - `"unknown"` + - `file_path: object { file_id }` - - `"user"` + - `file_id: string` - - `"assistant"` + The ID of the file that was generated. - - `"system"` + - `start_index: number` - - `"critic"` + - `text: string` - - `"discriminator"` + The text in the message content that needs to be replaced. - - `"developer"` + - `type: "file_path"` - - `"tool"` + Always `file_path`. - - `tools: array of BetaTool` + - `value: string` - The additional tool definitions made available at this item. + The data that makes up the text. - - `beta_function_tool: object { name, parameters, strict, 5 more }` + - `type: "text"` - 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). + Always `text`. - - `beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }` + - `refusal_content_block: object { refusal, type }` - 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). + The refusal content generated by the assistant. - - `beta_computer_tool: object { type }` + - `refusal: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "refusal"` - - `beta_computer_use_preview_tool: object { display_height, display_width, environment, type }` + Always `refusal`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `created_at: number` - - `beta_web_search_tool: object { type, filters, search_context_size, user_location }` + The Unix timestamp (in seconds) for when the message was created. - 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). + - `incomplete_at: number` - - `mcp: object { server_label, type, allowed_callers, 9 more }` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + - `incomplete_details: object { reason }` - - `code_interpreter: object { container, type, allowed_callers }` + On an incomplete message, details about why the message is incomplete. - A tool that runs Python code to help generate a response to a prompt. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `programmatic_tool_calling: object { type }` + The reason the message is incomplete. - - `image_generation: object { type, action, background, 9 more }` + - `"content_filter"` - A tool that generates images using the GPT image models. + - `"max_tokens"` - - `local_shell: object { type }` + - `"run_cancelled"` - A tool that allows the model to execute shell commands in a local environment. + - `"run_expired"` - - `beta_function_shell_tool: object { type, allowed_callers, environment }` + - `"run_failed"` - A tool that allows the model to execute shell commands. + - `metadata: map[string]` - - `beta_custom_tool: object { name, type, allowed_callers, 3 more }` + 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. - 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) + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `beta_namespace_tool: object { description, name, tools, type }` + - `object: "thread.message"` - Groups function/custom tools under a shared namespace. + The object type, which is always `thread.message`. - - `beta_tool_search_tool: object { type, description, execution, parameters }` + - `role: "user" or "assistant"` - Hosted or BYOT tool search configuration for deferred tools. + The entity that produced the message. One of `user` or `assistant`. - - `beta_web_search_preview_tool: object { type, search_content_types, search_context_size, user_location }` + - `"user"` - 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). + - `"assistant"` - - `beta_apply_patch_tool: object { type, allowed_callers }` + - `run_id: string` - Allows the assistant to create, delete, or update files using unified diffs. + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `type: "additional_tools"` + - `status: "in_progress" or "incomplete" or "completed"` - The type of the item. Always `additional_tools`. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `agent: optional object { agent_name }` + - `"in_progress"` - The agent that produced this item. + - `"incomplete"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `thread_id: string` - - `beta_response_reasoning_item: object { id, summary, type, 4 more }` + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - 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). +### Message Content - - `id: string` +- `message_content: ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - The unique identifier of the reasoning content. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `summary: array of object { text, type }` + - `image_file_content_block: object { image_file, type }` - Reasoning summary content. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `text: string` + - `image_file: object { file_id, detail }` - A summary of the reasoning output from the model so far. + - `file_id: string` - - `type: "summary_text"` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The type of the object. Always `summary_text`. + - `detail: optional "auto" or "low" or "high"` - - `type: "reasoning"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The type of the object. Always `reasoning`. + - `"auto"` - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `"high"` - - `agent_name: string` + - `type: "image_file"` - The canonical name of the agent that produced this item. + Always `image_file`. - - `content: optional array of object { text, type }` + - `image_url_content_block: object { image_url, type }` - Reasoning text content. + References an image URL in the content of a message. - - `text: string` + - `image_url: object { url, detail }` - The reasoning text from the model. + - `url: string` - - `type: "reasoning_text"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the reasoning text. Always `reasoning_text`. + - `detail: optional "auto" or "low" or "high"` - - `encrypted_content: optional string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"low"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"high"` - - `"in_progress"` + - `type: "image_url"` - - `"completed"` + The type of the content part. - - `"incomplete"` + - `text_content_block: object { text, type }` - - `program: object { id, call_id, code, 3 more }` + The text content that is part of a message. - - `id: string` + - `text: object { annotations, value }` - The unique ID of the program item. + - `annotations: array of Annotation` - - `call_id: string` + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - The stable call ID of the program item. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `code: string` + - `end_index: number` - The JavaScript source executed by programmatic tool calling. + - `file_citation: object { file_id }` - - `fingerprint: string` + - `file_id: string` - Opaque program replay fingerprint that must be round-tripped. + The ID of the specific File the citation is from. - - `type: "program"` + - `start_index: number` - The type of the item. Always `program`. + - `text: string` - - `agent: optional object { agent_name }` + The text in the message content that needs to be replaced. - The agent that produced this item. + - `type: "file_citation"` - - `agent_name: string` + Always `file_citation`. - The canonical name of the agent that produced this item. + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `program_output: object { id, call_id, result, 3 more }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `id: string` + - `end_index: number` - The unique ID of the program output item. + - `file_path: object { file_id }` - - `call_id: string` + - `file_id: string` - The call ID of the program item. + The ID of the file that was generated. - - `result: string` + - `start_index: number` - The result produced by the program item. + - `text: string` - - `status: "completed" or "incomplete"` + The text in the message content that needs to be replaced. - The terminal status of the program output item. + - `type: "file_path"` - - `"completed"` + Always `file_path`. - - `"incomplete"` + - `value: string` - - `type: "program_output"` + The data that makes up the text. - The type of the item. Always `program_output`. + - `type: "text"` - - `agent: optional object { agent_name }` + Always `text`. - The agent that produced this item. + - `refusal_content_block: object { refusal, type }` - - `agent_name: string` + The refusal content generated by the assistant. - The canonical name of the agent that produced this item. + - `refusal: string` - - `beta_response_compaction_item: object { id, encrypted_content, type, 2 more }` + - `type: "refusal"` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + Always `refusal`. - - `id: string` +### Message Content Delta - The unique ID of the compaction item. +- `message_content_delta: ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - - `encrypted_content: string` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The encrypted content that was produced by compaction. + - `image_file_delta_block: object { index, type, image_file }` - - `type: "compaction"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The type of the item. Always `compaction`. + - `index: number` - - `agent: optional object { agent_name }` + The index of the content part in the message. - The agent that produced this item. + - `type: "image_file"` - - `agent_name: string` + Always `image_file`. - The canonical name of the agent that produced this item. + - `image_file: optional object { detail, file_id }` - - `created_by: optional string` + - `detail: optional "auto" or "low" or "high"` - The identifier of the actor that created the item. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `image_generation_call: object { id, result, status, 2 more }` + - `"auto"` - An image generation request made by the model. + - `"low"` - - `id: string` + - `"high"` - The unique ID of the image generation call. + - `file_id: optional string` - - `result: string` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The generated image encoded in base64. + - `text_delta_block: object { index, type, text }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The text content that is part of a message. - The status of the image generation call. + - `index: number` - - `"in_progress"` + The index of the content part in the message. - - `"completed"` + - `type: "text"` - - `"generating"` + Always `text`. - - `"failed"` + - `text: optional object { annotations, value }` - - `type: "image_generation_call"` + - `annotations: optional array of AnnotationDelta` - The type of the image generation call. Always `image_generation_call`. + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - - `agent: optional object { agent_name }` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The agent that produced this item. + - `index: number` - - `agent_name: string` + The index of the annotation in the text content part. - The canonical name of the agent that produced this item. + - `type: "file_citation"` - - `beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }` + Always `file_citation`. - A tool call to run code. + - `end_index: optional number` - - `id: string` + - `file_citation: optional object { file_id, quote }` - The unique ID of the code interpreter tool call. + - `file_id: optional string` - - `code: string` + The ID of the specific File the citation is from. - The code to run, or null if not available. + - `quote: optional string` - - `container_id: string` + The specific quote in the file. - The ID of the container used to run the code. + - `start_index: optional number` - - `outputs: array of object { logs, type } or object { type, url }` + - `text: optional string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The text in the message content that needs to be replaced. - - `logs: object { logs, type }` + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - The logs output from the code interpreter. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `logs: string` + - `index: number` - The logs output from the code interpreter. + The index of the annotation in the text content part. - - `type: "logs"` + - `type: "file_path"` - The type of the output. Always `logs`. + Always `file_path`. - - `image: object { type, url }` + - `end_index: optional number` - The image output from the code interpreter. + - `file_path: optional object { file_id }` - - `type: "image"` + - `file_id: optional string` - The type of the output. Always `image`. + The ID of the file that was generated. - - `url: string` + - `start_index: optional number` - The URL of the image output from the code interpreter. + - `text: optional string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The text in the message content that needs to be replaced. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `value: optional string` - - `"in_progress"` + The data that makes up the text. - - `"completed"` + - `refusal_delta_block: object { index, type, refusal }` - - `"incomplete"` + The refusal content that is part of a message. - - `"interpreting"` + - `index: number` - - `"failed"` + The index of the refusal part in the message. - - `type: "code_interpreter_call"` + - `type: "refusal"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + Always `refusal`. - - `agent: optional object { agent_name }` + - `refusal: optional string` - The agent that produced this item. + - `image_url_delta_block: object { index, type, image_url }` - - `agent_name: string` + References an image URL in the content of a message. - The canonical name of the agent that produced this item. + - `index: number` - - `local_shell_call: object { id, action, call_id, 3 more }` + The index of the content part in the message. - A tool call to run a command on the local shell. + - `type: "image_url"` - - `id: string` + Always `image_url`. - The unique ID of the local shell call. + - `image_url: optional object { detail, url }` - - `action: object { command, env, type, 3 more }` + - `detail: optional "auto" or "low" or "high"` - Execute a shell command on the server. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `command: array of string` + - `"auto"` - The command to run. + - `"low"` - - `env: map[string]` + - `"high"` - Environment variables to set for the command. + - `url: optional string` - - `type: "exec"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the local shell action. Always `exec`. +### Message Content Part Param - - `timeout_ms: optional number` +- `message_content_part_param: ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - Optional timeout in milliseconds for the command. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `user: optional string` + - `image_file_content_block: object { image_file, type }` - Optional user to run the command as. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `working_directory: optional string` + - `image_file: object { file_id, detail }` - Optional working directory to run the command in. + - `file_id: string` - - `call_id: string` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The unique ID of the local shell tool call generated by the model. + - `detail: optional "auto" or "low" or "high"` - - `status: "in_progress" or "completed" or "incomplete"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The status of the local shell call. + - `"auto"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `type: "image_file"` - - `type: "local_shell_call"` + Always `image_file`. - The type of the local shell call. Always `local_shell_call`. + - `image_url_content_block: object { image_url, type }` - - `agent: optional object { agent_name }` + References an image URL in the content of a message. - The agent that produced this item. + - `image_url: object { url, detail }` - - `agent_name: string` + - `url: string` - The canonical name of the agent that produced this item. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `local_shell_call_output: object { id, output, type, 2 more }` + - `detail: optional "auto" or "low" or "high"` - The output of a local shell tool call. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `id: string` + - `"auto"` - The unique ID of the local shell tool call generated by the model. + - `"low"` - - `output: string` + - `"high"` - A JSON string of the output of the local shell tool call. + - `type: "image_url"` - - `type: "local_shell_call_output"` + The type of the content part. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `text_content_block_param: object { text, type }` - - `agent: optional object { agent_name }` + The text content that is part of a message. - The agent that produced this item. + - `text: string` - - `agent_name: string` + Text content to be sent to the model - The canonical name of the agent that produced this item. + - `type: "text"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Always `text`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. +### Message Deleted - - `"in_progress"` +- `message_deleted: object { id, deleted, object }` - - `"completed"` + - `id: string` - - `"incomplete"` + - `deleted: boolean` - - `beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }` + - `object: "thread.message.deleted"` - A tool call that executes one or more shell commands in a managed environment. +### Message Delta - - `id: string` +- `message_delta: object { content, role }` - The unique ID of the shell tool call. Populated when this item is returned via API. + The delta containing the fields that have changed on the Message. - - `action: object { commands, max_output_length, timeout_ms }` + - `content: optional array of MessageContentDelta` - The shell commands and limits that describe how to run the tool call. + The content of the message in array of text and/or images. - - `commands: array of string` + - `image_file_delta_block: object { index, type, image_file }` - - `max_output_length: number` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - Optional maximum number of characters to return from each command. + - `index: number` - - `timeout_ms: number` + The index of the content part in the message. - Optional timeout in milliseconds for the commands. + - `type: "image_file"` - - `call_id: string` + Always `image_file`. - The unique ID of the shell tool call generated by the model. + - `image_file: optional object { detail, file_id }` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `detail: optional "auto" or "low" or "high"` - Represents the use of a local environment to perform shell actions. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `beta_response_local_environment: object { type }` + - `"auto"` - Represents the use of a local environment to perform shell actions. + - `"low"` - - `type: "local"` + - `"high"` - The environment type. Always `local`. + - `file_id: optional string` - - `beta_response_container_reference: object { container_id, type }` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Represents a container created with /v1/containers. + - `text_delta_block: object { index, type, text }` - - `container_id: string` + The text content that is part of a message. - - `type: "container_reference"` + - `index: number` - The environment type. Always `container_reference`. + The index of the content part in the message. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "text"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Always `text`. - - `"in_progress"` + - `text: optional object { annotations, value }` - - `"completed"` + - `annotations: optional array of AnnotationDelta` - - `"incomplete"` + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - - `type: "shell_call"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The type of the item. Always `shell_call`. + - `index: number` - - `agent: optional object { agent_name }` + The index of the annotation in the text content part. - The agent that produced this item. + - `type: "file_citation"` - - `agent_name: string` + Always `file_citation`. - The canonical name of the agent that produced this item. + - `end_index: optional number` - - `caller: optional object { type } or object { caller_id, type }` + - `file_citation: optional object { file_id, quote }` - The execution context that produced this tool call. + - `file_id: optional string` - - `direct: object { type }` + The ID of the specific File the citation is from. - - `program: object { caller_id, type }` + - `quote: optional string` - - `caller_id: string` + The specific quote in the file. - The call ID of the program item that produced this tool call. + - `start_index: optional number` - - `type: "program"` + - `text: optional string` - - `created_by: optional string` + The text in the message content that needs to be replaced. - The ID of the entity that created this tool call. + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - - `beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The output of a shell tool call that was emitted. + - `index: number` - - `id: string` + The index of the annotation in the text content part. - The unique ID of the shell call output. Populated when this item is returned via API. + - `type: "file_path"` - - `call_id: string` + Always `file_path`. - The unique ID of the shell tool call generated by the model. + - `end_index: optional number` - - `max_output_length: number` + - `file_path: optional object { file_id }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `file_id: optional string` - - `output: array of object { outcome, stderr, stdout, created_by }` + The ID of the file that was generated. - An array of shell call output contents + - `start_index: optional number` - - `outcome: object { type } or object { exit_code, type }` + - `text: optional string` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The text in the message content that needs to be replaced. - - `timeout: object { type }` + - `value: optional string` - Indicates that the shell call exceeded its configured time limit. + The data that makes up the text. - - `exit: object { exit_code, type }` + - `refusal_delta_block: object { index, type, refusal }` - Indicates that the shell commands finished and returned an exit code. + The refusal content that is part of a message. - - `exit_code: number` + - `index: number` - Exit code from the shell process. + The index of the refusal part in the message. - - `type: "exit"` + - `type: "refusal"` - The outcome type. Always `exit`. + Always `refusal`. - - `stderr: string` + - `refusal: optional string` - The standard error output that was captured. + - `image_url_delta_block: object { index, type, image_url }` - - `stdout: string` + References an image URL in the content of a message. - The standard output that was captured. + - `index: number` - - `created_by: optional string` + The index of the content part in the message. - The identifier of the actor that created the item. + - `type: "image_url"` - - `status: "in_progress" or "completed" or "incomplete"` + Always `image_url`. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `image_url: optional object { detail, url }` - - `"in_progress"` + - `detail: optional "auto" or "low" or "high"` - - `"completed"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"incomplete"` + - `"auto"` - - `type: "shell_call_output"` + - `"low"` - The type of the shell call output. Always `shell_call_output`. + - `"high"` - - `agent: optional object { agent_name }` + - `url: optional string` - The agent that produced this item. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `agent_name: string` + - `role: optional "user" or "assistant"` - The canonical name of the agent that produced this item. + The entity that produced the message. One of `user` or `assistant`. - - `caller: optional object { type } or object { caller_id, type }` + - `"user"` - The execution context that produced this tool call. + - `"assistant"` - - `direct: object { type }` +### Message Delta Event - - `program: object { caller_id, type }` +- `message_delta_event: object { id, delta, object }` - - `caller_id: string` + Represents a message delta i.e. any changed fields on a message during streaming. - The call ID of the program item that produced this tool call. + - `id: string` - - `type: "program"` + The identifier of the message, which can be referenced in API endpoints. - - `created_by: optional string` + - `delta: object { content, role }` - The identifier of the actor that created the item. + The delta containing the fields that have changed on the Message. - - `beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }` + - `content: optional array of MessageContentDelta` - A tool call that applies file diffs by creating, deleting, or updating files. + The content of the message in array of text and/or images. - - `id: string` + - `image_file_delta_block: object { index, type, image_file }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `call_id: string` + - `index: number` - The unique ID of the apply patch tool call generated by the model. + The index of the content part in the message. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `type: "image_file"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Always `image_file`. - - `create_file: object { diff, path, type }` + - `image_file: optional object { detail, file_id }` - Instruction describing how to create a file via the apply_patch tool. + - `detail: optional "auto" or "low" or "high"` - - `diff: string` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Diff to apply. + - `"auto"` - - `path: string` + - `"low"` - Path of the file to create. + - `"high"` - - `type: "create_file"` + - `file_id: optional string` - Create a new file with the provided diff. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `delete_file: object { path, type }` + - `text_delta_block: object { index, type, text }` - Instruction describing how to delete a file via the apply_patch tool. + The text content that is part of a message. - - `path: string` + - `index: number` - Path of the file to delete. + The index of the content part in the message. - - `type: "delete_file"` + - `type: "text"` - Delete the specified file. + Always `text`. - - `update_file: object { diff, path, type }` + - `text: optional object { annotations, value }` - Instruction describing how to update a file via the apply_patch tool. + - `annotations: optional array of AnnotationDelta` - - `diff: string` + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - Diff to apply. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `path: string` + - `index: number` - Path of the file to update. + The index of the annotation in the text content part. - - `type: "update_file"` + - `type: "file_citation"` - Update an existing file with the provided diff. + Always `file_citation`. - - `status: "in_progress" or "completed"` + - `end_index: optional number` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `file_citation: optional object { file_id, quote }` - - `"in_progress"` + - `file_id: optional string` - - `"completed"` + The ID of the specific File the citation is from. - - `type: "apply_patch_call"` + - `quote: optional string` - The type of the item. Always `apply_patch_call`. + The specific quote in the file. - - `agent: optional object { agent_name }` + - `start_index: optional number` - The agent that produced this item. + - `text: optional string` - - `agent_name: string` + The text in the message content that needs to be replaced. - The canonical name of the agent that produced this item. + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - - `caller: optional object { type } or object { caller_id, type }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The execution context that produced this tool call. + - `index: number` - - `direct: object { type }` + The index of the annotation in the text content part. - - `program: object { caller_id, type }` + - `type: "file_path"` - - `caller_id: string` + Always `file_path`. - The call ID of the program item that produced this tool call. + - `end_index: optional number` - - `type: "program"` + - `file_path: optional object { file_id }` - - `created_by: optional string` + - `file_id: optional string` - The ID of the entity that created this tool call. + The ID of the file that was generated. - - `beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }` + - `start_index: optional number` - The output emitted by an apply patch tool call. + - `text: optional string` - - `id: string` + The text in the message content that needs to be replaced. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `value: optional string` - - `call_id: string` + The data that makes up the text. - The unique ID of the apply patch tool call generated by the model. + - `refusal_delta_block: object { index, type, refusal }` - - `status: "completed" or "failed"` + The refusal content that is part of a message. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `index: number` - - `"completed"` + The index of the refusal part in the message. - - `"failed"` + - `type: "refusal"` - - `type: "apply_patch_call_output"` + Always `refusal`. - The type of the item. Always `apply_patch_call_output`. + - `refusal: optional string` - - `agent: optional object { agent_name }` + - `image_url_delta_block: object { index, type, image_url }` - The agent that produced this item. + References an image URL in the content of a message. - - `agent_name: string` + - `index: number` - The canonical name of the agent that produced this item. + The index of the content part in the message. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "image_url"` - The execution context that produced this tool call. + Always `image_url`. - - `direct: object { type }` + - `image_url: optional object { detail, url }` - - `program: object { caller_id, type }` + - `detail: optional "auto" or "low" or "high"` - - `caller_id: string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The call ID of the program item that produced this tool call. + - `"auto"` - - `type: "program"` + - `"low"` - - `created_by: optional string` + - `"high"` - The ID of the entity that created this tool call output. + - `url: optional string` - - `output: optional string` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Optional textual output returned by the apply patch tool. + - `role: optional "user" or "assistant"` - - `mcp_list_tools: object { id, server_label, tools, 3 more }` + The entity that produced the message. One of `user` or `assistant`. - A list of tools available on an MCP server. + - `"user"` - - `id: string` + - `"assistant"` - The unique ID of the list. + - `object: "thread.message.delta"` - - `server_label: string` + The object type, which is always `thread.message.delta`. - The label of the MCP server. +### Refusal Content Block - - `tools: array of object { input_schema, name, annotations, description }` +- `refusal_content_block: object { refusal, type }` - The tools available on the server. + The refusal content generated by the assistant. - - `input_schema: unknown` + - `refusal: string` - The JSON schema describing the tool's input. + - `type: "refusal"` - - `name: string` + Always `refusal`. - The name of the tool. +### Refusal Delta Block - - `annotations: optional unknown` +- `refusal_delta_block: object { index, type, refusal }` - Additional annotations about the tool. + The refusal content that is part of a message. - - `description: optional string` + - `index: number` - The description of the tool. + The index of the refusal part in the message. - - `type: "mcp_list_tools"` + - `type: "refusal"` - The type of the item. Always `mcp_list_tools`. + Always `refusal`. - - `agent: optional object { agent_name }` + - `refusal: optional string` - The agent that produced this item. +### Text - - `agent_name: string` +- `text: object { annotations, value }` - The canonical name of the agent that produced this item. + - `annotations: array of Annotation` - - `error: optional string` + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - Error message if the server could not list tools. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `mcp_approval_request: object { id, arguments, name, 3 more }` + - `end_index: number` - A request for human approval of a tool invocation. + - `file_citation: object { file_id }` - - `id: string` + - `file_id: string` - The unique ID of the approval request. + The ID of the specific File the citation is from. - - `arguments: string` + - `start_index: number` - A JSON string of arguments for the tool. + - `text: string` - - `name: string` + The text in the message content that needs to be replaced. - The name of the tool to run. + - `type: "file_citation"` - - `server_label: string` + Always `file_citation`. - The label of the MCP server making the request. + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `type: "mcp_approval_request"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The type of the item. Always `mcp_approval_request`. + - `end_index: number` - - `agent: optional object { agent_name }` + - `file_path: object { file_id }` - The agent that produced this item. + - `file_id: string` - - `agent_name: string` + The ID of the file that was generated. - The canonical name of the agent that produced this item. + - `start_index: number` - - `mcp_approval_response: object { id, approval_request_id, approve, 3 more }` + - `text: string` - A response to an MCP approval request. + The text in the message content that needs to be replaced. - - `id: string` + - `type: "file_path"` - The unique ID of the approval response + Always `file_path`. - - `approval_request_id: string` + - `value: string` - The ID of the approval request being answered. + The data that makes up the text. - - `approve: boolean` +### Text Content Block - Whether the request was approved. +- `text_content_block: object { text, type }` - - `type: "mcp_approval_response"` + The text content that is part of a message. - The type of the item. Always `mcp_approval_response`. + - `text: object { annotations, value }` - - `agent: optional object { agent_name }` + - `annotations: array of Annotation` - The agent that produced this item. + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` - - `agent_name: string` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The canonical name of the agent that produced this item. + - `end_index: number` - - `reason: optional string` + - `file_citation: object { file_id }` - Optional reason for the decision. + - `file_id: string` - - `mcp_call: object { id, arguments, name, 7 more }` + The ID of the specific File the citation is from. - An invocation of a tool on an MCP server. + - `start_index: number` - - `id: string` + - `text: string` - The unique ID of the tool call. + The text in the message content that needs to be replaced. - - `arguments: string` + - `type: "file_citation"` - A JSON string of the arguments passed to the tool. + Always `file_citation`. - - `name: string` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - The name of the tool that was run. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `server_label: string` + - `end_index: number` - The label of the MCP server running the tool. + - `file_path: object { file_id }` - - `type: "mcp_call"` + - `file_id: string` - The type of the item. Always `mcp_call`. + The ID of the file that was generated. - - `agent: optional object { agent_name }` + - `start_index: number` - The agent that produced this item. + - `text: string` - - `agent_name: string` + The text in the message content that needs to be replaced. - The canonical name of the agent that produced this item. + - `type: "file_path"` - - `approval_request_id: optional string` + Always `file_path`. - 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. + - `value: string` - - `error: optional string` + The data that makes up the text. - The error from the tool call, if any. + - `type: "text"` - - `output: optional string` + Always `text`. - The output from the tool call. +### Text Content Block Param - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` +- `text_content_block_param: object { text, type }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The text content that is part of a message. - - `"in_progress"` + - `text: string` - - `"completed"` + Text content to be sent to the model - - `"incomplete"` + - `type: "text"` - - `"calling"` + Always `text`. - - `"failed"` +### Text Delta - - `beta_response_custom_tool_call_item: BetaResponseCustomToolCall` +- `text_delta: object { annotations, value }` - A call to a custom tool created by the model. + - `annotations: optional array of AnnotationDelta` - - `id: string` + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - The unique ID of the custom tool call item. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `status: "in_progress" or "completed" or "incomplete"` + - `index: number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The index of the annotation in the text content part. - - `"in_progress"` + - `type: "file_citation"` - - `"completed"` + Always `file_citation`. - - `"incomplete"` + - `end_index: optional number` - - `created_by: optional string` + - `file_citation: optional object { file_id, quote }` - The identifier of the actor that created the item. + - `file_id: optional string` - - `beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput` + The ID of the specific File the citation is from. - The output of a custom tool call from your code, being sent back to the model. + - `quote: optional string` - - `id: string` + The specific quote in the file. - The unique ID of the custom tool call output item. + - `start_index: optional number` - - `status: "in_progress" or "completed" or "incomplete"` + - `text: optional string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The text in the message content that needs to be replaced. - - `"in_progress"` + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - - `"completed"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"incomplete"` + - `index: number` - - `created_by: optional string` + The index of the annotation in the text content part. - The identifier of the actor that created the item. + - `type: "file_path"` - - `first_id: string` + Always `file_path`. - The ID of the first item in the list. + - `end_index: optional number` - - `has_more: boolean` + - `file_path: optional object { file_id }` - Whether there are more items available. + - `file_id: optional string` - - `last_id: string` + The ID of the file that was generated. - The ID of the last item in the list. + - `start_index: optional number` - - `object: "list"` + - `text: optional string` - The type of object returned, must be `list`. + The text in the message content that needs to be replaced. -# Input Tokens + - `value: optional string` -## Get input token counts + The data that makes up the text. -`$ openai beta:responses:input-tokens count` +### Text Delta Block -**post** `/responses/input_tokens?beta=true` +- `text_delta_block: object { index, type, text }` -Get input token counts + The text content that is part of a message. -### Parameters + - `index: number` -- `--conversation: optional string or BetaResponseConversationParam` + The index of the content part in the message. - Body param: The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + - `type: "text"` -- `--input: optional string or array of BetaResponseInputItem` + Always `text`. - Body param: Text, image, or file inputs to the model, used to generate a response + - `text: optional object { annotations, value }` -- `--instructions: optional string` + - `annotations: optional array of AnnotationDelta` - Body param: 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. + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` -- `--model: optional string` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - Body param: Model ID used to generate the response, like `gpt-4o` 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. + - `index: number` -- `--parallel-tool-calls: optional boolean` + The index of the annotation in the text content part. - Body param: Whether to allow the model to run tool calls in parallel. + - `type: "file_citation"` -- `--personality: optional string or "friendly" or "pragmatic"` + Always `file_citation`. - Body param: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + - `end_index: optional number` -- `--previous-response-id: optional string` + - `file_citation: optional object { file_id, quote }` - Body param: 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`. + - `file_id: optional string` -- `--reasoning: optional object { context, effort, generate_summary, 2 more }` + The ID of the specific File the citation is from. - Body param: **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `quote: optional string` -- `--text: optional object { format, verbosity }` + The specific quote in the file. - Body param: Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `start_index: optional number` - - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + - `text: optional string` -- `--tool-choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + The text in the message content that needs to be replaced. - Body param: Controls which tool the model should use, if any. + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` -- `--tool: optional array of BetaTool` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Body param: An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. + - `index: number` -- `--truncation: optional "auto" or "disabled"` + The index of the annotation in the text content part. - Body param: The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error. + - `type: "file_path"` -- `--beta: optional array of "responses_multi_agent=v1"` + Always `file_path`. - Header param: Optional beta features to enable for this request. + - `end_index: optional number` -### Returns + - `file_path: optional object { file_id }` -- `InputTokenCountResponse: object { input_tokens, object }` + - `file_id: optional string` - - `input_tokens: number` + The ID of the file that was generated. - - `object: "response.input_tokens"` + - `start_index: optional number` -### Example + - `text: optional string` -```cli -openai beta:responses:input-tokens count \ - --api-key 'My API Key' -``` + The text in the message content that needs to be replaced. -#### Response + - `value: optional string` -```json -{ - "input_tokens": 123, - "object": "response.input_tokens" -} -``` + The data that makes up the text.