Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Responses

Create and manage model responses.

Cancel a response
POST
/responses/{response_id}/cancel
Compact conversation
POST
/responses/compact
Connect
WebSocket
/responses
Create a model response
POST
/responses
Delete a model response
DELETE
/responses/{response_id}
Get a model response
GET
/responses/{response_id}
Models
BetaCompactedResponse object { id, created_at, object, 3 more }
BetaComputerAction = Click { button, type, x, 2 more } or DoubleClick { keys, type, x, y } or Drag { path, type, keys } or 6 more

A click action.

BetaComputerActionList = array of BetaComputerAction

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

BetaContainerAuto object { type, file_ids, memory_limit, 2 more }
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
BetaContainerNetworkPolicyDisabled object { type }
type: "disabled" (default: "disabled")

Disable outbound network access. Always disabled.

BetaContainerNetworkPolicyDomainSecret object { domain, name, value }
BetaContainerReference object { container_id, type }
container_id: string

The ID of the referenced container.

type: "container_reference" (default: "container_reference")

References a container created with the /v1/containers endpoint

BetaEasyInputMessage 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.

BetaImageDetail = "low" or "high" or "auto" or "original"
BetaInlineSkill object { description, name, source, type }
BetaInlineSkillSource object { data, media_type, type }

Inline skill payload

BetaLocalEnvironment object { type, skills }
BetaLocalSkill object { description, name, path }
BetaMcpToolCallError = McpProtocolError { code, message, type } or McpToolExecutionError { content, type } or HTTPError { code, message, type }
BetaResponse object { id, access_programs, created_at, 37 more }
BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }

Emitted when there is a partial audio response.

BetaResponseAudioDoneEvent object { sequence_number, type, agent }

Emitted when the audio response is complete.

BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }

Emitted when there is a partial transcript of audio.

BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }

Emitted when the full audio transcript is completed.

BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }

Emitted when a partial code snippet is streamed by the code interpreter.

BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }

Emitted when the code snippet is finalized by the code interpreter.

BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when the code interpreter call is completed.

BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when a code interpreter call is in progress.

BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when the code interpreter is actively interpreting the code snippet.

BetaResponseCompactionCompactingEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when new summary content is sampled for a compaction trigger. Contains no summary content.

BetaResponseCompletedEvent object { response, sequence_number, type, agent }

Emitted when the model response is complete.

BetaResponseComputerToolCallOutputScreenshot object { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

BetaResponseContainerReference object { container_id, type }

Represents a container created with /v1/containers.

container_id: string
type: "container_reference" (default: "container_reference")

The environment type. Always container_reference.

BetaResponseContent = BetaResponseInputText { text, type, prompt_cache_breakpoint } or BetaResponseInputImage { detail, type, file_id, 2 more } or BetaResponseInputFile { type, detail, file_data, 4 more } or 3 more

Multi-modal input and output contents.

BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }

Emitted when a new content part is added.

BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }

Emitted when a content part is done.

BetaResponseConversationParam object { id }

The conversation that this response belongs to.

id: string

The unique ID of the conversation.

BetaResponseCreatedEvent object { response, sequence_number, type, agent }

An event that is emitted when a response is created.

BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }

Event representing a delta (partial update) to the input of a custom tool call.

BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }

Event indicating that input for a custom tool call is complete.

BetaResponseDeleteResponse object { id, deleted, object }
BetaResponseError object { code, message, misalignment, 2 more }

An error object returned when the model fails to generate a Response.

BetaResponseErrorEvent object { code, message, param, 3 more }

Emitted when an error occurs.

BetaResponseFailedEvent object { response, sequence_number, type, agent }

An event that is emitted when a response fails.

BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when a file search call is completed (results found).

BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when a file search call is initiated.

BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when a file search is currently searching.

BetaResponseFormatTextConfig = Text { type } or BetaResponseFormatTextJSONSchemaConfig { name, schema, type, 2 more } or JSONObject { 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.

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.

BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }

JSON Schema response format. Used to generate structured JSON responses. Learn more about Structured Outputs.

BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }

Emitted when there is a partial function-call arguments delta.

BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }

Emitted when function-call arguments are finalized.

