Documentation | Responses

Responses

responses

Methods

Responses ->

OpenAIResponse

| { delta, sequence_number, type } | { sequence_number, type } | 52 more...

post/v5/responses

Responses

Response fields

OpenAIResponse

ResponseAudioDeltaEvent = { delta, sequence_number, type }

Emitted when there is a partial audio response.

ResponseAudioDoneEvent = { sequence_number, type }

Emitted when the audio response is complete.

ResponseAudioTranscriptDeltaEvent = { delta, sequence_number, type }

Emitted when there is a partial transcript of audio.

ResponseAudioTranscriptDoneEvent = { sequence_number, type }

Emitted when the full audio transcript is completed.

ResponseCodeInterpreterCallCodeDeltaEvent = { delta, item_id, output_index, 2 more... }

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

ResponseCodeInterpreterCallCodeDoneEvent = { code, item_id, output_index, 2 more... }

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

ResponseCodeInterpreterCallCompletedEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when the code interpreter call is completed.

ResponseCodeInterpreterCallInProgressEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when a code interpreter call is in progress.

ResponseCodeInterpreterCallInterpretingEvent = { item_id, output_index, sequence_number, 1 more... }

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

ResponseCompletedEvent = { response, sequence_number, type }

Emitted when the model response is complete.

ResponseContentPartAddedEvent = { content_index, item_id, output_index, 3 more... }

Emitted when a new content part is added.

ResponseContentPartDoneEvent = { content_index, item_id, output_index, 3 more... }

Emitted when a content part is done.

ResponseCreatedEvent = { response, sequence_number, type }

An event that is emitted when a response is created.

ResponseErrorEvent = { message, sequence_number, type, 2 more... }

Emitted when an error occurs.

ResponseFileSearchCallCompletedEvent = { item_id, output_index, sequence_number, 1 more... }

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

ResponseFileSearchCallInProgressEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when a file search call is initiated.

ResponseFileSearchCallSearchingEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when a file search is currently searching.

ResponseFunctionCallArgumentsDeltaEvent = { delta, item_id, output_index, 2 more... }

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

ResponseFunctionCallArgumentsDoneEvent = { arguments, item_id, name, 3 more... }

Emitted when function-call arguments are finalized.

ResponseInProgressEvent = { response, sequence_number, type }

Emitted when the response is in progress.

ResponseFailedEvent = { response, sequence_number, type }

An event that is emitted when a response fails.

ResponseIncompleteEvent = { response, sequence_number, type }

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

ResponseOutputItemAddedEvent = { item, output_index, sequence_number, 1 more... }

Emitted when a new output item is added.

ResponseOutputItemDoneEvent = { item, output_index, sequence_number, 1 more... }

Emitted when an output item is marked done.

ResponseReasoningSummaryPartAddedEvent = { item_id, output_index, part, 3 more... }

Emitted when a new reasoning summary part is added.

ResponseReasoningSummaryPartDoneEvent = { item_id, output_index, part, 3 more... }

Emitted when a reasoning summary part is completed.

ResponseReasoningSummaryTextDeltaEvent = { delta, item_id, output_index, 3 more... }

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

ResponseReasoningSummaryTextDoneEvent = { item_id, output_index, sequence_number, 3 more... }

Emitted when a reasoning summary text is completed.

ResponseReasoningTextDeltaEvent = { content_index, delta, item_id, 3 more... }

Emitted when a delta is added to a reasoning text.

ResponseReasoningTextDoneEvent = { content_index, item_id, output_index, 3 more... }

Emitted when a reasoning text is completed.

ResponseRefusalDeltaEvent = { content_index, delta, item_id, 3 more... }

Emitted when there is a partial refusal text.

ResponseRefusalDoneEvent = { content_index, item_id, output_index, 3 more... }

Emitted when refusal text is finalized.

ResponseTextDeltaEvent = { content_index, delta, item_id, 4 more... }

Emitted when there is an additional text delta.

ResponseTextDoneEvent = { content_index, item_id, logprobs, 4 more... }

Emitted when text content is finalized.

ResponseWebSearchCallCompletedEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when a web search call is completed.

ResponseWebSearchCallInProgressEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when a web search call is initiated.

ResponseWebSearchCallSearchingEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when a web search call is executing.

ResponseImageGenCallCompletedEvent = { item_id, output_index, sequence_number, 1 more... }

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

ResponseImageGenCallGeneratingEvent = { item_id, output_index, sequence_number, 1 more... }

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

ResponseImageGenCallInProgressEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when an image generation tool call is in progress.

ResponseImageGenCallPartialImageEvent = { item_id, output_index, partial_image_b64, 3 more... }

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

ResponseMcpCallArgumentsDeltaEvent = { delta, item_id, output_index, 2 more... }

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

ResponseMcpCallArgumentsDoneEvent = { arguments, item_id, output_index, 2 more... }

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

ResponseMcpCallCompletedEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when an MCP tool call has completed successfully.

ResponseMcpCallFailedEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when an MCP tool call has failed.

ResponseMcpCallInProgressEvent = { item_id, output_index, sequence_number, 1 more... }

Emitted when an MCP tool call is in progress.

ResponseMcpListToolsCompletedEvent = { item_id, output_index, sequence_number, 1 more... }

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

ResponseMcpListToolsFailedEvent = { item_id, output_index, sequence_number, 1 more... }

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

ResponseMcpListToolsInProgressEvent = { item_id, output_index, sequence_number, 1 more... }

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

ResponseOutputTextAnnotationAddedEvent = { annotation, annotation_index, content_index, 4 more... }

Emitted when an annotation is added to output text content.

ResponseQueuedEvent = { response, sequence_number, type }

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

ResponseCustomToolCallInputDeltaEvent = { delta, item_id, output_index, 2 more... }

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

ResponseCustomToolCallInputDoneEvent = { input, item_id, output_index, 2 more... }

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

GenericResponseEvent = { type }

Request example

curl https://api.egp.scale.com/v5/responses \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{
          "input": "string",
          "model": "model"
        }'

200Example

{
  "id": "id",
  "created_at": 0,
  "model": "gpt-5.2",
  "object": "response",
  "output": [
    {
      "id": "id",
      "content": [
        {
          "annotations": [
            {
              "file_id": "file_id",
              "filename": "filename",
              "index": 0,
              "type": "file_citation"
            }
          ],
          "text": "text",
          "type": "output_text",
          "logprobs": [
            {
              "token": "token",
              "bytes": [
                0
              ],
              "logprob": 0,
              "top_logprobs": [
                {
                  "token": "token",
                  "bytes": [
                    0
                  ],
                  "logprob": 0
                }
              ]
            }
          ]
        }
      ],
      "role": "assistant",
      "status": "in_progress",
      "type": "message",
      "phase": "commentary"
    }
  ],
  "parallel_tool_calls": true,
  "tool_choice": "none",
  "tools": [
    {
      "name": "name",
      "type": "function",
      "description": "description",
      "parameters": {
        "foo": "bar"
      },
      "strict": true
    }
  ],
  "background": true,
  "completed_at": 0,
  "conversation": {
    "id": "id"
  },
  "error": {
    "code": "server_error",
    "message": "message"
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  },
  "instructions": "string",
  "max_output_tokens": 0,
  "max_tool_calls": 0,
  "metadata": {
    "foo": "string"
  },
  "previous_response_id": "previous_response_id",
  "prompt": {
    "id": "id",
    "variables": {
      "foo": "string"
    },
    "version": "version"
  },
  "prompt_cache_key": "prompt_cache_key",
  "prompt_cache_retention": "in-memory",
  "reasoning": {
    "effort": "none",
    "generate_summary": "auto",
    "summary": "auto"
  },
  "safety_identifier": "safety_identifier",
  "service_tier": "auto",
  "status": "completed",
  "temperature": 0,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "top_logprobs": 0,
  "top_p": 0,
  "truncation": "auto",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "user": "user"
}

Domain types

ApplyPatchCall = { call_id, operation, status, 2 more... }

A tool call representing a request to create, delete, or update files using diff patches.

ApplyPatchCallOutput = { call_id, status, type, 2 more... }

The streamed output emitted by an apply patch tool call.

ApplyPatchTool = { type }

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

ComputerTool = { display_height, display_width, environment, 1 more... }

A tool that controls a virtual computer.

Learn more about the computer tool.

ContainerNetworkPolicyAllowlist = { allowed_domains, type, domain_secrets }

ContainerNetworkPolicyDisabled = { type }

ContainerReference = { container_id, type }

ContainerReferenceParam = { container_id, type }

Conversation = { id }

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

CustomTool = { name, type, description, 1 more... }

A custom tool that processes input using a specified format.

Learn more about custom tools

