Good thing I said “next to come” and not “soon to come…”
Responses API - Request shape
In sync with OpenAPI specification Jan 9 2025 - Python v2.15.0
POST https://api.openai.com/v1/responses
Parameters (JSON body):
model: string # required [model ID]
input: string | array # required [text, or a list of input items]
├▸ (string): string # [equivalent to a single user text message]
└▸ (array): InputItem[] # [multi-part / multi-turn inputs]
├▸ message (EasyInputMessage): object
│ ├▸ type: "message" # required
│ ├▸ role: "user" | "assistant" | "system" | "developer" # required
│ └▸ content: string | InputContent[] # required
│ ├▸ (string): string # [plain text]
│ └▸ (array): InputContent[]
│ ├▸ input_text: object
│ │ ├▸ type: "input_text" # required
│ │ └▸ text: string # required
│ ├▸ input_image: object
│ │ ├▸ type: "input_image" # required
│ │ ├▸ detail: "low" | "high" | "auto" # required (default: auto)
│ │ ├▸ image_url: string | null # optional [URL or data URL (base64)]
│ │ └▸ file_id: string | null # optional [uploaded file ID]
│ └▸ input_file: object
│ ├▸ type: "input_file" # required
│ ├▸ file_id: string | null # optional
│ ├▸ filename: string # optional
│ ├▸ file_url: string # optional
│ └▸ file_data: string # optional [file content (encoded)]
├▸ item (Item): object # [conversation-state items; may include prior outputs/tool results]
│ └▸ type: (discriminator; varies) # required
│ ├▸ message (InputMessage): object
│ │ ├▸ type: "message" # required
│ │ ├▸ role: "user" | "system" | "developer" # required
│ │ └▸ content: InputContent[] # required (same InputContent shapes as above)
│ ├▸ item_reference: object
│ │ ├▸ type: "item_reference" | null # optional (default: item_reference)
│ │ └▸ id: string # required
│ ├▸ (output shapes that can appear in conversation state)
│ │ ├▸ output_message (OutputMessage): object
│ │ │ ├▸ type: "message" # required
│ │ │ ├▸ role: "assistant" # required
│ │ │ ├▸ id: string # required
│ │ │ ├▸ status: "in_progress" | "completed" | "incomplete" # required
│ │ │ └▸ content: OutputMessageContent[]
│ │ │ ├▸ output_text: object
│ │ │ │ ├▸ type: "output_text" # required
│ │ │ │ ├▸ text: string # required
│ │ │ │ ├▸ annotations: Annotation[] # required
│ │ │ │ └▸ logprobs: LogProb[] # optional (only if included via include)
│ │ │ └▸ refusal: object
│ │ │ ├▸ type: "refusal" # required
│ │ │ └▸ refusal: string # required
│ │ ├▸ file_search_call (FileSearchToolCall): object
│ │ │ ├▸ type: "file_search_call" # required
│ │ │ ├▸ id: string # required
│ │ │ ├▸ status: "in_progress" | "searching" | "completed" | "incomplete" | "failed" # required
│ │ │ ├▸ queries: string[] # required
│ │ │ └▸ results: array | null # optional (only if included via include)
│ │ ├▸ web_search_call (WebSearchToolCall): object
│ │ │ ├▸ type: "web_search_call" # required
│ │ │ ├▸ id: string # required
│ │ │ ├▸ status: "in_progress" | "searching" | "completed" | "failed" # required
│ │ │ └▸ action: object # required [search/open_page/find]
│ │ ├▸ computer_call (ComputerToolCall): object
│ │ │ ├▸ type: "computer_call" # required
│ │ │ ├▸ id: string # required
│ │ │ ├▸ call_id: string # required
│ │ │ ├▸ action: object # required [click/double_click/drag/keypress/move/screenshot/scroll/type/wait]
│ │ │ ├▸ pending_safety_checks: ComputerCallSafetyCheckParam[] # required
│ │ │ └▸ status: "in_progress" | "completed" | "incomplete" # required
│ │ ├▸ function_call (FunctionToolCall): object
│ │ │ ├▸ type: "function_call" # required
│ │ │ ├▸ id: string # required
│ │ │ ├▸ call_id: string # required
│ │ │ ├▸ name: string # required
│ │ │ ├▸ arguments: string # required [JSON string]
│ │ │ └▸ status: "in_progress" | "completed" | "incomplete" # required
│ │ ├▸ function_call_output: object
│ │ │ ├▸ type: "function_call_output" # required
│ │ │ ├▸ call_id: string # required
│ │ │ ├▸ output: string | array # required [JSON string, or content list]
│ │ │ └▸ status: "in_progress" | "completed" | "incomplete" | null # optional
│ │ ├▸ reasoning (ReasoningItem): object
│ │ │ ├▸ type: "reasoning" # required
│ │ │ ├▸ id: string # required
│ │ │ ├▸ encrypted_content: string | null # optional (only if included via include)
│ │ │ ├▸ summary: Summary[] # required
│ │ │ ├▸ content: ReasoningTextContent[] # optional
│ │ │ └▸ status: "in_progress" | "completed" | "incomplete" # required
│ │ ├▸ image_generation_call (ImageGenToolCall): object
│ │ │ ├▸ type: "image_generation_call" # required
│ │ │ ├▸ id: string # required
│ │ │ ├▸ status: "in_progress" | "completed" | "generating" | "failed" # required
│ │ │ └▸ result: string | null # required [base64 image]
│ │ └▸ code_interpreter_call (CodeInterpreterToolCall): object
│ │ ├▸ type: "code_interpreter_call" # required
│ │ ├▸ id: string # required
│ │ ├▸ status: "in_progress" | "completed" | "incomplete" | "interpreting" | "failed" # required
│ │ ├▸ container_id: string # required
│ │ ├▸ code: string | null # required
│ │ └▸ outputs: array | null # optional (only if included via include)
└▸ item_reference: object
├▸ type: "item_reference" | null # optional (default: item_reference)
└▸ id: string # required [ID of an item to reference]
instructions: string | null # optional [system/developer message inserted into context]
previous_response_id: string | null # optional [multi-turn linkage; cannot be used with conversation]
conversation: string | object | null # optional [conversation container]
├▸ (string): string # [conversation ID]
└▸ (object): object
└▸ id: string # required
metadata: object | null # optional [up to 16 string→string pairs]
temperature: number | null # optional (default: 1) [0..2]
top_p: number | null # optional (default: 1) [0..1]
top_logprobs: integer | null # optional [0..20]
user: string # optional (deprecated)
safety_identifier: string # optional
prompt_cache_key: string # optional
service_tier: "auto" | "default" | "flex" | "scale" | "priority" | null # optional (default: auto)
prompt_cache_retention: "in-memory" | "24h" | null # optional
reasoning: object | null # optional [reasoning configuration]
├▸ effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | null # optional (default: medium)
├▸ summary: "auto" | "concise" | "detailed" | null # optional
└▸ generate_summary: "auto" | "concise" | "detailed" | null # optional (deprecated)
background: boolean | null # optional (default: false)
max_output_tokens: integer | null # optional
max_tool_calls: integer | null # optional
text: object # optional [text output configuration]
├▸ format: object # optional (default: {"type":"text"})
│ ├▸ text: object
│ │ └▸ type: "text" # required
│ ├▸ json_schema: object # [Structured Outputs]
│ │ ├▸ type: "json_schema" # required
│ │ ├▸ name: string # required
│ │ ├▸ schema: object # required [JSON Schema]
│ │ ├▸ description: string # optional
│ │ └▸ strict: boolean | null # optional (default: false)
│ └▸ json_object: object # [older JSON mode]
│ └▸ type: "json_object" # required
└▸ verbosity: "low" | "medium" | "high" | null # optional (default: medium)
tools: Tool[] # optional [tools the model may call]
├▸ function: object
│ ├▸ type: "function" # required
│ ├▸ name: string # required
│ ├▸ description: string | null # optional
│ ├▸ parameters: object | null # required [JSON Schema]
│ └▸ strict: boolean | null # required
├▸ file_search: object
│ ├▸ type: "file_search" # required
│ ├▸ vector_store_ids: string[] # required
│ ├▸ max_num_results: integer # optional [1..50]
│ ├▸ ranking_options: object # optional
│ │ ├▸ ranker: "auto" | "default-2024-11-15" # optional
│ │ ├▸ score_threshold: number # optional [0..1]
│ │ └▸ hybrid_search: object # optional
│ │ ├▸ embedding_weight: number # required
│ │ └▸ text_weight: number # required
│ └▸ filters: object | null # optional
│ ├▸ ComparisonFilter: object
│ │ ├▸ type: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" # required
│ │ ├▸ key: string # required
│ │ └▸ value: string | number | boolean | array # required
│ └▸ CompoundFilter: object
│ ├▸ type: "and" | "or" # required
│ └▸ filters: array # required
├▸ computer_use_preview: object
│ ├▸ type: "computer_use_preview" # required
│ ├▸ environment: "windows" | "mac" | "linux" | "ubuntu" | "browser" # required
│ ├▸ display_width: integer # required
│ └▸ display_height: integer # required
├▸ web_search: object
│ ├▸ type: "web_search" | "web_search_2025_08_26" # required
│ ├▸ filters: object | null # optional
│ │ └▸ allowed_domains: string[] | null # optional
│ ├▸ user_location: object | null # optional
│ │ ├▸ type: "approximate" # required (default: approximate)
│ │ ├▸ country: string | null # optional
│ │ ├▸ region: string | null # optional
│ │ ├▸ city: string | null # optional
│ │ └▸ timezone: string | null # optional
│ └▸ search_context_size: "low" | "medium" | "high" # required (default: medium)
├▸ mcp: object
│ ├▸ type: "mcp" # required
│ ├▸ server_label: string # required
│ ├▸ server_url: string # optional
│ ├▸ connector_id: enum # optional
│ ├▸ authorization: string # optional
│ ├▸ server_description: string # optional
│ ├▸ headers: object | null # optional
│ ├▸ allowed_tools: string[] | object | null # optional
│ │ ├▸ (array): string[] # [allowed tool names]
│ │ └▸ (filter object): object
│ │ ├▸ tool_names: string[] # optional
│ │ └▸ read_only: boolean # optional
│ └▸ require_approval: "always" | "never" | object | null # optional (default: always)
├▸ code_interpreter: object
│ ├▸ type: "code_interpreter" # required
│ └▸ container: string | object # required
│ ├▸ (string): string # [container ID]
│ └▸ (auto object): object
│ ├▸ type: "auto" # required
│ ├▸ file_ids: string[] # optional
│ └▸ memory_limit: "1g" | "4g" | "16g" | "64g" | null # optional
├▸ image_generation: object
│ ├▸ type: "image_generation" # required
│ ├▸ model: string # optional (default: gpt-image-1)
│ ├▸ quality: "low" | "medium" | "high" | "auto" # optional (default: auto)
│ ├▸ size: "1024x1024" | "1024x1536" | "1536x1024" | "auto" # optional (default: auto)
│ ├▸ output_format: "png" | "webp" | "jpeg" # optional (default: png)
│ ├▸ output_compression: integer # optional (default: 100) [0..100]
│ ├▸ moderation: "auto" | "low" # optional (default: auto)
│ ├▸ background: "transparent" | "opaque" | "auto" # optional (default: auto)
│ ├▸ input_fidelity: "high" | "low" | null # optional
│ ├▸ input_image_mask: object # optional
│ │ ├▸ image_url: string # optional
│ │ └▸ file_id: string # optional
│ └▸ partial_images: integer # optional (default: 0) [0..3]
├▸ local_shell: object
│ └▸ type: "local_shell" # required
├▸ shell: object
│ └▸ type: "shell" # required
├▸ custom: object
│ ├▸ type: "custom" # required
│ ├▸ name: string # required
│ ├▸ description: string # optional
│ └▸ format: object # optional
│ ├▸ text: object
│ │ └▸ type: "text" # required
│ └▸ grammar: object
│ ├▸ type: "grammar" # required
│ ├▸ syntax: "lark" | "regex" # required
│ └▸ definition: string # required
├▸ web_search_preview: object
│ ├▸ type: "web_search_preview" | "web_search_preview_2025_03_11" # required
│ ├▸ user_location: object | null # optional
│ │ ├▸ type: "approximate" # required (default: approximate)
│ │ ├▸ country: string | null # optional
│ │ ├▸ region: string | null # optional
│ │ ├▸ city: string | null # optional
│ │ └▸ timezone: string | null # optional
│ └▸ search_context_size: "low" | "medium" | "high" # required (default: medium)
└▸ apply_patch: object
└▸ type: "apply_patch" # required
tool_choice: "none" | "auto" | "required" | object # optional
├▸ (mode string): "none" | "auto" | "required"
└▸ (object): object
├▸ allowed_tools: object
│ ├▸ type: "allowed_tools" # required
│ ├▸ mode: "auto" | "required" # required
│ └▸ tools: array # required
├▸ hosted_tool: object
│ └▸ type: "file_search" | "web_search_preview" | "web_search_preview_2025_03_11" | "computer_use_preview" | "image_generation" | "code_interpreter" # required
├▸ function: object
│ ├▸ type: "function" # required
│ └▸ name: string # required
├▸ mcp: object
│ ├▸ type: "mcp" # required
│ ├▸ server_label: string # required
│ └▸ name: string | null # required
├▸ custom: object
│ ├▸ type: "custom" # required
│ └▸ name: string # required
├▸ apply_patch: object
│ └▸ type: "apply_patch" # required
└▸ shell: object
└▸ type: "shell" # required
prompt: object | null # optional [prompt template reference]
├▸ id: string # required
├▸ version: string | null # optional
└▸ variables: object | null # optional [map of substitutions]
└▸ <var_name>: string | InputContent # optional
├▸ (string): string
├▸ input_text: object
│ ├▸ type: "input_text" # required
│ └▸ text: string # required
├▸ input_image: object
│ ├▸ type: "input_image" # required
│ ├▸ detail: "low" | "high" | "auto" # required (default: auto)
│ ├▸ image_url: string | null # optional
│ └▸ file_id: string | null # optional
└▸ input_file: object
├▸ type: "input_file" # required
├▸ file_id: string | null # optional
├▸ filename: string # optional
├▸ file_url: string # optional
└▸ file_data: string # optional
truncation: "auto" | "disabled" | null # optional (default: disabled)
include: string[] | null # optional
├▸ "file_search_call.results"
├▸ "web_search_call.results"
├▸ "web_search_call.action.sources"
├▸ "message.input_image.image_url"
├▸ "computer_call_output.output.image_url"
├▸ "code_interpreter_call.outputs"
├▸ "reasoning.encrypted_content"
└▸ "message.output_text.logprobs"
parallel_tool_calls: boolean | null # optional (default: true)
store: boolean | null # optional (default: true)
stream: boolean | null # optional (default: false)
stream_options: object | null # optional
└▸ include_obfuscation: boolean # optional
Response object - non streaming
POST https://api.openai.com/v1/responses (200 OK)
Content-Type: application/json
Response (JSON):
id: string # required
object: "response" # required
status: "completed" | "failed" | "in_progress" | "cancelled" | "queued" | "incomplete" # required
created_at: number # required [unix seconds]
completed_at: number | null # optional [unix seconds; typically present when status="completed"]
error: object | null # required
├▸ (object):
│ ├▸ code: string # required
│ │ ├▸ "server_error"
│ │ ├▸ "rate_limit_exceeded"
│ │ ├▸ "invalid_prompt"
│ │ ├▸ "vector_store_timeout"
│ │ ├▸ "invalid_image"
│ │ ├▸ "invalid_image_format"
│ │ ├▸ "invalid_base64_image"
│ │ ├▸ "invalid_image_url"
│ │ ├▸ "image_too_large"
│ │ ├▸ "image_too_small"
│ │ ├▸ "image_parse_error"
│ │ ├▸ "image_content_policy_violation"
│ │ ├▸ "invalid_image_mode"
│ │ ├▸ "image_file_too_large"
│ │ ├▸ "unsupported_image_media_type"
│ │ ├▸ "empty_image_file"
│ │ ├▸ "failed_to_download_image"
│ │ └▸ "image_file_not_found"
│ └▸ message: string # required
└▸ (null): null
incomplete_details: object | null # required
├▸ (object):
│ └▸ reason: "max_output_tokens" | "content_filter" # optional
└▸ (null): null
output: OutputItem[] # required
└▸ (each OutputItem): object # required [iterate this array; branch on item.type]
├▸ type: string # required [discriminator]
│ ├▸ "message"
│ ├▸ "function_call"
│ ├▸ "function_call_output"
│ ├▸ "computer_call"
│ ├▸ "computer_call_output"
│ ├▸ "local_shell_call"
│ ├▸ "local_shell_call_output"
│ ├▸ "shell_call"
│ ├▸ "shell_call_output"
│ ├▸ "apply_patch_call"
│ ├▸ "apply_patch_call_output"
│ ├▸ "reasoning"
│ ├▸ "compaction"
│ ├▸ "image_generation_call"
│ ├▸ "mcp_call"
│ ├▸ "mcp_list_tools"
│ ├▸ "mcp_approval_request"
│ ├▸ "mcp_approval_response"
│ ├▸ "custom_tool_call"
│ ├▸ "custom_tool_call_output"
│ ├▸ "file_search_call"
│ ├▸ "web_search_call"
│ └▸ "code_interpreter_call"
├▸ (when type="message"): object
│ ├▸ id: string # required
│ ├▸ role: "assistant" # required
│ ├▸ status: "in_progress" | "completed" | "incomplete" # required
│ └▸ content: OutputMessageContent[] # required
│ └▸ (each OutputMessageContent): object # required [branch on content.type]
│ ├▸ type: "output_text" | "refusal" # required
│ ├▸ (when type="output_text"): object
│ │ ├▸ text: string # required
│ │ ├▸ annotations: Annotation[] # required
│ │ │ └▸ (each Annotation): object # required [branch on annotation.type]
│ │ │ ├▸ type: "file_citation" | "url_citation" | "container_file_citation" | "file_path" # required
│ │ │ ├▸ (when type="file_citation"): object
│ │ │ │ ├▸ file_id: string # required
│ │ │ │ ├▸ index: integer # required
│ │ │ │ └▸ filename: string # required
│ │ │ ├▸ (when type="url_citation"): object
│ │ │ │ ├▸ url: string # required
│ │ │ │ ├▸ start_index: integer # required
│ │ │ │ ├▸ end_index: integer # required
│ │ │ │ └▸ title: string # required
│ │ │ ├▸ (when type="container_file_citation"): object
│ │ │ │ ├▸ container_id: string # required
│ │ │ │ ├▸ file_id: string # required
│ │ │ │ ├▸ start_index: integer # required
│ │ │ │ ├▸ end_index: integer # required
│ │ │ │ └▸ filename: string # required
│ │ │ └▸ (when type="file_path"): object
│ │ │ ├▸ file_id: string # required
│ │ │ └▸ index: integer # required
│ │ └▸ logprobs: LogProb[] # optional [only present when requested via include]
│ │ └▸ (each LogProb): object
│ │ ├▸ token: string # required
│ │ ├▸ logprob: number # required
│ │ ├▸ bytes: integer[] # required
│ │ └▸ top_logprobs: TopLogProb[] # required
│ │ └▸ (each TopLogProb): object
│ │ ├▸ token: string # required
│ │ ├▸ logprob: number # required
│ │ └▸ bytes: integer[] # required
│ └▸ (when type="refusal"): object
│ └▸ refusal: string # required
├▸ (when type="function_call"): object
│ ├▸ id: string # optional
│ ├▸ call_id: string # required
│ ├▸ name: string # required
│ ├▸ arguments: string # required [JSON string]
│ └▸ status: "in_progress" | "completed" | "incomplete" # optional
├▸ (when type="function_call_output"): object
│ ├▸ id: string | null # optional
│ ├▸ call_id: string # required
│ ├▸ output: string | FunctionAndCustomToolCallOutput[] # required
│ │ ├▸ (string): string # [JSON string]
│ │ └▸ (array): see ## FunctionAndCustomToolCallOutput
│ └▸ status: "in_progress" | "completed" | "incomplete" | null # optional
├▸ (when type="computer_call"): object
│ ├▸ id: string # required
│ ├▸ call_id: string # required
│ ├▸ status: "in_progress" | "completed" | "incomplete" # required
│ ├▸ pending_safety_checks: ComputerCallSafetyCheck[] # required
│ │ └▸ (each ComputerCallSafetyCheck): object
│ │ ├▸ id: string # required
│ │ ├▸ code: string | null # optional
│ │ └▸ message: string | null # optional
│ └▸ action: ComputerAction # required
│ └▸ type: string # required [discriminator]
│ ├▸ "click"
│ │ ├▸ button: "left" | "right" | "wheel" | "back" | "forward" # required
│ │ ├▸ x: integer # required
│ │ └▸ y: integer # required
│ ├▸ "double_click"
│ │ ├▸ x: integer # required
│ │ └▸ y: integer # required
│ ├▸ "drag"
│ │ └▸ path: DragPoint[] # required
│ │ └▸ (each DragPoint): object
│ │ ├▸ x: integer # required
│ │ └▸ y: integer # required
│ ├▸ "keypress"
│ │ └▸ keys: string[] # required
│ ├▸ "move"
│ │ ├▸ x: integer # required
│ │ └▸ y: integer # required
│ ├▸ "screenshot"
│ ├▸ "scroll"
│ │ ├▸ x: integer # required
│ │ ├▸ y: integer # required
│ │ ├▸ scroll_x: integer # required
│ │ └▸ scroll_y: integer # required
│ ├▸ "type"
│ │ └▸ text: string # required
│ └▸ "wait"
├▸ (when type="computer_call_output"): object
│ ├▸ id: string | null # optional
│ ├▸ call_id: string # required
│ ├▸ output: object # required
│ │ ├▸ type: "computer_screenshot" # required
│ │ ├▸ image_url: string # required
│ │ └▸ file_id: string # required
│ ├▸ acknowledged_safety_checks: ComputerCallSafetyCheck[] | null # optional
│ └▸ status: "in_progress" | "completed" | "incomplete" | null # optional
├▸ (when type="local_shell_call"): object
│ ├▸ id: string # required
│ ├▸ call_id: string # required
│ ├▸ status: "in_progress" | "completed" | "incomplete" # required
│ └▸ action: object # required
│ ├▸ type: "exec" # required
│ ├▸ command: string[] # required
│ ├▸ timeout_ms: integer | null # optional
│ ├▸ working_directory: string | null # optional
│ ├▸ env: object # required [string->string map]
│ └▸ user: string | null # optional
├▸ (when type="local_shell_call_output"): object
│ ├▸ id: string # required
│ ├▸ call_id: string # required
│ ├▸ output: string # required [JSON string]
│ └▸ status: "in_progress" | "completed" | "incomplete" | null # optional
├▸ (when type="shell_call"): object
│ ├▸ id: string | null # optional
│ ├▸ call_id: string # required
│ ├▸ action: object # required
│ │ ├▸ commands: string[] # required
│ │ ├▸ timeout_ms: integer | null # optional
│ │ └▸ max_output_length: integer | null # optional
│ └▸ status: "in_progress" | "completed" | "incomplete" | null # optional
├▸ (when type="shell_call_output"): object
│ ├▸ id: string | null # optional
│ ├▸ call_id: string # required
│ ├▸ output: ShellOutputChunk[] # required
│ │ └▸ (each ShellOutputChunk): object # required
│ │ ├▸ stdout: string # required
│ │ ├▸ stderr: string # required
│ │ └▸ outcome: object # required [branch on outcome.type]
│ │ ├▸ type: "timeout" | "exit" # required
│ │ ├▸ (when type="timeout"): object
│ │ └▸ (when type="exit"): object
│ │ └▸ exit_code: integer # required
│ └▸ max_output_length: integer | null # optional
├▸ (when type="apply_patch_call"): object
│ ├▸ id: string | null # optional
│ ├▸ call_id: string # required
│ ├▸ status: "in_progress" | "completed" # required
│ └▸ operation: object # required [branch on operation.type]
│ ├▸ type: "create_file" | "delete_file" | "update_file" # required
│ ├▸ (when type="create_file"): object
│ │ ├▸ path: string # required
│ │ └▸ diff: string # required
│ ├▸ (when type="delete_file"): object
│ │ └▸ path: string # required
│ └▸ (when type="update_file"): object
│ ├▸ path: string # required
│ └▸ diff: string # required
├▸ (when type="apply_patch_call_output"): object
│ ├▸ id: string | null # optional
│ ├▸ call_id: string # required
│ ├▸ status: "completed" | "failed" # required
│ └▸ output: string | null # optional
├▸ (when type="reasoning"): object
│ ├▸ id: string # required
│ ├▸ status: "in_progress" | "completed" | "incomplete" # optional
│ ├▸ encrypted_content: string | null # optional
│ ├▸ summary: object[] # required
│ │ └▸ (each summary item): object
│ │ ├▸ type: "summary_text" # required
│ │ └▸ text: string # required
│ └▸ content: object[] # optional
│ └▸ (each content item): object
│ ├▸ type: "reasoning_text" # required
│ └▸ text: string # required
├▸ (when type="compaction"): object
│ ├▸ id: string | null # optional
│ └▸ encrypted_content: string # required
├▸ (when type="image_generation_call"): object
│ ├▸ id: string # required
│ ├▸ status: "in_progress" | "completed" | "generating" | "failed" # required
│ └▸ result: string | null # required [base64 image]
├▸ (when type="mcp_call"): object
│ ├▸ id: string # required
│ ├▸ server_label: string # required
│ ├▸ name: string # required
│ ├▸ arguments: string # required [JSON string]
│ ├▸ status: "in_progress" | "completed" | "incomplete" | "calling" | "failed" # optional
│ ├▸ output: string | null # optional
│ ├▸ error: string | null # optional
│ └▸ approval_request_id: string | null # optional
├▸ (when type="mcp_list_tools"): object
│ ├▸ id: string # required
│ ├▸ server_label: string # required
│ ├▸ tools: object[] # required
│ │ └▸ (each tool): object
│ │ ├▸ name: string # required
│ │ ├▸ input_schema: object # required
│ │ ├▸ description: string | null # optional
│ │ └▸ annotations: object | null # optional
│ └▸ error: string | null # optional
├▸ (when type="mcp_approval_request"): object
│ ├▸ id: string # required
│ ├▸ server_label: string # required
│ ├▸ name: string # required
│ └▸ arguments: string # required [JSON string]
├▸ (when type="mcp_approval_response"): object
│ ├▸ id: string | null # optional
│ ├▸ request_id: string # required [present per required-list in the provided spec excerpt]
│ ├▸ approval_request_id: string # required
│ ├▸ approve: boolean # required
│ └▸ reason: string | null # optional
├▸ (when type="custom_tool_call"): object
│ ├▸ id: string # optional
│ ├▸ call_id: string # required
│ ├▸ name: string # required
│ └▸ input: string # required
├▸ (when type="custom_tool_call_output"): object
│ ├▸ id: string # required
│ ├▸ call_id: string # required
│ └▸ output: string | FunctionAndCustomToolCallOutput[] # required
│ ├▸ (string): string
│ └▸ (array): see ## FunctionAndCustomToolCallOutput
├▸ (when type="file_search_call"): object
│ ├▸ id: string # required
│ ├▸ status: "in_progress" | "searching" | "completed" | "incomplete" | "failed" # required
│ └▸ tool_payload: object # optional [tool-specific fields omitted for parsing]
├▸ (when type="web_search_call"): object
│ ├▸ id: string # required
│ ├▸ status: "in_progress" | "searching" | "completed" | "failed" # required
│ └▸ tool_payload: object # optional [tool-specific fields omitted for parsing]
└▸ (when type="code_interpreter_call"): object
├▸ id: string # required
├▸ status: "in_progress" | "completed" | "incomplete" | "interpreting" | "failed" # required
└▸ tool_payload: object # optional [tool-specific fields omitted for parsing]
usage: object # required
├▸ input_tokens: integer # required
├▸ input_tokens_details: object # required
│ └▸ cached_tokens: integer # required
├▸ output_tokens: integer # required
├▸ output_tokens_details: object # required
│ └▸ reasoning_tokens: integer # required
└▸ total_tokens: integer # required
conversation: object | null # optional
├▸ (object):
│ └▸ id: string # required
└▸ (null): null