BetaResponseFunctionShellCallOutputContent object { outcome, stderr, stdout }

Captured stdout and stderr for a portion of a shell tool call output.

BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when an image generation tool call has completed and the final image is available.

BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when an image generation tool call is actively generating an image (intermediate state).

BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when an image generation tool call is in progress.

BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 8 more }

Emitted when a partial image is available during image generation streaming.

BetaResponseInProgressEvent object { response, sequence_number, type, agent }

Emitted when the response is in progress.

BetaResponseIncludable = "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more

Specify additional output data to include in the model response. Currently supported values are:

  • 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).
BetaResponseIncompleteEvent object { response, sequence_number, type, agent }

An event that is emitted when a response finishes as incomplete.

Over WebSocket, steering can finish a response with response.incomplete_details.reason set to steered, followed automatically by a successor response.created that commits the queued steering input.

BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }

Emitted when all injected input items were validated and committed to the active response.

BetaResponseInjectEvent object { input, response_id, type }

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.

BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }

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.

BetaResponseInputAudio object { input_audio, type }

An audio input to the model.

BetaResponseInputContent = BetaResponseInputText { text, type, prompt_cache_breakpoint } or BetaResponseInputImage { detail, type, file_id, 2 more } or BetaResponseInputFile { type, detail, file_data, 4 more }

A text input to the model.

BetaResponseInputFile object { type, detail, file_data, 4 more }

A file input to the model.

BetaResponseInputFileContent object { type, detail, file_data, 4 more }

A file input to the model.

BetaResponseInputImage object { detail, type, file_id, 2 more }

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

BetaResponseInputImageContent object { type, detail, file_id, 2 more }

An image input to the model. Learn about image inputs

BetaResponseInputMessageContentList = array of BetaResponseInputContent

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

BetaResponseInputMessageItem object { id, content, role, 3 more }
BetaResponseInputText object { text, type, prompt_cache_breakpoint }

A text input to the model.

BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }

A text input to the model.

BetaResponseLocalEnvironment object { type }

Represents the use of a local environment to perform shell actions.

type: "local" (default: "local")

The environment type. Always local.

BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }

Emitted when there is a delta (partial update) to the arguments of an MCP tool call.

BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }

Emitted when the arguments for an MCP tool call are finalized.

BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call has completed successfully.

BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call has failed.

BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call is in progress.

BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when the list of available MCP tools has been successfully retrieved.

BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when the attempt to list available MCP tools has failed.

BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when the system is in the process of retrieving the list of available MCP tools.

BetaResponseOutputAudio object { data, transcript, type }

An audio output from the model.

BetaResponseOutputItem = BetaResponseOutputMessage { id, content, role, 4 more } or FileSearchCall { id, queries, status, 3 more } or FunctionCall { arguments, call_id, name, 7 more } or 28 more

An output message from the model.

BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }

Emitted when a new output item is added.

BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }

Emitted when an output item is marked done.

BetaResponseOutputMessage object { id, content, role, 4 more }

An output message from the model.

BetaResponseOutputRefusal object { refusal, type }

A refusal from the model.

refusal: string

The refusal explanation from the model.

type: "refusal" (default: "refusal")

The type of the refusal. Always refusal.

BetaResponseOutputText object { annotations, logprobs, text, type }

A text output from the model.

BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }

Emitted when an annotation is added to output text content.

BetaResponsePrompt object { id, variables, version }

Reference to a prompt template and its variables. Learn more.

BetaResponseQueuedEvent object { response, sequence_number, type, agent }

Emitted when a response is queued and waiting to be processed.

BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }

Emitted when a new reasoning summary part is added.

BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }

Emitted when a reasoning summary part is completed.

BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }

Emitted when a delta is added to a reasoning summary text.

BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }

Emitted when a reasoning summary text is completed.

BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }

Emitted when a delta is added to a reasoning text.

BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }

Emitted when a reasoning text is completed.

BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }

Emitted when there is a partial refusal text.

BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }

Emitted when refusal text is finalized.

BetaResponseShellCallCommandAddedEvent object { command, command_index, output_index, 3 more }

A streaming event that indicated a shell command was added to a tool call.

