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
CompactedResponse object { id, created_at, object, 3 more }
ComputerAction = Click { button, type, x, 2 more } or DoubleClick { keys, type, x, y } or Drag { path, type, keys } or 6 more

A click action.

ComputerActionList = array of ComputerAction

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

ContainerAuto object { type, file_ids, memory_limit, 2 more }
ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
ContainerNetworkPolicyDisabled object { type }
type: "disabled" (default: "disabled")

Disable outbound network access. Always disabled.

ContainerNetworkPolicyDomainSecret object { domain, name, value }
ContainerReference 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

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

ImageDetail = "low" or "high" or "auto" or "original"
InlineSkill object { description, name, source, type }
InlineSkillSource object { data, media_type, type }

Inline skill payload

LocalEnvironment object { type, skills }
LocalSkill object { description, name, path }
description: string

The description of the skill.

name: string

The name of the skill.

path: string

The path to the directory containing the skill.

McpToolCallError = McpProtocolError { code, message, type } or McpToolExecutionError { content, type } or HTTPError { code, message, type }
Response object { id, access_programs, created_at, 36 more }
ResponseAudioDeltaEvent object { delta, sequence_number, type }

Emitted when there is a partial audio response.

delta: string

A chunk of Base64 encoded response audio bytes.

sequence_number: integer

A sequence number for this chunk of the stream response.

type: "response.audio.delta"

The type of the event. Always response.audio.delta.

ResponseAudioDoneEvent object { sequence_number, type }

Emitted when the audio response is complete.

sequence_number: integer

The sequence number of the delta.

type: "response.audio.done"

The type of the event. Always response.audio.done.

ResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type }

Emitted when there is a partial transcript of audio.

delta: string

The partial transcript of the audio response.

sequence_number: integer

The sequence number of this event.

type: "response.audio.transcript.delta"

The type of the event. Always response.audio.transcript.delta.

ResponseAudioTranscriptDoneEvent object { sequence_number, type }

Emitted when the full audio transcript is completed.

sequence_number: integer

The sequence number of this event.

type: "response.audio.transcript.done"

The type of the event. Always response.audio.transcript.done.

ResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 2 more }

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

ResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 2 more }

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

ResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, type }

Emitted when the code interpreter call is completed.

ResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, type }

Emitted when a code interpreter call is in progress.

ResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, type }

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

ResponseCompactionCompactingEvent object { item_id, output_index, sequence_number, type }

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

ResponseCompletedEvent object { response, sequence_number, type }

Emitted when the model response is complete.

ResponseComputerToolCallOutputScreenshot object { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

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

ResponseContent = ResponseInputText { text, type, prompt_cache_breakpoint } or ResponseInputImage { detail, type, file_id, 2 more } or ResponseInputFile { type, detail, file_data, 4 more } or 3 more

Multi-modal input and output contents.

ResponseContentPartAddedEvent object { content_index, item_id, output_index, 3 more }

Emitted when a new content part is added.

ResponseContentPartDoneEvent object { content_index, item_id, output_index, 3 more }

Emitted when a content part is done.

ResponseConversationParam object { id }

The conversation that this response belongs to.

id: string

The unique ID of the conversation.

ResponseCreatedEvent object { response, sequence_number, type }

An event that is emitted when a response is created.

ResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 2 more }

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

ResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 2 more }

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

ResponseDeleteResponse object { id, deleted, object }
id: string
deleted: boolean
object: "response.deleted" (default: "response.deleted")
ResponseError object { code, message, misalignment, 2 more }

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

ResponseErrorEvent object { code, message, param, 2 more }

Emitted when an error occurs.

ResponseFailedEvent object { response, sequence_number, type }

An event that is emitted when a response fails.

ResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, type }

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

ResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, type }

Emitted when a file search call is initiated.

ResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, type }

Emitted when a file search is currently searching.

ResponseFormatTextConfig = ResponseFormatText { type } or ResponseFormatTextJSONSchemaConfig { name, schema, type, 2 more } or ResponseFormatJSONObject { 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.

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

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

ResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 2 more }

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

ResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, output_index, 2 more }

Emitted when function-call arguments are finalized.

ResponseFunctionShellCallOutputContent object { outcome, stderr, stdout }

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

ResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, type }

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

ResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, type }

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

ResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, type }

Emitted when an image generation tool call is in progress.

ResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 7 more }

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

ResponseInProgressEvent object { response, sequence_number, type }

Emitted when the response is in progress.

ResponseIncludable = "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).
ResponseIncompleteEvent object { response, sequence_number, type }

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.

ResponseInputAudio object { input_audio, type }

An audio input to the model.

ResponseInputContent = ResponseInputText { text, type, prompt_cache_breakpoint } or ResponseInputImage { detail, type, file_id, 2 more } or ResponseInputFile { type, detail, file_data, 4 more }

A text input to the model.

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

