API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Responses

Cancel a response

beta.responses.cancel(response_id, **kwargs) -> BetaResponse { id, created_at, error, 31 more }

POST/responses/{response_id}/cancel

Compact a response

beta.responses.compact(**kwargs) -> BetaCompactedResponse { id, created_at, object, 2 more }

POST/responses/compact

Create a model response

beta.responses.create(**kwargs) -> BetaResponse { id, created_at, error, 31 more }

POST/responses

Delete a model response

beta.responses.delete(response_id, **kwargs) -> void

DELETE/responses/{response_id}

Get a model response

beta.responses.retrieve(response_id, **kwargs) -> BetaResponse { id, created_at, error, 31 more }

GET/responses/{response_id}

ModelsExpand Collapse

class BetaApplyPatchTool { type, allowed_callers }

Allows the assistant to create, delete, or update files using unified diffs.

class BetaCompactedResponse { id, created_at, object, 2 more }

BetaComputerAction = Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more

A click action.

BetaComputerActionList = Array[BetaComputerAction]

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

class BetaComputerTool { type }

A tool that controls a virtual computer. Learn more about the computer tool.

class BetaComputerUsePreviewTool { display_height, display_width, environment, type }

A tool that controls a virtual computer. Learn more about the computer tool.

class BetaContainerAuto { type, file_ids, memory_limit, 2 more }

class BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }

class BetaContainerNetworkPolicyDisabled { type }

class BetaContainerNetworkPolicyDomainSecret { domain, name, value }

class BetaContainerReference { container_id, type }

class BetaCustomTool { name, type, allowed_callers, 3 more }

A custom tool that processes input using a specified format. Learn more about custom tools

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

class BetaFileSearchTool { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files. Learn more about the file search tool.

class BetaFunctionShellTool { type, allowed_callers, environment }

A tool that allows the model to execute shell commands.

class BetaFunctionTool { name, parameters, strict, 5 more }

Defines a function in your own code the model can choose to call. Learn more about function calling.

class BetaInlineSkill { description, name, source, type }

class BetaInlineSkillSource { data, media_type, type }

Inline skill payload

class BetaLocalEnvironment { type, skills }

class BetaLocalSkill { description, name, path }

BetaMcpToolCallError = McpProtocolError{ code, message, type} | McpToolExecutionError{ content, type} | HTTPError{ code, message, type}

class BetaNamespaceTool { description, name, tools, type }

Groups function/custom tools under a shared namespace.

class BetaResponse { id, created_at, error, 31 more }

class BetaResponseApplyPatchToolCall { id, call_id, operation, 5 more }

A tool call that applies file diffs by creating, deleting, or updating files.

class BetaResponseApplyPatchToolCallOutput { id, call_id, status, 5 more }

The output emitted by an apply patch tool call.

class BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent }

Emitted when there is a partial audio response.

class BetaResponseAudioDoneEvent { sequence_number, type, agent }

Emitted when the audio response is complete.

class BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent }

Emitted when there is a partial transcript of audio.

class BetaResponseAudioTranscriptDoneEvent { sequence_number, type, agent }

Emitted when the full audio transcript is completed.

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

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

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

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

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

Emitted when the code interpreter call is completed.

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

Emitted when a code interpreter call is in progress.

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

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

class BetaResponseCodeInterpreterToolCall { id, code, container_id, 4 more }

A tool call to run code.

class BetaResponseCompactionItem { id, encrypted_content, type, 2 more }

A compaction item generated by the v1/responses/compact API.

class BetaResponseCompactionItemParam { encrypted_content, type, id, agent }

A compaction item generated by the v1/responses/compact API.

class BetaResponseCompletedEvent { response, sequence_number, type, agent }

Emitted when the model response is complete.

class BetaResponseComputerToolCall { id, call_id, pending_safety_checks, 5 more }

A tool call to a computer use tool. See the computer use guide for more information.

class BetaResponseComputerToolCallOutputItem { id, call_id, output, 5 more }

class BetaResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

class BetaResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

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

Multi-modal input and output contents.

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

Emitted when a new content part is added.

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

Emitted when a content part is done.

class BetaResponseConversationParam { id }

The conversation that this response belongs to.