BetaResponseShellCallCommandDeltaEvent object { command_index, delta, output_index, 4 more }

A streaming event that indicated a shell command was incrementally updated.

BetaResponseShellCallCommandDoneEvent object { command, command_index, output_index, 3 more }

A streaming event that indicated a shell command was completed.

BetaResponseShellCallOutputContentDeltaEvent object { command_index, delta, item_id, 4 more }

A streaming event that indicated shell call output was incrementally added.

BetaResponseShellCallOutputContentDoneEvent object { command_index, item_id, output, 4 more }

A streaming event that indicated shell call output was completed.

BetaResponseStatus = "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.

BetaResponseSteerAcceptedEvent object { sequence_number, steer, type, stream_id }

Emitted when steering input has been validated and queued. Acceptance means the server owns the input, not that it has been applied. The successor’s response.created event is the commit point. If accepted input cannot be committed, response.steer.failed returns it with the same steering ID.

When the response stops for client-owned tool output or approval, the input remains queued and response.steer.pending is emitted after response.completed. Fill the pending event’s required_input stubs with saved results and send one matching explicit response.create per parent. Do not resend accepted input while it is still queued.

BetaResponseSteerErrorCode = "response_not_found" or "invalid_input" or "steering_not_supported" or 4 more or string

A machine-readable steering error code. Clients should handle unknown values because additional codes may be introduced. Known values include:

  • response_not_found: The target response is not available on this connection.
  • invalid_input: The event or input failed validation.
  • steering_not_supported: The model or response execution mode does not support steering.
  • too_many_pending_steers: Too much steering input is pending for the response.
  • response_already_completed: The response completed and is no longer accepting steering input.
  • response_not_active: The response is no longer accepting steering input.
  • successor_creation_failed: The successor response could not be created.
BetaResponseSteerEvent object { input, previous_response_id, type }

Queues user input to steer a response on this WebSocket connection. Input can contain text, images, and files. Steering is supported only for single-agent responses on models and execution modes that support steering. Responses bound to a conversation or using automatic compaction do not support steering.

A response.steer.accepted event acknowledges that the server owns the queued input, not that it has been applied. The successor’s response.created event is the commit point. Input that cannot be committed is returned in response.steer.failed.

Steering may cause the active response to finish at a safe output boundary with response.incomplete and incomplete_details.reason set to steered, followed automatically by a successor response.created. Normal completion can also be followed by an automatic successor. Automatic successors inherit the previous response’s settings and continue from it with the queued input.

If the response stops for client-owned tool output or approval, accepted steering input remains queued and response.steer.pending is emitted after response.completed. Fill the required_input stubs from that event with saved tool results or approval decisions, and send one explicit response.create per parent with the same previous_response_id and WebSocket lane. Do not rerun tools or resend accepted steering input. The queued input is prepended in submission order to that request’s input, and the explicit request retains its own settings.

This event accepts only type, previous_response_id, and input. Do not send stream_id; the target response determines the WebSocket lane.

BetaResponseSteerFailedEvent object { error, sequence_number, steer, 2 more }

Emitted when steering input is rejected or cannot be committed to a successor response. Returns the original, uncommitted input so the client can carry it into response.create when appropriate. Invalid input must be corrected before retrying.

Failures after acceptance include the same steering ID. Failures before an ID is allocated omit steer.id. A lost connection or missing acknowledgement leaves the outcome unknown; it is not proof that the input was rejected.

BetaResponseSteerInput = string or array of Message { content, role, type, 3 more } or FunctionCallOutput { output, type, id, 6 more }

Input to queue for a continuation of the response. Uses the same string or input-item shape as response.create.input, with a non-empty array when supplying input items.

Steering accepts only messages with the user role. Each message may contain only type, role, and content, with content as a string or an array of input_text, input_image, and input_file parts. The optional type must be message. Other roles, tool outputs, and item types are not supported for steering.

BetaResponseSteerPendingEvent object { reason, required_input, sequence_number, 3 more }

Emitted when accepted steering input remains queued after the target response completes. The server still owns the input. Do not resend it. The successor’s response.created event is the commit point.