EasyInputMessage = { content, role, phase, 1 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.

FileSearchTool = { type, vector_store_ids, filters, 2 more... }

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

FunctionShellTool = { type, environment }

A tool that allows the model to execute shell commands.

FunctionTool = { name, type, description, 2 more... }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

IncompleteDetails = { reason }

Details about why the response is incomplete.

LocalEnvironment = { type, skills }

LocalEnvironmentParam = { type, skills }

McpApprovalRequest = { id, arguments, name, 2 more... }

A request for human approval of a tool invocation.

OpenAIResponse = { id, created_at, model, 29 more... }

OpenAIResponseCodeInterpreterToolCall = { id, container_id, status, 3 more... }

A tool call to run code.

OpenAIResponseComputerToolCall = { id, action, call_id, 3 more... }

A tool call to a computer use tool.

See the computer use guide for more information.

OpenAIResponseCustomToolCall = { call_id, input, name, 2 more... }

A call to a custom tool created by the model.

OpenAIResponseCustomToolCallOutput = { call_id, output, type, 1 more... }

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

OpenAIResponseError = { code, message }

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

OpenAIResponseFileSearchToolCall = { id, queries, status, 2 more... }

The results of a file search tool call.

See the file search guide for more information.

OpenAIResponseFunctionToolCall = { arguments, call_id, name, 3 more... }

A tool call to run a function.

See the function calling guide for more information.

OpenAIResponseFunctionWebSearch = { id, action, status, 1 more... }

The results of a web search tool call.

See the web search guide for more information.

OpenAIResponseInputFile = { type, file_data, file_id, 2 more... }

A file input to the model.

OpenAIResponseInputFileParam = { type, file_data, file_id, 2 more... }

A file input to the model.

OpenAIResponseInputImage = { detail, type, file_id, 1 more... }

An image input to the model.

Learn about image inputs.

OpenAIResponseInputImageParam = { detail, type, file_id, 1 more... }

An image input to the model.

Learn about image inputs.

OpenAIResponseInputText = { text, type }

A text input to the model.

OpenAIResponseInputTextParam = { text, type }

A text input to the model.

OpenAIResponseOutputMessage = { id, content, role, 3 more... }

An output message from the model.

OpenAIResponseOutputRefusal = { refusal, type }

A refusal from the model.

OpenAIResponseOutputText = { annotations, text, type, 1 more... }

A text output from the model.

OpenAIResponsePrompt = { id, variables, version }

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

OpenAIResponseReasoningItem = { id, summary, type, 3 more... }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

OpenAIResponseTextConfig = { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

OpenAIResponseUsage = { 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.

OpenAITypesResponsesResponseInputItemComputerCallOutput = { call_id, output, type, 3 more... }

The output of a computer tool call.

OpenAITypesResponsesResponseInputItemFunctionCallOutput = { call_id, output, type, 2 more... }

The output of a function tool call.

OpenAITypesResponsesResponseInputItemImageGenerationCall = { id, status, type, 1 more... }

An image generation request made by the model.

OpenAITypesResponsesResponseInputItemItemReference = { id, type }

An internal identifier for an item to reference.

OpenAITypesResponsesResponseInputItemLocalShellCall = { id, action, call_id, 2 more... }

A tool call to run a command on the local shell.

OpenAITypesResponsesResponseInputItemLocalShellCallOutput = { id, output, type, 1 more... }

The output of a local shell tool call.

OpenAITypesResponsesResponseInputItemMcpApprovalResponse = { approval_request_id, approve, type, 2 more... }

A response to an MCP approval request.

OpenAITypesResponsesResponseInputItemMcpCall = { id, arguments, name, 6 more... }

An invocation of a tool on an MCP server.

OpenAITypesResponsesResponseInputItemMcpListTools = { id, server_label, tools, 2 more... }

A list of tools available on an MCP server.

OpenAITypesResponsesResponseInputItemMessage = { content, role, status, 1 more... }

OpenAITypesResponsesResponseOutputItemImageGenerationCall = { id, status, type, 1 more... }

An image generation request made by the model.

OpenAITypesResponsesResponseOutputItemLocalShellCall = { id, action, call_id, 2 more... }

A tool call to run a command on the local shell.

OpenAITypesResponsesResponseOutputItemMcpCall = { id, arguments, name, 6 more... }

An invocation of a tool on an MCP server.

OpenAITypesResponsesResponseOutputItemMcpListTools = { id, server_label, tools, 2 more... }

A list of tools available on an MCP server.

PartReasoningText = { text, type }

Reasoning text from the model.

Reasoning = { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

ResponseApplyPatchToolCall = { id, call_id, operation, 3 more... }

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

ResponseApplyPatchToolCallOutput = { id, call_id, status, 3 more... }

The output emitted by an apply patch tool call.

ResponseCompactionItem = { id, encrypted_content, type, 1 more... }

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

ResponseCompactionItemParam = { encrypted_content, type, id }

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

ResponseComputerToolCallOutputScreenshot = { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

ResponseCreateResponse =

OpenAIResponse

| { delta, sequence_number, type } | { sequence_number, type } | 52 more...

Emitted when there is a partial audio response.

ResponseFunctionShellToolCall = { id, action, call_id, 4 more... }

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

ResponseFunctionShellToolCallOutput = { id, call_id, output, 4 more... }

The output of a shell tool call that was emitted.

ShellCall = { action, call_id, type, 3 more... }

A tool representing a request to execute one or more shell commands.

ShellCallOutput = { call_id, output, type, 3 more... }

The streamed output items emitted by a shell tool call.

ToolChoiceAllowed = { mode, tools, type }

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

ToolChoiceApplyPatch = { type }

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

ToolChoiceCustom = { name, type }

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

ToolChoiceFunction = { name, type }

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

ToolChoiceMcp = { server_label, type, name }

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

ToolChoiceShell = { type }

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

ToolChoiceTypes = { type }

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

WebSearchPreviewTool = { type, 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.

WebSearchTool = { type, filters, search_context_size, 1 more... }

Search the Internet for sources related to the prompt.

Learn more about the web search tool.