class BetaResponseCreatedEvent { response, sequence_number, type, agent }

An event that is emitted when a response is created.

class BetaResponseCustomToolCall { call_id, input, name, 5 more }

A call to a custom tool created by the model.

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

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

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

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

class BetaResponseCustomToolCallItem { id, status, created_by }

A call to a custom tool created by the model.

class BetaResponseCustomToolCallOutput { call_id, output, type, 3 more }

The output of a custom tool call from your code, being sent back to the model.

class BetaResponseCustomToolCallOutputItem { id, status, created_by }

The output of a custom tool call from your code, being sent back to the model.

class BetaResponseError { code, message }

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

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

Emitted when an error occurs.

class BetaResponseFailedEvent { response, sequence_number, type, agent }

An event that is emitted when a response fails.

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

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

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

Emitted when a file search call is initiated.

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

Emitted when a file search is currently searching.

class BetaResponseFileSearchToolCall { id, queries, status, 3 more }

The results of a file search tool call. See the file search guide for more information.

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

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

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

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

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

class BetaResponseFunctionCallArgumentsDoneEvent { arguments, item_id, name, 4 more }

Emitted when function-call arguments are finalized.

BetaResponseFunctionCallOutputItem = BetaResponseInputTextContent { text, type, prompt_cache_breakpoint } | BetaResponseInputImageContent { type, detail, file_id, 2 more } | BetaResponseInputFileContent { type, detail, file_data, 4 more }

A piece of message content, such as text, an image, or a file.

BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]

An array of content outputs (text, image, file) for the function tool call.

class BetaResponseFunctionShellCallOutputContent { outcome, stderr, stdout }

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

class BetaResponseFunctionShellToolCall { id, action, call_id, 6 more }

A tool call that executes one or more shell commands in a managed environment.

class BetaResponseFunctionShellToolCallOutput { id, call_id, max_output_length, 6 more }

The output of a shell tool call that was emitted.

class BetaResponseFunctionToolCall { arguments, call_id, name, 6 more }

A tool call to run a function. See the function calling guide for more information.

class BetaResponseFunctionToolCallItem { id, status, created_by }

A tool call to run a function. See the function calling guide for more information.

class BetaResponseFunctionToolCallOutputItem { id, call_id, output, 7 more }

class BetaResponseFunctionWebSearch { id, action, status, 2 more }

The results of a web search tool call. See the web search guide for more information.

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

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

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

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

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

Emitted when an image generation tool call is in progress.

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

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

class BetaResponseInProgressEvent { response, sequence_number, type, agent }

Emitted when the response is in progress.

BetaResponseIncludable = :"file_search_call.results" | :"web_search_call.results" | :"web_search_call.action.sources" | 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).

class BetaResponseIncompleteEvent { response, sequence_number, type, agent }

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

class BetaResponseInjectCreatedEvent { response_id, sequence_number, type, stream_id }

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