A file input to the model.

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

A file input to the model.

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

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

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

An image input to the model. Learn about image inputs

ResponseInputMessageContentList = array of ResponseInputContent

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

ResponseInputMessageItem object { id, content, role, 2 more }
ResponseInputText object { text, type, prompt_cache_breakpoint }

A text input to the model.

ResponseInputTextContent object { text, type, prompt_cache_breakpoint }

A text input to the model.

ResponseLocalEnvironment object { type }

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

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

The environment type. Always local.

ResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 2 more }

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

ResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 2 more }

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

ResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, type }

Emitted when an MCP tool call has completed successfully.

ResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, type }

Emitted when an MCP tool call has failed.

ResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, type }

Emitted when an MCP tool call is in progress.

ResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, type }

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

ResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, type }

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

ResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, type }

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

ResponseOutputAudio object { data, transcript, type }

An audio output from the model.

data: string

Base64-encoded audio data from the model.

transcript: string

The transcript of the audio data from the model.

type: "output_audio"

The type of the output audio. Always output_audio.

ResponseOutputItem = ResponseOutputMessage { id, content, role, 3 more } or FileSearchCall { id, queries, status, 2 more } or FunctionCall { arguments, call_id, name, 6 more } or 25 more

An output message from the model.

ResponseOutputItemAddedEvent object { item, output_index, sequence_number, type }

Emitted when a new output item is added.

ResponseOutputItemDoneEvent object { item, output_index, sequence_number, type }

Emitted when an output item is marked done.

ResponseOutputMessage object { id, content, role, 3 more }

An output message from the model.

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

ResponseOutputText object { annotations, logprobs, text, type }

A text output from the model.

ResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 4 more }

Emitted when an annotation is added to output text content.

ResponsePrompt object { id, variables, version }

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

ResponseQueuedEvent object { response, sequence_number, type }

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

ResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 3 more }

Emitted when a new reasoning summary part is added.

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

Emitted when a reasoning summary part is completed.

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

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

ResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 3 more }

Emitted when a reasoning summary text is completed.

ResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 3 more }

Emitted when a delta is added to a reasoning text.

ResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 3 more }

Emitted when a reasoning text is completed.

ResponseRefusalDeltaEvent object { content_index, delta, item_id, 3 more }

Emitted when there is a partial refusal text.

ResponseRefusalDoneEvent object { content_index, item_id, output_index, 3 more }

Emitted when refusal text is finalized.

ResponseShellCallCommandAddedEvent object { command, command_index, output_index, 2 more }

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

ResponseShellCallCommandDeltaEvent object { command_index, delta, output_index, 3 more }

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

ResponseShellCallCommandDoneEvent object { command, command_index, output_index, 2 more }

A streaming event that indicated a shell command was completed.

ResponseShellCallOutputContentDeltaEvent object { command_index, delta, item_id, 3 more }

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

ResponseShellCallOutputContentDoneEvent object { command_index, item_id, output, 3 more }

A streaming event that indicated shell call output was completed.

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

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

ResponseSteerErrorCode = "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.
ResponseSteerEvent 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.

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

ResponseSteerInput = string or array of Message { content, role, type, 2 more } or FunctionCallOutput { output, type, id, 5 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.

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

ResponseSteerPendingReason = "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
ResponseSteerRequiredInput = 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.

ResponseStreamEvent = ResponseAudioDeltaEvent { delta, sequence_number, type } or ResponseAudioDoneEvent { sequence_number, type } or ResponseAudioTranscriptDeltaEvent { delta, sequence_number, type } or 56 more

Event emitted while a response is streamed.

ResponseTextConfig object { format, verbosity }

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

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

Emitted when there is an additional text delta.

ResponseTextDoneEvent object { content_index, item_id, logprobs, 4 more }

Emitted when text content is finalized.

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

ResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, type }

Emitted when a web search call is completed.

ResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, type }

Emitted when a web search call is initiated.

ResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, type }

Emitted when a web search call is executing.

ResponsesClientEvent = ResponseCreate { type, access_programs, background, 33 more } or ResponseSteerEvent { input, previous_response_id, type }

Client events accepted by the Responses WebSocket server.

ResponsesServerEvent = ResponseAudioDeltaEvent { delta, sequence_number, type } or ResponseAudioDoneEvent { sequence_number, type } or ResponseAudioTranscriptDeltaEvent { delta, sequence_number, type } or 59 more

Server events emitted by the Responses WebSocket server.

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

SkillReference object { skill_id, type, version }
ToolChoiceAllowed object { mode, tools, type }

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

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

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

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

ToolChoiceMcp 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 or null

The name of the tool to call on the server.

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

One of the following:
"none"
"auto"
"required"
ToolChoiceShell 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.

ToolChoiceTypes object { type }

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

ToolSearchOutputNamespaceTool 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
ResponseItemList 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")