ChatGPT · Schema
ChatGPT Response
Schema for an OpenAI Responses API response object. Represents a model-generated response including output items, tool call results, token usage, and metadata. The Responses API is OpenAI's recommended API primitive for building with their models.
AgentsAIChatGPTEmbeddingsFine-TuningGPT-4GPT-5Language ModelOpenAIRealtime
Properties
| Name | Type | Description |
|---|---|---|
| id | string | Unique identifier for the response, prefixed with 'resp_' |
| object | string | The object type, which is always 'response' |
| created_at | integer | Unix timestamp (in seconds) of when the response was created |
| model | string | The model used to generate the response |
| status | string | The status of the response generation |
| output | array | An array of content items generated by the model, including messages, function calls, tool invocations, and reasoning items |
| usage | object | Token usage statistics for the response |
| error | object | An error object if the response generation failed |
| incomplete_details | object | Details about why the response is incomplete |
| instructions | string | The system or developer instructions provided for the response |
| metadata | object | Set of key-value pairs attached to the response for storing additional information |
| temperature | number | The sampling temperature used for generation |
| top_p | number | The nucleus sampling parameter used for generation |
| max_output_tokens | integer | The maximum number of output tokens configured for the response |
| previous_response_id | string | The ID of the previous response in a multi-turn conversation |
| reasoning | object | The reasoning configuration used for o-series models |
| text | object | The text format configuration used for the response |
| tools | array | The tools available during response generation |
| truncation | string | The truncation strategy used for the model context |
| user | string | The end-user identifier |
| service_tier | string | The service tier used for processing the request |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://platform.openai.com/schemas/response.json",
"title": "ChatGPT Response",
"description": "Schema for an OpenAI Responses API response object. Represents a model-generated response including output items, tool call results, token usage, and metadata. The Responses API is OpenAI's recommended API primitive for building with their models.",
"type": "object",
"required": ["id", "object", "created_at", "model", "status", "output", "usage"],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the response, prefixed with 'resp_'",
"pattern": "^resp_"
},
"object": {
"type": "string",
"description": "The object type, which is always 'response'",
"const": "response"
},
"created_at": {
"type": "integer",
"description": "Unix timestamp (in seconds) of when the response was created",
"minimum": 0
},
"model": {
"type": "string",
"description": "The model used to generate the response",
"minLength": 1
},
"status": {
"type": "string",
"description": "The status of the response generation",
"enum": ["completed", "failed", "in_progress", "incomplete"]
},
"output": {
"type": "array",
"description": "An array of content items generated by the model, including messages, function calls, tool invocations, and reasoning items",
"items": {
"$ref": "#/$defs/OutputItem"
}
},
"usage": {
"$ref": "#/$defs/Usage",
"description": "Token usage statistics for the response"
},
"error": {
"$ref": "#/$defs/ResponseError",
"description": "An error object if the response generation failed",
"nullable": true
},
"incomplete_details": {
"type": "object",
"description": "Details about why the response is incomplete",
"nullable": true,
"properties": {
"reason": {
"type": "string",
"description": "The reason the response is incomplete",
"enum": ["max_output_tokens", "content_filter"]
}
}
},
"instructions": {
"type": "string",
"description": "The system or developer instructions provided for the response",
"nullable": true
},
"metadata": {
"type": "object",
"description": "Set of key-value pairs attached to the response for storing additional information",
"nullable": true,
"additionalProperties": {
"type": "string"
},
"maxProperties": 16
},
"temperature": {
"type": "number",
"description": "The sampling temperature used for generation",
"minimum": 0,
"maximum": 2,
"nullable": true
},
"top_p": {
"type": "number",
"description": "The nucleus sampling parameter used for generation",
"minimum": 0,
"maximum": 1,
"nullable": true
},
"max_output_tokens": {
"type": "integer",
"description": "The maximum number of output tokens configured for the response",
"nullable": true
},
"previous_response_id": {
"type": "string",
"description": "The ID of the previous response in a multi-turn conversation",
"nullable": true
},
"reasoning": {
"$ref": "#/$defs/ReasoningConfig",
"description": "The reasoning configuration used for o-series models",
"nullable": true
},
"text": {
"$ref": "#/$defs/TextConfig",
"description": "The text format configuration used for the response",
"nullable": true
},
"tools": {
"type": "array",
"description": "The tools available during response generation",
"items": {
"$ref": "#/$defs/Tool"
}
},
"truncation": {
"type": "string",
"description": "The truncation strategy used for the model context",
"enum": ["auto", "disabled"],
"nullable": true
},
"user": {
"type": "string",
"description": "The end-user identifier",
"nullable": true
},
"service_tier": {
"type": "string",
"description": "The service tier used for processing the request",
"nullable": true
}
},
"$defs": {
"OutputItem": {
"type": "object",
"description": "A single output item from the model response",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The type of output item",
"enum": [
"message",
"function_call",
"web_search_call",
"file_search_call",
"computer_call",
"code_interpreter_call",
"reasoning",
"mcp_call",
"image_generation_call",
"mcp_list_tools",
"mcp_approval_request"
]
},
"id": {
"type": "string",
"description": "The unique ID of the output item"
},
"role": {
"type": "string",
"description": "The role of the output item author",
"const": "assistant"
},
"status": {
"type": "string",
"description": "The status of the output item",
"enum": ["completed", "in_progress", "incomplete"]
},
"content": {
"type": "array",
"description": "The content of the output message (for message type items)",
"items": {
"$ref": "#/$defs/OutputContentPart"
}
},
"name": {
"type": "string",
"description": "The name of the function being called (for function_call type items)"
},
"call_id": {
"type": "string",
"description": "The unique ID of the function call"
},
"arguments": {
"type": "string",
"description": "The arguments to the function call in JSON format"
},
"summary": {
"type": "array",
"description": "A summary of reasoning performed by the model (for reasoning type items)",
"items": {
"$ref": "#/$defs/ReasoningSummary"
}
},
"action": {
"type": "object",
"description": "The computer action to perform (for computer_call type items)",
"properties": {
"type": {
"type": "string",
"description": "The type of computer action",
"enum": ["click", "double_click", "drag", "key", "move", "screenshot", "scroll", "type", "wait"]
},
"x": {
"type": "integer",
"description": "The x-coordinate for mouse actions"
},
"y": {
"type": "integer",
"description": "The y-coordinate for mouse actions"
},
"text": {
"type": "string",
"description": "The text to type"
},
"key": {
"type": "string",
"description": "The key to press"
}
}
}
}
},
"OutputContentPart": {
"type": "object",
"description": "A content part within an output message",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The type of content part",
"enum": ["output_text", "refusal"]
},
"text": {
"type": "string",
"description": "The text content of the output"
},
"refusal": {
"type": "string",
"description": "The refusal message if the model declines to respond"
},
"annotations": {
"type": "array",
"description": "Annotations on the text, such as citations from file search or web search",
"items": {
"$ref": "#/$defs/Annotation"
}
}
}
},
"Annotation": {
"type": "object",
"description": "An annotation on output text, providing citations and references",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The type of annotation",
"enum": ["url_citation", "file_citation", "file_path"]
},
"start_index": {
"type": "integer",
"description": "The start index of the annotated text span",
"minimum": 0
},
"end_index": {
"type": "integer",
"description": "The end index of the annotated text span",
"minimum": 0
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL cited (for url_citation type)"
},
"title": {
"type": "string",
"description": "The title of the cited resource"
},
"file_id": {
"type": "string",
"description": "The ID of the cited file (for file_citation and file_path types)"
},
"quote": {
"type": "string",
"description": "The relevant quote from the cited file"
}
}
},
"ReasoningSummary": {
"type": "object",
"description": "A summary text entry from the model's reasoning process",
"properties": {
"type": {
"type": "string",
"description": "The type of reasoning summary",
"const": "summary_text"
},
"text": {
"type": "string",
"description": "The summary text"
}
}
},
"Usage": {
"type": "object",
"description": "Token usage statistics for the response",
"required": ["input_tokens", "output_tokens", "total_tokens"],
"properties": {
"input_tokens": {
"type": "integer",
"description": "The number of input tokens used",
"minimum": 0
},
"input_tokens_details": {
"type": "object",
"description": "Detailed breakdown of input token usage",
"properties": {
"cached_tokens": {
"type": "integer",
"description": "Number of cached input tokens",
"minimum": 0
}
}
},
"output_tokens": {
"type": "integer",
"description": "The number of output tokens generated",
"minimum": 0
},
"output_tokens_details": {
"type": "object",
"description": "Detailed breakdown of output token usage",
"properties": {
"reasoning_tokens": {
"type": "integer",
"description": "Number of reasoning tokens generated",
"minimum": 0
}
}
},
"total_tokens": {
"type": "integer",
"description": "Total number of tokens used (input + output)",
"minimum": 0
}
}
},
"ResponseError": {
"type": "object",
"description": "Error information when a response generation fails",
"properties": {
"code": {
"type": "string",
"description": "The error code"
},
"message": {
"type": "string",
"description": "A human-readable error message"
}
}
},
"ReasoningConfig": {
"type": "object",
"description": "Configuration for reasoning models (o-series)",
"properties": {
"effort": {
"type": "string",
"description": "The level of reasoning effort",
"enum": ["low", "medium", "high"],
"default": "medium"
},
"summary": {
"type": "string",
"description": "The level of reasoning summary detail",
"enum": ["auto", "concise", "detailed"],
"nullable": true
}
}
},
"TextConfig": {
"type": "object",
"description": "Configuration for the text response format",
"properties": {
"format": {
"type": "object",
"description": "The format specification for the response text",
"properties": {
"type": {
"type": "string",
"description": "The format type",
"enum": ["text", "json_object", "json_schema"]
},
"name": {
"type": "string",
"description": "The name of the response format schema"
},
"description": {
"type": "string",
"description": "A description of the response format"
},
"schema": {
"type": "object",
"description": "The JSON schema for structured outputs"
},
"strict": {
"type": "boolean",
"description": "Whether strict schema adherence is enabled",
"default": false
}
}
}
}
},
"Tool": {
"type": "object",
"description": "A tool available for the model to use during response generation",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The type of tool",
"enum": [
"function",
"web_search_preview",
"file_search",
"code_interpreter",
"computer_use_preview",
"mcp",
"image_generation"
]
},
"name": {
"type": "string",
"description": "The name of the function (for function type tools)"
},
"description": {
"type": "string",
"description": "A description of what the function does"
},
"parameters": {
"type": "object",
"description": "The parameters the function accepts as a JSON Schema object"
},
"strict": {
"type": "boolean",
"description": "Whether strict schema adherence is enabled for function calls",
"default": false
},
"vector_store_ids": {
"type": "array",
"description": "The IDs of vector stores to search (for file_search type)",
"items": {
"type": "string"
}
},
"max_num_results": {
"type": "integer",
"description": "Maximum number of results from file search",
"minimum": 1,
"maximum": 50,
"default": 20
},
"server_label": {
"type": "string",
"description": "A label for the MCP server (for mcp type)"
},
"server_url": {
"type": "string",
"format": "uri",
"description": "The URL of the MCP server (for mcp type)"
},
"allowed_tools": {
"type": "array",
"description": "List of allowed tool names from the MCP server",
"items": {
"type": "string"
}
}
}
},
"InputItem": {
"type": "object",
"description": "An input item provided to the model as part of a conversation",
"required": ["role"],
"properties": {
"role": {
"type": "string",
"description": "The role of the input item",
"enum": ["user", "assistant", "system", "developer"]
},
"content": {
"description": "The content of the input item",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/InputContentPart"
}
}
]
},
"type": {
"type": "string",
"description": "The type of input item",
"enum": ["message", "function_call_output", "item_reference"]
},
"id": {
"type": "string",
"description": "The unique ID of the input item"
},
"call_id": {
"type": "string",
"description": "The ID of the function call this output corresponds to"
},
"output": {
"type": "string",
"description": "The output of the function call"
},
"status": {
"type": "string",
"description": "The status of the input item",
"enum": ["completed", "incomplete"]
}
}
},
"InputContentPart": {
"type": "object",
"description": "A content part within a multi-part input item",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The type of content part",
"enum": ["input_text", "input_image", "input_file"]
},
"text": {
"type": "string",
"description": "The text content (for input_text type)"
},
"image_url": {
"type": "string",
"format": "uri",
"description": "The URL of the image (for input_image type)"
},
"detail": {
"type": "string",
"description": "The detail level for image inputs",
"enum": ["auto", "low", "high"],
"default": "auto"
},
"file_id": {
"type": "string",
"description": "The ID of the uploaded file (for input_file type)"
},
"filename": {
"type": "string",
"description": "The name of the file"
}
}
}
}
}