API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Responses

Cancel a response

Response responses().cancel(ResponseCancelParamsparams = ResponseCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

POST/responses/{response_id}/cancel

Compact a response

CompactedResponse responses().compact(ResponseCompactParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

POST/responses/compact

Create a model response

Response responses().create(ResponseCreateParamsparams = ResponseCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

POST/responses

Delete a model response

responses().delete(ResponseDeleteParamsparams = ResponseDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

DELETE/responses/{response_id}

Get a model response

Response responses().retrieve(ResponseRetrieveParamsparams = ResponseRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/responses/{response_id}

ModelsExpand Collapse

class ApplyPatchTool:

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

class CompactedResponse:

class ComputerAction: A class that can be one of several variants.union

A click action.

class ComputerTool:

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

class ComputerUsePreviewTool:

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

class ContainerAuto:

class ContainerNetworkPolicyAllowlist:

class ContainerNetworkPolicyDisabled:

class ContainerNetworkPolicyDomainSecret:

class ContainerReference:

class CustomTool:

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

class EasyInputMessage:

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 FileSearchTool:

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

class FunctionShellTool:

A tool that allows the model to execute shell commands.

class FunctionTool:

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

class InlineSkill:

class InlineSkillSource:

Inline skill payload

class LocalEnvironment:

class LocalSkill:

class McpToolCallError: A class that can be one of several variants.union

class NamespaceTool:

Groups function/custom tools under a shared namespace.

class Response:

class ResponseApplyPatchToolCall:

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

class ResponseApplyPatchToolCallOutput:

The output emitted by an apply patch tool call.

class ResponseAudioDeltaEvent:

Emitted when there is a partial audio response.

class ResponseAudioDoneEvent:

Emitted when the audio response is complete.

class ResponseAudioTranscriptDeltaEvent:

Emitted when there is a partial transcript of audio.

class ResponseAudioTranscriptDoneEvent:

Emitted when the full audio transcript is completed.

class ResponseCodeInterpreterCallCodeDeltaEvent:

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

class ResponseCodeInterpreterCallCodeDoneEvent:

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

class ResponseCodeInterpreterCallCompletedEvent:

Emitted when the code interpreter call is completed.

class ResponseCodeInterpreterCallInProgressEvent:

Emitted when a code interpreter call is in progress.

class ResponseCodeInterpreterCallInterpretingEvent:

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

class ResponseCodeInterpreterToolCall:

A tool call to run code.

class ResponseCompactionItem:

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

class ResponseCompactionItemParam:

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

class ResponseCompletedEvent:

Emitted when the model response is complete.

class ResponseComputerToolCall:

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

class ResponseComputerToolCallOutputItem:

class ResponseComputerToolCallOutputScreenshot:

A computer screenshot image used with the computer use tool.

class ResponseContainerReference:

Represents a container created with /v1/containers.

class ResponseContent: A class that can be one of several variants.union

Multi-modal input and output contents.

class ResponseContentPartAddedEvent:

Emitted when a new content part is added.

class ResponseContentPartDoneEvent:

Emitted when a content part is done.

class ResponseConversationParam:

The conversation that this response belongs to.

class ResponseCreatedEvent:

An event that is emitted when a response is created.

class ResponseCustomToolCall:

A call to a custom tool created by the model.

class ResponseCustomToolCallInputDeltaEvent:

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

class ResponseCustomToolCallInputDoneEvent:

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

class ResponseCustomToolCallItem:

A call to a custom tool created by the model.

class ResponseCustomToolCallOutput:

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

class ResponseCustomToolCallOutputItem:

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

class ResponseError:

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

class ResponseErrorEvent:

Emitted when an error occurs.

class ResponseFailedEvent:

An event that is emitted when a response fails.

class ResponseFileSearchCallCompletedEvent:

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

class ResponseFileSearchCallInProgressEvent:

Emitted when a file search call is initiated.

class ResponseFileSearchCallSearchingEvent:

Emitted when a file search is currently searching.

class ResponseFileSearchToolCall:

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

class ResponseFormatTextConfig: A class that can be one of several variants.union

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 ResponseFormatTextJsonSchemaConfig:

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

class ResponseFunctionCallArgumentsDeltaEvent:

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

class ResponseFunctionCallArgumentsDoneEvent:

Emitted when function-call arguments are finalized.

class ResponseFunctionCallOutputItem: A class that can be one of several variants.union

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

class ResponseFunctionShellCallOutputContent:

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

class ResponseFunctionShellToolCall:

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

class ResponseFunctionShellToolCallOutput:

The output of a shell tool call that was emitted.

class ResponseFunctionToolCall:

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

class ResponseFunctionToolCallItem:

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

class ResponseFunctionToolCallOutputItem:

class ResponseFunctionWebSearch:

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

class ResponseImageGenCallCompletedEvent:

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

class ResponseImageGenCallGeneratingEvent:

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

class ResponseImageGenCallInProgressEvent:

Emitted when an image generation tool call is in progress.

class ResponseImageGenCallPartialImageEvent:

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

class ResponseInProgressEvent:

Emitted when the response is in progress.

enum ResponseIncludable:

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 ResponseIncompleteEvent:

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

class ResponseInputAudio:

An audio input to the model.

class ResponseInputContent: A class that can be one of several variants.union

A text input to the model.

class ResponseInputFile:

A file input to the model.

class ResponseInputFileContent:

A file input to the model.

class ResponseInputImage:

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

class ResponseInputImageContent:

An image input to the model. Learn about image inputs

class ResponseInputItem: A class that can be one of several variants.union

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 ResponseInputMessageItem:

class ResponseInputText:

A text input to the model.

class ResponseInputTextContent:

A text input to the model.

class ResponseItem: A class that can be one of several variants.union

Content item used to generate a response.

class ResponseLocalEnvironment:

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

class ResponseMcpCallArgumentsDeltaEvent:

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

class ResponseMcpCallArgumentsDoneEvent:

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

class ResponseMcpCallCompletedEvent:

Emitted when an MCP tool call has completed successfully.

class ResponseMcpCallFailedEvent:

Emitted when an MCP tool call has failed.

class ResponseMcpCallInProgressEvent:

Emitted when an MCP tool call is in progress.

class ResponseMcpListToolsCompletedEvent:

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

class ResponseMcpListToolsFailedEvent:

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

class ResponseMcpListToolsInProgressEvent:

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

class ResponseOutputAudio:

An audio output from the model.

class ResponseOutputItem: A class that can be one of several variants.union

An output message from the model.

class ResponseOutputItemAddedEvent:

Emitted when a new output item is added.

class ResponseOutputItemDoneEvent:

Emitted when an output item is marked done.

class ResponseOutputMessage:

An output message from the model.

class ResponseOutputRefusal:

A refusal from the model.

class ResponseOutputText:

A text output from the model.

class ResponseOutputTextAnnotationAddedEvent:

Emitted when an annotation is added to output text content.

class ResponsePrompt:

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

class ResponseQueuedEvent:

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

class ResponseReasoningItem:

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 ResponseReasoningSummaryPartAddedEvent:

Emitted when a new reasoning summary part is added.

class ResponseReasoningSummaryPartDoneEvent:

Emitted when a reasoning summary part is completed.

class ResponseReasoningSummaryTextDeltaEvent:

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

class ResponseReasoningSummaryTextDoneEvent:

Emitted when a reasoning summary text is completed.

class ResponseReasoningTextDeltaEvent:

Emitted when a delta is added to a reasoning text.

class ResponseReasoningTextDoneEvent:

Emitted when a reasoning text is completed.

class ResponseRefusalDeltaEvent:

Emitted when there is a partial refusal text.

class ResponseRefusalDoneEvent:

Emitted when refusal text is finalized.

class ResponseShellCallCommandAddedEvent:

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

class ResponseShellCallCommandDeltaEvent:

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

class ResponseShellCallCommandDoneEvent:

A streaming event that indicated a shell command was completed.

class ResponseShellCallOutputContentDeltaEvent:

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

class ResponseShellCallOutputContentDoneEvent:

A streaming event that indicated shell call output was completed.

enum ResponseStatus:

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

class ResponseStreamEvent: A class that can be one of several variants.union

Event emitted while a response is streamed.

class ResponseTextConfig:

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 ResponseTextDeltaEvent:

Emitted when there is an additional text delta.

class ResponseTextDoneEvent:

Emitted when text content is finalized.

class ResponseToolSearchCall:

class ResponseToolSearchOutputItem:

class ResponseToolSearchOutputItemParam:

class ResponseUsage:

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

class ResponseWebSearchCallCompletedEvent:

Emitted when a web search call is completed.

class ResponseWebSearchCallInProgressEvent:

Emitted when a web search call is initiated.

class ResponseWebSearchCallSearchingEvent:

Emitted when a web search call is executing.

class ResponsesClientEvent:

class ResponsesServerEvent: A class that can be one of several variants.union

Server events emitted by the Responses WebSocket server.

class SkillReference:

class Tool: A class that can be one of several variants.union

A tool that can be used to generate a response.

class ToolChoiceAllowed:

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

class ToolChoiceApplyPatch:

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

class ToolChoiceCustom:

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

class ToolChoiceFunction:

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

class ToolChoiceMcp:

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

enum ToolChoiceOptions:

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 ToolChoiceShell:

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

class ToolChoiceTypes:

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

class ToolSearchTool:

Hosted or BYOT tool search configuration for deferred tools.

class WebSearchPreviewTool:

This tool searches the web for relevant results to use in a response. Learn more about the web search tool.

class WebSearchTool:

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

ResponsesInput Items

List input items

InputItemListPage responses().inputItems().list(InputItemListParamsparams = InputItemListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/responses/{response_id}/input_items

ModelsExpand Collapse

class ResponseItemList:

A list of Response items.

ResponsesInput Tokens

Get input token counts

InputTokenCountResponse responses().inputTokens().count(InputTokenCountParamsparams = InputTokenCountParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

POST/responses/input_tokens