class BetaResponseInjectEvent { 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.

class BetaResponseInjectFailedEvent { 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.

BetaResponseInput = Array[BetaResponseInputItem]

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

class BetaResponseInputAudio { input_audio, type }

An audio input to the model.

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

A text input to the model.

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

A file input to the model.

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

A file input to the model.

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

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

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

An image input to the model. Learn about image inputs

BetaResponseInputItem = BetaEasyInputMessage { content, role, phase, type } | Message{ content, role, agent, 2 more} | BetaResponseOutputMessage { id, content, role, 4 more } | 32 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.

BetaResponseInputMessageContentList = Array[BetaResponseInputContent]

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

class BetaResponseInputMessageItem { id, content, role, 3 more }

class BetaResponseInputText { text, type, prompt_cache_breakpoint }

A text input to the model.

class BetaResponseInputTextContent { text, type, prompt_cache_breakpoint }

A text input to the model.

BetaResponseItem = BetaResponseInputMessageItem { id, content, role, 3 more } | BetaResponseOutputMessage { id, content, role, 4 more } | BetaResponseFileSearchToolCall { id, queries, status, 3 more } | 29 more

Content item used to generate a response.

class BetaResponseLocalEnvironment { type }

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

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

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

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

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

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

Emitted when an MCP tool call has completed successfully.

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

Emitted when an MCP tool call has failed.

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

Emitted when an MCP tool call is in progress.

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

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

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

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

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

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

class BetaResponseOutputAudio { data, transcript, type }

An audio output from the model.

BetaResponseOutputItem = BetaResponseOutputMessage { id, content, role, 4 more } | BetaResponseFileSearchToolCall { id, queries, status, 3 more } | BetaResponseFunctionToolCall { arguments, call_id, name, 6 more } | 28 more

An output message from the model.

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

Emitted when a new output item is added.

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

Emitted when an output item is marked done.

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

An output message from the model.

class BetaResponseOutputRefusal { refusal, type }

A refusal from the model.

class BetaResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

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

Emitted when an annotation is added to output text content.

class BetaResponsePrompt { id, variables, version }

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

class BetaResponseQueuedEvent { response, sequence_number, type, agent }

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

class BetaResponseReasoningItem { 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.

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

Emitted when a new reasoning summary part is added.

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

Emitted when a reasoning summary part is completed.

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

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

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

Emitted when a reasoning summary text is completed.

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

Emitted when a delta is added to a reasoning text.

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

Emitted when a reasoning text is completed.

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

Emitted when there is a partial refusal text.

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

Emitted when refusal text is finalized.

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

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

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

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

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

A streaming event that indicated a shell command was completed.

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

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

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

A streaming event that indicated shell call output was completed.

BetaResponseStatus = :completed | :failed | :in_progress | 3 more

The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete.

BetaResponseStreamEvent = BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } | BetaResponseAudioDoneEvent { sequence_number, type, agent } | BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } | 55 more

Event emitted while a response is streamed.

class BetaResponseTextConfig { 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
• Structured Outputs

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

Emitted when there is an additional text delta.

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

Emitted when text content is finalized.

class BetaResponseToolSearchCall { id, arguments, call_id, 5 more }

class BetaResponseToolSearchOutputItem { id, call_id, execution, 5 more }

class BetaResponseToolSearchOutputItemParam { tools, type, id, 4 more }

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

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

Emitted when a web search call is completed.

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

Emitted when a web search call is initiated.

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

Emitted when a web search call is executing.

BetaResponsesClientEvent = ResponseCreate{ type, background, context_management, 31 more} | BetaResponseInjectEvent { input, response_id, type }

Client events accepted by the Responses WebSocket server.

BetaResponsesServerEvent = BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } & { stream_id} | BetaResponseAudioDoneEvent { sequence_number, type, agent } & { stream_id} | BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } & { stream_id} | 57 more

Server events emitted by the Responses WebSocket server.

class BetaSkillReference { skill_id, type, version }

BetaTool = BetaFunctionTool { name, parameters, strict, 5 more } | BetaFileSearchTool { type, vector_store_ids, filters, 2 more } | BetaComputerTool { type } | 13 more

A tool that can be used to generate a response.

class BetaToolChoiceAllowed { mode, tools, type }

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

class BetaToolChoiceApplyPatch { type }

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

class BetaToolChoiceCustom { name, type }

Use this option to force the model to call a specific custom tool.

class BetaToolChoiceFunction { name, type }

Use this option to force the model to call a specific function.

class BetaToolChoiceMcp { server_label, type, name }

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

BetaToolChoiceOptions = :none | :auto | :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.

class BetaToolChoiceShell { type }

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

class BetaToolChoiceTypes { type }

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

class BetaToolSearchTool { type, description, execution, parameters }

Hosted or BYOT tool search configuration for deferred tools.

class BetaWebSearchPreviewTool { 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.

class BetaWebSearchTool { type, external_web_access, filters, 2 more }

Search the Internet for sources related to the prompt. Learn more about the web search tool.

ResponsesInput Items

List input items

beta.responses.input_items.list(response_id, **kwargs) -> CursorPage<BetaResponseItem>

GET/responses/{response_id}/input_items

ModelsExpand Collapse

class BetaResponseItemList { data, first_id, has_more, 2 more }

A list of Response items.

ResponsesInput Tokens

Get input token counts

beta.responses.input_tokens.count(**kwargs) -> InputTokenCountResponse { input_tokens, object }

POST/responses/input_tokens

ModelsExpand Collapse

class InputTokenCountResponse { input_tokens, object }