When reason is waiting_for_required_input, this event follows response.completed while the response waits for the tool results or approval decisions identified by required_input. Copy those stubs, fill their result fields using the ordinary response.create input schemas, and submit one continuation per parent with the same previous_response_id and WebSocket lane. Use saved results without rerunning tools. The queued steering input is prepended in submission order to the continuation’s input. That explicit request retains its own settings.

This notification is emitted at most once per steering submission. Multiple submissions for the same parent can report the same required inputs; they do not each require a separate continuation.

BetaResponseSteerPendingReason = "waiting_for_required_input" or string

An extensible enum describing why accepted steering input is still queued. Clients should handle unknown values because additional reasons may be introduced. Known values include:

  • waiting_for_required_input: The response is waiting for the tool results or approval decisions identified by required_input.
One of the following:
"waiting_for_required_input"

An extensible enum describing why accepted steering input is still queued. Clients should handle unknown values because additional reasons may be introduced. Known values include:

  • waiting_for_required_input: The response is waiting for the tool results or approval decisions identified by required_input.
string
BetaResponseSteerRequiredInput = FunctionCallOutput { call_id, name, type } or CustomToolCallOutput { call_id, type } or ComputerCallOutput { call_id, type } or 4 more

An input stub identifying an outstanding client-owned tool result or approval decision. Copy the stub and fill the result fields using the corresponding response.create input schema. Use saved results without rerunning the tool. The server does not supply results, approval decisions, or safety acknowledgements in these stubs.

BetaResponseStreamEvent = BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } or BetaResponseAudioDoneEvent { sequence_number, type, agent } or BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } or 56 more

Event emitted while a response is streamed.

BetaResponseTextConfig object { format, verbosity }

Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more:

BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }

Emitted when there is an additional text delta.

BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }

Emitted when text content is finalized.

BetaResponseUsage 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.

BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is completed.

BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is initiated.

BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is executing.

BetaResponsesClientEvent = ResponseCreate { type, access_programs, background, 34 more } or BetaResponseSteerEvent { input, previous_response_id, type } or BetaResponseInjectEvent { input, response_id, type }

Client events accepted by the Responses WebSocket server.

BetaResponsesServerEvent = BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } or BetaResponseAudioDoneEvent { sequence_number, type, agent } or BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } or 61 more

Server events emitted by the Responses WebSocket server.

BetaServiceTier = "auto" or "default" or "flex" or 4 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’, then the request will be processed with the Flex Processing service tier.
  • To opt-in to Fast mode at the request level, include the service_tier=fast or service_tier=priority parameter for Responses or Chat Completions. The response will show service_tier=priority regardless of if you specify service_tier=fast or priority in your request.
  • If set to ‘ultrafast’, then the request will be processed with the access-controlled Ultrafast Processing service tier. This tier is currently available for gpt-5.6-sol; a response served through it will show service_tier=ultrafast.
  • 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.

BetaSkillReference object { skill_id, type, version }
BetaToolChoiceAllowed object { mode, tools, type }

Constrains the tools available to the model to a pre-defined set.

BetaToolChoiceApplyPatch object { type }

Forces the model to call the apply_patch tool when executing a tool call.

type: "apply_patch" (default: "apply_patch")

The tool to call. Always apply_patch.

BetaToolChoiceCustom 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.

BetaToolChoiceFunction 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.

BetaToolChoiceMcp object { server_label, type, name }

Use this option to force the model to call a specific tool on a remote MCP server.

BetaToolChoiceOptions = "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.

BetaToolChoiceShell object { type }

Forces the model to call the shell tool when a tool call is required.

type: "shell" (default: "shell")

The tool to call. Always shell.

BetaToolChoiceTypes object { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

BetaToolSearchOutputNamespaceTool object { description, name, tools, type }

Groups function/custom tools under a shared namespace.

ResponsesInput Items

Create and manage model responses.

List input items
GET
/responses/{response_id}/input_items
Models
BetaResponseItemList object { data, first_id, has_more, 2 more }

A list of Response items.

ResponsesInput Tokens

Create and manage model responses.

Get input token counts
POST
/responses/input_tokens
Models
InputTokenCountResponse object { input_tokens, object }
input_tokens: integer
object: "response.input_tokens" (default: "response.input_tokens")