# Agents ## Create an agent **post** `/agents` Creates a reusable agent without storing credentials. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Body Parameters - `model: string` The model to use for the agent. The requested model name is preserved. - `instructions: optional string or null` Additional instructions appended to the agent's default base instructions. Omit or set to null to add no custom instructions. - `metadata: optional map[string] or null` Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. - `multi_agent: optional MultiAgentConfigParam or null` Configuration for creating and coordinating subagents. Subagent tools are disabled by default. - `enabled: boolean` Whether subagent tools are enabled. - `max_concurrent_subagents: optional number` Maximum number of subagents that may run concurrently. Defaults to 6. - `name: optional string or null` A human-readable name for the agent. Omission or null leaves the agent unnamed. - `reasoning: optional AgentReasoningParam or null` Configuration for model reasoning. Omission uses the model's default effort. - `effort: optional "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort the model should use. Omission lets the model select it. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` Controls whether the response includes a reasoning summary. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: optional "auto" or "default" or "flex" or 3 more or null` The service tier used for model requests. Defaults to `auto`. - `"auto"` Selects the service tier automatically. - `"default"` Uses the default service tier. - `"flex"` Uses the flex service tier. - `"priority"` Uses the priority service tier. - `"fast"` Uses the fast service tier. - `"ultrafast"` Uses the ultrafast service tier. - `text: optional AgentTextParam or null` Configuration for generated text. Defaults to the `text` format and medium verbosity. - `format: optional TextFormatParam or null` The output format. Omission uses ordinary text (`{"type": "text"}`). - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. Defaults to `medium`, matching Responses. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. - `tools: optional array of PersistedAgentToolParam or null` Tools available to the agent. Defaults to an empty list. The tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `defer_loading: optional boolean` Whether this function is deferred and discovered through tool search. Defaults to `false`. - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { type, enabled }` Enables calling tools from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `enabled: optional boolean` Whether tools can be called from model-generated code. Defaults to `true`. - `Mcp object { server_label, transport, type, 5 more }` Tools provided by a remote MCP server without stored credentials. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransportParam` The credential-free transport used to connect to the MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `headers: optional map[string] or null` Non-secret HTTP headers sent to the MCP server. - `Stdio object { command, cwd, type, 2 more }` Starts an MCP server as a local process. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `args: optional array of string or null` Arguments passed to the MCP server command. - `env_vars: optional array of string or null` Environment variable names to inherit from the selected execution environment. - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `allowed_tools: optional array of string or null` The MCP tools the agent may call. All server tools are allowed when omitted. - `connection_origin: optional "service" or "environment" or null` Selects where outbound MCP HTTP connections originate. - `"service"` Uses the Managed Agents service network. - `"environment"` Uses the session's execution environment. - `credential_id: optional string or null` The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. - `request_metadata: optional map[unknown] or null` Metadata included with requests to this MCP server. - `required: optional boolean` Whether this MCP server must initialize before the first turn. Defaults to `false`. - `WebSearch object { type, allowed_domains, context_size, 2 more }` Web search. - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `allowed_domains: optional array of string or null` Domains the search may include. - `context_size: optional "low" or "medium" or "high" or null` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: optional object { city, country, region, timezone } or null` Approximate location used to localize search results. - `city: optional string or null` The city name. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. Defaults to `live`. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. - `ComputerUse object { type, include_screenshots }` Browser use in an OpenAI-hosted session. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `include_screenshots: optional boolean` Whether computer tool outputs include screenshots. Defaults to `false`. ### Returns - `Agent object { id, created_at, instructions, 10 more }` A reusable agent scoped to the caller's project. - `id: string` The ID of the reusable agent. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` The resolved configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server without stored credentials. - `allowed_tools: array of string or null` The MCP tools the agent may call, or null when all server tools are allowed. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `HTTP object { headers, server_url, type }` Connects to an MCP server over HTTP. - `headers: map[string]` Non-secret HTTP headers sent to the MCP server. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```http curl https://api.openai.com/v1/agents \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "model" }' ``` #### Response ```json { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ``` ## Delete an agent **delete** `/agents/{agent_id}` Deletes a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Path Parameters - `agent_id: string` ### Returns - `AgentDeleted object { id, deleted, object }` A deleted reusable agent. - `id: string` The ID of the deleted agent. - `deleted: boolean` Whether the agent was deleted. Always `true`. - `object: "agent.deleted"` The object type. Always `agent.deleted`. - `"agent.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/$AGENT_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.deleted" } ``` ## List agents **get** `/agents` Lists reusable agents in the current project. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Agent` The resources returned in this page, in the requested sort order. - `id: string` The ID of the reusable agent. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` The resolved configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server without stored credentials. - `allowed_tools: array of string or null` The MCP tools the agent may call, or null when all server tools are allowed. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `HTTP object { headers, server_url, type }` Connects to an MCP server over HTTP. - `headers: map[string]` Non-secret HTTP headers sent to the MCP server. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent **get** `/agents/{agent_id}` Retrieves a reusable agent by ID. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Path Parameters - `agent_id: string` ### Returns - `Agent object { id, created_at, instructions, 10 more }` A reusable agent scoped to the caller's project. - `id: string` The ID of the reusable agent. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` The resolved configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server without stored credentials. - `allowed_tools: array of string or null` The MCP tools the agent may call, or null when all server tools are allowed. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `HTTP object { headers, server_url, type }` Connects to an MCP server over HTTP. - `headers: map[string]` Non-secret HTTP headers sent to the MCP server. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```http curl https://api.openai.com/v1/agents/$AGENT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ``` ## Update an agent **post** `/agents/{agent_id}` Updates a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration). ### Path Parameters - `agent_id: string` ### Body Parameters - `instructions: optional string or null` Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `metadata: optional map[string] or null` Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. - `model: optional string` The model to use for the agent. The requested model name is preserved. - `multi_agent: optional MultiAgentConfigParam or null` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. - `max_concurrent_subagents: optional number` Maximum number of subagents that may run concurrently. Defaults to 6. - `name: optional string or null` A replacement name. Omit to leave unchanged, or pass null to clear it. - `reasoning: optional AgentReasoningParam or null` Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. - `effort: optional "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort the model should use. Omission lets the model select it. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` Controls whether the response includes a reasoning summary. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: optional "auto" or "default" or "flex" or 3 more or null` The service tier used for model requests. - `"auto"` Selects the service tier automatically. - `"default"` Uses the default service tier. - `"flex"` Uses the flex service tier. - `"priority"` Uses the priority service tier. - `"fast"` Uses the fast service tier. - `"ultrafast"` Uses the ultrafast service tier. - `text: optional AgentTextParam or null` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format. Omission uses ordinary text (`{"type": "text"}`). - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. Defaults to `medium`, matching Responses. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. - `tools: optional array of PersistedAgentToolParam or null` Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `defer_loading: optional boolean` Whether this function is deferred and discovered through tool search. Defaults to `false`. - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { type, enabled }` Enables calling tools from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `enabled: optional boolean` Whether tools can be called from model-generated code. Defaults to `true`. - `Mcp object { server_label, transport, type, 5 more }` Tools provided by a remote MCP server without stored credentials. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransportParam` The credential-free transport used to connect to the MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `headers: optional map[string] or null` Non-secret HTTP headers sent to the MCP server. - `Stdio object { command, cwd, type, 2 more }` Starts an MCP server as a local process. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `args: optional array of string or null` Arguments passed to the MCP server command. - `env_vars: optional array of string or null` Environment variable names to inherit from the selected execution environment. - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `allowed_tools: optional array of string or null` The MCP tools the agent may call. All server tools are allowed when omitted. - `connection_origin: optional "service" or "environment" or null` Selects where outbound MCP HTTP connections originate. - `"service"` Uses the Managed Agents service network. - `"environment"` Uses the session's execution environment. - `credential_id: optional string or null` The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. - `request_metadata: optional map[unknown] or null` Metadata included with requests to this MCP server. - `required: optional boolean` Whether this MCP server must initialize before the first turn. Defaults to `false`. - `WebSearch object { type, allowed_domains, context_size, 2 more }` Web search. - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `allowed_domains: optional array of string or null` Domains the search may include. - `context_size: optional "low" or "medium" or "high" or null` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: optional object { city, country, region, timezone } or null` Approximate location used to localize search results. - `city: optional string or null` The city name. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. Defaults to `live`. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. - `ComputerUse object { type, include_screenshots }` Browser use in an OpenAI-hosted session. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `include_screenshots: optional boolean` Whether computer tool outputs include screenshots. Defaults to `false`. ### Returns - `Agent object { id, created_at, instructions, 10 more }` A reusable agent scoped to the caller's project. - `id: string` The ID of the reusable agent. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` The resolved configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server without stored credentials. - `allowed_tools: array of string or null` The MCP tools the agent may call, or null when all server tools are allowed. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `HTTP object { headers, server_url, type }` Connects to an MCP server over HTTP. - `headers: map[string]` Non-secret HTTP headers sent to the MCP server. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Example ```http curl https://api.openai.com/v1/agents/$AGENT_ID \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "instructions": "instructions", "metadata": { "foo": "string" }, "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "object": "agent", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ], "updated_at": 0 } ``` ### Example ```http # 1. Omit reasoning: keep its current settings while renaming the agent. curl "https://api.openai.com/v1/agents/$AGENT_ID" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: agents=v1" \ -d '{"name": "Renamed"}' # 2. Send null: reset reasoning to the model's defaults. curl "https://api.openai.com/v1/agents/$AGENT_ID" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: agents=v1" \ -d '{"reasoning": null}' # 3. Send an object: replace the entire reasoning configuration, without merging. # The agent's model must support the "low" reasoning effort. curl "https://api.openai.com/v1/agents/$AGENT_ID" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: agents=v1" \ -d '{"reasoning": {"effort": "low"}}' ``` ## Domain Types ### Agent - `Agent object { id, created_at, instructions, 10 more }` A reusable agent scoped to the caller's project. - `id: string` The ID of the reusable agent. - `created_at: number` The Unix timestamp, in seconds, when the agent was created. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `metadata: map[string]` Custom string key-value pairs attached to the agent. - `model: string` The requested model name used for inference. - `multi_agent: MultiAgentConfig` The resolved configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` A human-readable name for the agent, or null if it is unnamed. - `object: "agent"` The object type. Always `agent`. - `"agent"` - `reasoning: AgentReasoning` The resolved reasoning configuration, including the model default for an omitted effort. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The resolved service-tier policy used for model requests. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` The resolved configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of PersistedAgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server without stored credentials. - `allowed_tools: array of string or null` The MCP tools the agent may call, or null when all server tools are allowed. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `HTTP object { headers, server_url, type }` Connects to an MCP server over HTTP. - `headers: map[string]` Non-secret HTTP headers sent to the MCP server. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `updated_at: number` The Unix timestamp, in seconds, when the agent was last updated. ### Agent Browser Authentication Cancel Param - `AgentBrowserAuthenticationCancelParam object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` ### Agent Browser Authentication Submit Param - `AgentBrowserAuthenticationSubmitParam object { action, fields, type, selected_option }` - `action: "submit"` - `"submit"` - `fields: array of object { field_id, value }` Values for up to six active fields in the required action. The submitted field-value mapping and selected option must fit within 120 KiB of JSON. - `field_id: string` The field ID from the required action. - `value: string` The value to enter into the registered control. - `type: "browser_authentication"` - `"browser_authentication"` - `selected_option: optional string or null` The chosen method. Required when the required action contains options. ### Agent Browser Origin Access Param - `AgentBrowserOriginAccessParam object { decision, type }` - `decision: "approve" or "deny" or "cancel"` Whether to allow, deny, or cancel the requested origin access. - `"approve"` Allow the browser to access this origin. - `"deny"` Deny access to this origin. - `"cancel"` Dismiss this request without approving access. - `type: "browser_origin_access"` - `"browser_origin_access"` ### Agent Close Subagent Call Item - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. ### Agent Command Execution Item - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` ### Agent Content - `AgentContent = OutputText or EncryptedContent { encrypted_content, type }` A plaintext or encrypted content part exchanged between agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` ### Agent Create Subagent Call Item - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. ### Agent Deleted - `AgentDeleted object { id, deleted, object }` A deleted reusable agent. - `id: string` The ID of the deleted agent. - `deleted: boolean` Whether the agent was deleted. Always `true`. - `object: "agent.deleted"` The object type. Always `agent.deleted`. - `"agent.deleted"` ### Agent Function Call Item - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` ### Agent Function Call Output - `AgentFunctionCallOutput = string or array of InputContent` The text or model-input content supplied as a function result. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Agent Function Call Output Param - `AgentFunctionCallOutputParam = string or array of InputContentParam` A function result represented as text or supported model-input content. - `string` - `array of InputContentParam` - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Agent Function Call Status - `AgentFunctionCallStatus = "in_progress" or "completed" or "failed" or "incomplete"` The status of a tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. ### Agent Interrupt Subagent Call Item - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. ### Agent Mcp Call Item - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` ### Agent Output Command Execution Output Delta Event - `AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 4 more }` Emitted when command execution produces an output delta. - `delta: string` The output text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the command execution item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.output.command_execution_output.delta"` The type of the object. Always `agent.output.command_execution_output.delta`. - `"agent.output.command_execution_output.delta"` ### Agent Output Item - `AgentOutputItem = AgentSessionAssistantMessage or AgentReasoningItem or AgentFunctionCallItem or 11 more` An output item produced by an agent. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of the assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. ### Agent Output Item Status - `AgentOutputItemStatus = "in_progress" or "completed" or "incomplete"` The status of an agent output item. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. ### Agent Reasoning - `AgentReasoning object { effort, summary }` The reasoning configuration used by an agent. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. ### Agent Reasoning Item - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` ### Agent Reasoning Param - `AgentReasoningParam object { effort, summary }` Reasoning configuration for the agent. - `effort: optional "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort the model should use. Omission lets the model select it. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` Controls whether the response includes a reasoning summary. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. ### Agent Resume Subagent Call Item - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. ### Agent Send Subagent Input Call Item - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. ### Agent Session - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Agent Session Assistant Message - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of the assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` ### Agent Session Created Event - `AgentSessionCreatedEvent object { event_id, session, type }` Emitted when a session is created. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that was created. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.created"` The type of the object. Always `agent.session.created`. - `"agent.session.created"` ### Agent Session Deleted - `AgentSessionDeleted object { id, deleted, object }` A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously. - `id: string` The ID of the deleted session. - `deleted: boolean` Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress. - `object: "agent.session.deleted"` The object type. Always `agent.session.deleted`. - `"agent.session.deleted"` ### Agent Session Environment Connected Event - `AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment connects. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.connected"` The type of the object. Always `agent.session.environment.connected`. - `"agent.session.environment.connected"` ### Agent Session Environment Disconnected Event - `AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment disconnects. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.disconnected"` The type of the object. Always `agent.session.environment.disconnected`. - `"agent.session.environment.disconnected"` ### Agent Session Environment Expired Event - `AgentSessionEnvironmentExpiredEvent object { environment, event_id, session_id, 2 more }` Emitted after a suspended hosted session environment and its checkpoint expire. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.expired"` The type of the object. Always `agent.session.environment.expired`. - `"agent.session.environment.expired"` ### Agent Session Environment Failed Event - `AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment fails. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.failed"` The type of the object. Always `agent.session.environment.failed`. - `"agent.session.environment.failed"` ### Agent Session Environment Pending Event - `AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }` Emitted while a session environment is being prepared. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.pending"` The type of the object. Always `agent.session.environment.pending`. - `"agent.session.environment.pending"` ### Agent Session Environment Ready Event - `AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }` Emitted when a hosted session environment is ready to connect. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.ready"` The type of the object. Always `agent.session.environment.ready`. - `"agent.session.environment.ready"` ### Agent Session Environment Reset Event - `AgentSessionEnvironmentResetEvent object { environment_id, event_id, reset_count, 3 more }` Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox's files and processes do not. - `environment_id: string` The stable environment ID, retained across sandbox replacements. - `event_id: string` The unique ID of the event. - `reset_count: number` Monotonically increasing reset number. Repeated notifications share this number. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The associated turn, when applicable. - `type: "agent.session.environment.reset"` The type of the object. Always `agent.session.environment.reset`. - `"agent.session.environment.reset"` ### Agent Session Environment State - `AgentSessionEnvironmentState object { id, error, status, type }` The current state of a session environment. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. ### Agent Session Environment Suspended Event - `AgentSessionEnvironmentSuspendedEvent object { environment, event_id, session_id, 2 more }` Emitted after an idle hosted session environment is checkpointed and stopped. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.suspended"` The type of the object. Always `agent.session.environment.suspended`. - `"agent.session.environment.suspended"` ### Agent Session Error Event - `AgentSessionErrorEvent object { error, event_id, session_id, type }` Emitted when a turn or session fails. - `error: SessionError` The error that occurred. - `code: string or null` The machine-readable error code, if any. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `type: "error"` The type of the object. Always `error`. - `"error"` ### Agent Session Event - `AgentSessionEvent = AgentSessionErrorEvent or AgentSessionEnvironmentReadyEvent or AgentSessionEnvironmentSuspendedEvent or 30 more` An event emitted by a Managed Agents session. - `AgentSessionErrorEvent object { error, event_id, session_id, type }` Emitted when a turn or session fails. - `error: SessionError` The error that occurred. - `code: string or null` The machine-readable error code, if any. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `type: "error"` The type of the object. Always `error`. - `"error"` - `AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }` Emitted when a hosted session environment is ready to connect. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.ready"` The type of the object. Always `agent.session.environment.ready`. - `"agent.session.environment.ready"` - `AgentSessionEnvironmentSuspendedEvent object { environment, event_id, session_id, 2 more }` Emitted after an idle hosted session environment is checkpointed and stopped. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.suspended"` The type of the object. Always `agent.session.environment.suspended`. - `"agent.session.environment.suspended"` - `AgentSessionEnvironmentExpiredEvent object { environment, event_id, session_id, 2 more }` Emitted after a suspended hosted session environment and its checkpoint expire. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.expired"` The type of the object. Always `agent.session.environment.expired`. - `"agent.session.environment.expired"` - `AgentSessionEnvironmentResetEvent object { environment_id, event_id, reset_count, 3 more }` Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox's files and processes do not. - `environment_id: string` The stable environment ID, retained across sandbox replacements. - `event_id: string` The unique ID of the event. - `reset_count: number` Monotonically increasing reset number. Repeated notifications share this number. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The associated turn, when applicable. - `type: "agent.session.environment.reset"` The type of the object. Always `agent.session.environment.reset`. - `"agent.session.environment.reset"` - `AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 4 more }` Emitted when command execution produces an output delta. - `delta: string` The output text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the command execution item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.output.command_execution_output.delta"` The type of the object. Always `agent.output.command_execution_output.delta`. - `"agent.output.command_execution_output.delta"` - `AgentSessionCreatedEvent object { event_id, session, type }` Emitted when a session is created. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that was created. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.created"` The type of the object. Always `agent.session.created`. - `"agent.session.created"` - `AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn is created. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it was created. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.created"` The type of the object. Always `agent.session.turn.created`. - `"agent.session.turn.created"` - `AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn starts running. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it started running. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.in_progress"` The type of the object. Always `agent.session.turn.in_progress`. - `"agent.session.turn.in_progress"` - `AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn completes. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The completed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.completed"` The type of the object. Always `agent.session.turn.completed`. - `"agent.session.turn.completed"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. - `AgentSessionTurnFailedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn fails. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The failed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.failed"` The type of the object. Always `agent.session.turn.failed`. - `"agent.session.turn.failed"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. - `AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn is cancelled. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The cancelled turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.cancelled"` The type of the object. Always `agent.session.turn.cancelled`. - `"agent.session.turn.cancelled"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. - `AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 3 more }` Emitted when an item is added to a turn. - `event_id: string` The unique ID of the event. - `item: AgentSessionItem` The item that was added. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number or null` The index of the item in the turn output, when the item is agent output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.added"` The type of the object. Always `agent.session.turn.item.added`. - `"agent.session.turn.item.added"` - `AgentSessionIdleEvent object { event_id, session, type }` Emitted when a session becomes idle. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that became idle. - `type: "agent.session.idle"` The type of the object. Always `agent.session.idle`. - `"agent.session.idle"` - `AgentSessionInProgressEvent object { event_id, session, type }` Emitted when a session starts processing a turn. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that started processing. - `type: "agent.session.in_progress"` The type of the object. Always `agent.session.in_progress`. - `"agent.session.in_progress"` - `AgentSessionRequiresActionEvent object { event_id, session, type }` Emitted when a session is waiting for one or more required actions. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session and its current required actions. - `type: "agent.session.requires_action"` The type of the object. Always `agent.session.requires_action`. - `"agent.session.requires_action"` - `AgentSessionFailedEvent object { event_id, session, type }` Emitted when a session fails. - `event_id: string` The unique ID of the event. - `session: AgentSession` The failed session. - `type: "agent.session.failed"` The type of the object. Always `agent.session.failed`. - `"agent.session.failed"` - `AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }` Emitted while a session environment is being prepared. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.pending"` The type of the object. Always `agent.session.environment.pending`. - `"agent.session.environment.pending"` - `AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment connects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.connected"` The type of the object. Always `agent.session.environment.connected`. - `"agent.session.environment.connected"` - `AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment disconnects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.disconnected"` The type of the object. Always `agent.session.environment.disconnected`. - `"agent.session.environment.disconnected"` - `AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment fails. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.failed"` The type of the object. Always `agent.session.environment.failed`. - `"agent.session.environment.failed"` - `AgentSessionSubagentCreatedEvent object { event_id, subagent, type }` Emitted when a subagent is created. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was created. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.created"` The type of the object. Always `agent.session.subagent.created`. - `"agent.session.subagent.created"` - `AgentSessionSubagentActiveEvent object { event_id, subagent, type }` Emitted when a closed subagent successfully resumes. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that resumed. - `type: "agent.session.subagent.active"` The type of the object. Always `agent.session.subagent.active`. - `"agent.session.subagent.active"` - `AgentSessionSubagentClosedEvent object { event_id, subagent, type }` Emitted when a subagent is closed. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was closed. - `type: "agent.session.subagent.closed"` The type of the object. Always `agent.session.subagent.closed`. - `"agent.session.subagent.closed"` - `AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 3 more }` Emitted when an output item is complete. - `event_id: string` The unique ID of the event. - `item: AgentOutputItem` The completed output item. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `phase: "commentary" or "final_answer" or null` The phase of the assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `output_index: number` The index of the output item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.done"` The type of the object. Always `agent.session.turn.item.done`. - `"agent.session.turn.item.done"` - `AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output text content part is added. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The initial content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.added"` The type of the object. Always `agent.session.turn.content_part.added`. - `"agent.session.turn.content_part.added"` - `AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output content part is complete. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The completed content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.done"` The type of the object. Always `agent.session.turn.content_part.done`. - `"agent.session.turn.content_part.done"` - `AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 5 more }` Emitted when text is appended to an output text content part. - `content_index: number` The index of the content part in the message. - `delta: string` The text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.delta"` The type of the object. Always `agent.session.turn.output_text.delta`. - `"agent.session.turn.output_text.delta"` - `AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output text content part is complete. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `text: string` The complete output text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.done"` The type of the object. Always `agent.session.turn.output_text.done`. - `"agent.session.turn.output_text.done"` - `AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 5 more }` Emitted when a reasoning summary content part is added. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The initial summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.added"` The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. - `"agent.session.turn.reasoning_summary_part.added"` - `AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 6 more }` Emitted when a reasoning summary part is complete. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The completed summary part. - `session_id: string` The ID of the session associated with the event. - `status: "incomplete" or null` Present as `incomplete` when summary generation was interrupted. - `"incomplete"` - `summary_index: number` The index of the summary part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.done"` The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. - `"agent.session.turn.reasoning_summary_part.done"` - `AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 5 more }` Emitted when text is appended to a reasoning summary. - `delta: string` The summary text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.delta"` The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. - `"agent.session.turn.reasoning_summary_text.delta"` - `AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 5 more }` Emitted when a reasoning summary content part is complete. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `text: string` The complete reasoning summary text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.done"` The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. - `"agent.session.turn.reasoning_summary_text.done"` ### Agent Session Failed Event - `AgentSessionFailedEvent object { event_id, session, type }` Emitted when a session fails. - `event_id: string` The unique ID of the event. - `session: AgentSession` The failed session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.failed"` The type of the object. Always `agent.session.failed`. - `"agent.session.failed"` ### Agent Session Idle Event - `AgentSessionIdleEvent object { event_id, session, type }` Emitted when a session becomes idle. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that became idle. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.idle"` The type of the object. Always `agent.session.idle`. - `"agent.session.idle"` ### Agent Session In Progress Event - `AgentSessionInProgressEvent object { event_id, session, type }` Emitted when a session starts processing a turn. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that started processing. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.in_progress"` The type of the object. Always `agent.session.in_progress`. - `"agent.session.in_progress"` ### Agent Session Input Message Param - `AgentSessionInputMessageParam object { content, role, type }` A user message submitted to a session. - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` ### Agent Session Input Param - `AgentSessionInputParam = AgentSessionInputComputerUseApprovalRequestResult { request_id, response, type } or AgentSessionInputMessage { input, type } or AgentSessionInputCancel { type } or AgentSessionInputToolResult { call_id, success, turn_id, 3 more }` Input submitted to an existing session. - `AgentSessionInputComputerUseApprovalRequestResult object { request_id, response, type }` Responds to a pending Computer Use approval request. - `request_id: string` The registered request ID from the required action. - `response: AgentBrowserAuthenticationSubmitParam or AgentBrowserAuthenticationCancelParam or AgentBrowserOriginAccessParam` The response for this request type. - `AgentBrowserAuthenticationSubmitParam object { action, fields, type, selected_option }` - `action: "submit"` - `"submit"` - `fields: array of object { field_id, value }` Values for up to six active fields in the required action. The submitted field-value mapping and selected option must fit within 120 KiB of JSON. - `field_id: string` The field ID from the required action. - `value: string` The value to enter into the registered control. - `type: "browser_authentication"` - `"browser_authentication"` - `selected_option: optional string or null` The chosen method. Required when the required action contains options. - `AgentBrowserAuthenticationCancelParam object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `AgentBrowserOriginAccessParam object { decision, type }` - `decision: "approve" or "deny" or "cancel"` Whether to allow, deny, or cancel the requested origin access. - `"approve"` Allow the browser to access this origin. - `"deny"` Deny access to this origin. - `"cancel"` Dismiss this request without approving access. - `type: "browser_origin_access"` - `"browser_origin_access"` - `type: "agent.session.input.computer_use_approval_request_result"` The type of the object. Always `agent.session.input.computer_use_approval_request_result`. - `"agent.session.input.computer_use_approval_request_result"` - `AgentSessionInputMessage object { input, type }` Adds one or more user messages and starts a turn. - `input: array of AgentSessionInputMessageParam` The user messages to add to the session. - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` - `type: "agent.session.input.message"` The type of the object. Always `agent.session.input.message`. - `"agent.session.input.message"` - `AgentSessionInputCancel object { type }` Cancels the session's active turn. - `type: "agent.session.input.cancel"` The type of the object. Always `agent.session.input.cancel`. - `"agent.session.input.cancel"` - `AgentSessionInputToolResult object { call_id, success, turn_id, 3 more }` Submits the result of a function call. - `call_id: string` The ID of the function call. - `success: boolean` Whether the function call succeeded. - `turn_id: string` The ID of the turn that requested the function call. - `type: "agent.session.input.tool_result"` The type of the object. Always `agent.session.input.tool_result`. - `"agent.session.input.tool_result"` - `error: optional string or null` The error message when the call failed. - `output: optional AgentFunctionCallOutputParam or null` The function result when the call succeeded. - `string` - `array of InputContentParam` - `InputText object { text, type }` Text input to the model. - `InputImage object { image_url, type }` Image input to the model. ### Agent Session Item - `AgentSessionItem = AgentSessionMessage or AgentReasoningItem or AgentFunctionCallItem or 14 more` An item associated with a session turn. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. ### Agent Session Message - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` ### Agent Session Message Content - `AgentSessionMessageContent = InputText { text, type } or InputImage { image_url, type } or OutputText { text, type }` A content part in a session message. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` ### Agent Session Requires Action Event - `AgentSessionRequiresActionEvent object { event_id, session, type }` Emitted when a session is waiting for one or more required actions. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session and its current required actions. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.requires_action"` The type of the object. Always `agent.session.requires_action`. - `"agent.session.requires_action"` ### Agent Session Subagent Active Event - `AgentSessionSubagentActiveEvent object { event_id, subagent, type }` Emitted when a closed subagent successfully resumes. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that resumed. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.active"` The type of the object. Always `agent.session.subagent.active`. - `"agent.session.subagent.active"` ### Agent Session Subagent Closed Event - `AgentSessionSubagentClosedEvent object { event_id, subagent, type }` Emitted when a subagent is closed. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was closed. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.closed"` The type of the object. Always `agent.session.subagent.closed`. - `"agent.session.subagent.closed"` ### Agent Session Subagent Created Event - `AgentSessionSubagentCreatedEvent object { event_id, subagent, type }` Emitted when a subagent is created. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was created. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.created"` The type of the object. Always `agent.session.subagent.created`. - `"agent.session.subagent.created"` ### Agent Session Turn Cancelled Event - `AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn is cancelled. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The cancelled turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.cancelled"` The type of the object. Always `agent.session.turn.cancelled`. - `"agent.session.turn.cancelled"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. ### Agent Session Turn Completed Event - `AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn completes. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The completed turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.completed"` The type of the object. Always `agent.session.turn.completed`. - `"agent.session.turn.completed"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. ### Agent Session Turn Content Part Added Event - `AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output text content part is added. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The initial content part. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.added"` The type of the object. Always `agent.session.turn.content_part.added`. - `"agent.session.turn.content_part.added"` ### Agent Session Turn Content Part Done Event - `AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output content part is complete. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The completed content part. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.done"` The type of the object. Always `agent.session.turn.content_part.done`. - `"agent.session.turn.content_part.done"` ### Agent Session Turn Created Event - `AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn is created. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it was created. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.created"` The type of the object. Always `agent.session.turn.created`. - `"agent.session.turn.created"` ### Agent Session Turn Failed Event - `AgentSessionTurnFailedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn fails. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The failed turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.failed"` The type of the object. Always `agent.session.turn.failed`. - `"agent.session.turn.failed"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. ### Agent Session Turn In Progress Event - `AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn starts running. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it started running. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.in_progress"` The type of the object. Always `agent.session.turn.in_progress`. - `"agent.session.turn.in_progress"` ### Agent Session Turn Item Added Event - `AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 3 more }` Emitted when an item is added to a turn. - `event_id: string` The unique ID of the event. - `item: AgentSessionItem` The item that was added. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number or null` The index of the item in the turn output, when the item is agent output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.added"` The type of the object. Always `agent.session.turn.item.added`. - `"agent.session.turn.item.added"` ### Agent Session Turn Item Done Event - `AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 3 more }` Emitted when an output item is complete. - `event_id: string` The unique ID of the event. - `item: AgentOutputItem` The completed output item. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of the assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number` The index of the output item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.done"` The type of the object. Always `agent.session.turn.item.done`. - `"agent.session.turn.item.done"` ### Agent Session Turn Output Text Delta Event - `AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 5 more }` Emitted when text is appended to an output text content part. - `content_index: number` The index of the content part in the message. - `delta: string` The text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.delta"` The type of the object. Always `agent.session.turn.output_text.delta`. - `"agent.session.turn.output_text.delta"` ### Agent Session Turn Output Text Done Event - `AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output text content part is complete. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `text: string` The complete output text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.done"` The type of the object. Always `agent.session.turn.output_text.done`. - `"agent.session.turn.output_text.done"` ### Agent Session Turn Reasoning Summary Part Added Event - `AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 5 more }` Emitted when a reasoning summary content part is added. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The initial summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.added"` The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. - `"agent.session.turn.reasoning_summary_part.added"` ### Agent Session Turn Reasoning Summary Part Done Event - `AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 6 more }` Emitted when a reasoning summary part is complete. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The completed summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `session_id: string` The ID of the session associated with the event. - `status: "incomplete" or null` Present as `incomplete` when summary generation was interrupted. - `"incomplete"` - `summary_index: number` The index of the summary part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.done"` The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. - `"agent.session.turn.reasoning_summary_part.done"` ### Agent Session Turn Reasoning Summary Text Delta Event - `AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 5 more }` Emitted when text is appended to a reasoning summary. - `delta: string` The summary text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.delta"` The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. - `"agent.session.turn.reasoning_summary_text.delta"` ### Agent Session Turn Reasoning Summary Text Done Event - `AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 5 more }` Emitted when a reasoning summary content part is complete. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `text: string` The complete reasoning summary text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.done"` The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. - `"agent.session.turn.reasoning_summary_text.done"` ### Agent Text - `AgentText object { format, verbosity }` The text configuration used by an agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` ### Agent Text Param - `AgentTextParam object { format, verbosity }` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format. Omission uses ordinary text (`{"type": "text"}`). - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. Defaults to `medium`, matching Responses. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. ### Agent Tool - `AgentTool = Function { defer_loading, description, name, 2 more } or ProgrammaticToolCalling { enabled, type } or Mcp { allowed_tools, connection_origin, credential_id, 5 more } or 2 more` A tool available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` ### Agent Tool Param - `AgentToolParam = Function { description, name, parameters, 2 more } or ToolSearch { type } or ProgrammaticToolCalling { type, enabled } or 3 more` A tool available to the agent. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `defer_loading: optional boolean` Whether this function is deferred and discovered through tool search. Defaults to `false`. - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { type, enabled }` Enables calling tools from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `enabled: optional boolean` Whether tools can be called from model-generated code. Defaults to `true`. - `Mcp object { server_label, transport, type, 5 more }` Tools provided by a remote MCP server. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransportParam` The transport used to connect to the MCP server. - `HTTP object { server_url, type, authorization, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `authorization: optional string or null` The authorization value sent to the MCP server, if any. - `headers: optional map[string] or null` Additional HTTP headers sent to the MCP server. - `Stdio object { command, cwd, type, 3 more }` Starts an MCP server as a local process. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `args: optional array of string or null` Arguments passed to the MCP server command. - `env: optional map[string] or null` Environment variables set for the MCP server process. - `env_vars: optional array of string or null` Environment variable names to inherit from the selected execution environment. - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `allowed_tools: optional array of string or null` The MCP tools the agent may call. All server tools are allowed when omitted. - `connection_origin: optional "service" or "environment" or null` Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment. - `"service"` Uses the Managed Agents service network. - `"environment"` Uses the session's execution environment. - `credential_id: optional string or null` The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL. - `request_metadata: optional map[unknown] or null` Metadata included with requests to this MCP server. - `required: optional boolean` Whether this MCP server must initialize before the first turn. Defaults to `false`. - `WebSearch object { type, allowed_domains, context_size, 2 more }` Web search. - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `allowed_domains: optional array of string or null` Domains the search may include. - `context_size: optional "low" or "medium" or "high" or null` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: optional object { city, country, region, timezone } or null` Approximate location used to localize search results. - `city: optional string or null` The city name. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. Defaults to `live`. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. - `ComputerUse object { type, include_screenshots }` Browser use in an OpenAI-hosted session. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `include_screenshots: optional boolean` Whether computer tool outputs include screenshots. Defaults to `false`. ### Agent Wait For Subagents Call Item - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. ### Agent Web Search Call Item - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` ### Environment - `Environment = None { type } or OpenAIHosted { id, capability_directories, desktop, 7 more } or SelfHosted { id, capability_directories, remote_url, 2 more }` The execution environment for a session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. ### Environment Param - `EnvironmentParam = None { type } or OpenAIHosted { type, capability_directories, container_size, 10 more } or SelfHosted { type, workspace_directory, capability_directories }` The execution environment and optional reusable template for a session. - `None object { type }` Runs the agent without an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { type, capability_directories, container_size, 10 more }` An existing OpenAI-hosted environment or new inline/template-based hosted configuration. - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `container_size: optional "small" or "medium" or "large"` The hosted container size. Omission selects the medium tier. - `"small"` - `"medium"` - `"large"` - `desktop: optional object { enabled } or null` Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. - `enabled: boolean` Whether to provision the desktop and its browser proxy. - `env: optional map[string] or null` Environment variables made available to the agent. - `environment_id: optional string` An existing prewarmed environment. Cannot be combined with a template or inline configuration. - `environment_template_id: optional string` A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. - `files: optional array of HostedEnvironmentFileParam or null` Files available before the agent starts. Defaults to an empty list. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: optional object { access, allowed_domains, blocked_domains } or null` Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: optional array of string or null` Domains the environment may access when network access is restricted. - `blocked_domains: optional array of string or null` Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported. - `packages: optional object { npm, python, system } or null` Packages to install in the environment. Defaults to empty package lists. - `npm: optional array of string or null` npm packages to install globally. Defaults to an empty list. - `python: optional array of string or null` Python packages to install. Defaults to an empty list. - `system: optional array of string or null` System packages to install. Defaults to an empty list. - `plugins: optional array of HostedPluginParam or null` Plugins provided as inline ZIP archives. Defaults to an empty list. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Ordered, confidential setup commands. Command bodies are never returned. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - `SkillReference object { skill_id, type, version }` References a skill uploaded through the Skills API. - `skill_id: string` The ID of the skill created through `/v1/skills`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `SelfHosted object { type, workspace_directory, capability_directories }` An application-hosted environment configured inline. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` Absolute project directory inside the self-hosted environment. - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. ### Hosted Environment File - `HostedEnvironmentFile = HostedEnvironmentFileID or Inline { id, path, size_bytes, type }` Metadata for a file materialized in an OpenAI-hosted execution environment. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Environment File ID - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` ### Hosted Environment File Param - `HostedEnvironmentFileParam = FileID { file_id, path, type } or Inline { data, path, type }` A file materialized in an OpenAI-hosted execution environment. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Plugin - `HostedPlugin object { description, name, type }` A plugin installed from an inline ZIP archive. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Plugin Param - `HostedPluginParam object { description, name, source, type }` Supplies a plugin ZIP directly in the session request. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Skill - `HostedSkill = HostedSkillReference or Inline { description, name, type }` A skill installed in an OpenAI-hosted environment. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Skill Param - `HostedSkillParam = SkillReference { skill_id, type, version } or Inline { description, name, source, type }` A skill installed in an OpenAI-hosted environment. - `SkillReference object { skill_id, type, version }` References a skill uploaded through the Skills API. - `skill_id: string` The ID of the skill created through `/v1/skills`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Hosted Skill Reference - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. ### Inline Capability Source Param - `InlineCapabilitySourceParam object { data, media_type, type }` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` ### Input Content - `InputContent = InputText { text, type } or InputImage { image_url, type }` User-provided content recorded in a session item. - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Input Content Param - `InputContentParam = InputText { text, type } or InputImage { image_url, type }` Content included in an input message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` ### Mcp Transport - `McpTransport = HTTP { server_url, type } or Stdio { args, command, cwd, 2 more }` The transport used to connect to an MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` ### Mcp Transport Param - `McpTransportParam = HTTP { server_url, type, authorization, headers } or Stdio { command, cwd, type, 3 more }` The transport used to connect to an MCP server. - `HTTP object { server_url, type, authorization, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `authorization: optional string or null` The authorization value sent to the MCP server, if any. - `headers: optional map[string] or null` Additional HTTP headers sent to the MCP server. - `Stdio object { command, cwd, type, 3 more }` Starts an MCP server as a local process. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `args: optional array of string or null` Arguments passed to the MCP server command. - `env: optional map[string] or null` Environment variables set for the MCP server process. - `env_vars: optional array of string or null` Environment variable names to inherit from the selected execution environment. ### Multi Agent Config - `MultiAgentConfig object { enabled, max_concurrent_subagents }` The resolved configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. ### Multi Agent Config Param - `MultiAgentConfigParam object { enabled, max_concurrent_subagents }` Explicit configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. - `max_concurrent_subagents: optional number` Maximum number of subagents that may run concurrently. Defaults to 6. ### Output Text - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` ### Persisted Agent Tool - `PersistedAgentTool = Function { defer_loading, description, name, 2 more } or ToolSearch { type } or ProgrammaticToolCalling { enabled, type } or 3 more` A credential-free tool available to a reusable agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server without stored credentials. - `allowed_tools: array of string or null` The MCP tools the agent may call, or null when all server tools are allowed. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The vault credential selected for this MCP server, if any. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransport` The credential-free transport used to connect to the MCP server. - `HTTP object { headers, server_url, type }` Connects to an MCP server over HTTP. - `headers: map[string]` Non-secret HTTP headers sent to the MCP server. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` ### Persisted Agent Tool Param - `PersistedAgentToolParam = Function { description, name, parameters, 2 more } or ToolSearch { type } or ProgrammaticToolCalling { type, enabled } or 3 more` A tool that can be stored on a reusable agent without session credentials. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `defer_loading: optional boolean` Whether this function is deferred and discovered through tool search. Defaults to `false`. - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { type, enabled }` Enables calling tools from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `enabled: optional boolean` Whether tools can be called from model-generated code. Defaults to `true`. - `Mcp object { server_label, transport, type, 5 more }` Tools provided by a remote MCP server without stored credentials. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: PersistedMcpTransportParam` The credential-free transport used to connect to the MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `headers: optional map[string] or null` Non-secret HTTP headers sent to the MCP server. - `Stdio object { command, cwd, type, 2 more }` Starts an MCP server as a local process. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `args: optional array of string or null` Arguments passed to the MCP server command. - `env_vars: optional array of string or null` Environment variable names to inherit from the selected execution environment. - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `allowed_tools: optional array of string or null` The MCP tools the agent may call. All server tools are allowed when omitted. - `connection_origin: optional "service" or "environment" or null` Selects where outbound MCP HTTP connections originate. - `"service"` Uses the Managed Agents service network. - `"environment"` Uses the session's execution environment. - `credential_id: optional string or null` The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL. - `request_metadata: optional map[unknown] or null` Metadata included with requests to this MCP server. - `required: optional boolean` Whether this MCP server must initialize before the first turn. Defaults to `false`. - `WebSearch object { type, allowed_domains, context_size, 2 more }` Web search. - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `allowed_domains: optional array of string or null` Domains the search may include. - `context_size: optional "low" or "medium" or "high" or null` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: optional object { city, country, region, timezone } or null` Approximate location used to localize search results. - `city: optional string or null` The city name. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. Defaults to `live`. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. - `ComputerUse object { type, include_screenshots }` Browser use in an OpenAI-hosted session. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `include_screenshots: optional boolean` Whether computer tool outputs include screenshots. Defaults to `false`. ### Persisted Mcp Transport - `PersistedMcpTransport = HTTP { headers, server_url, type } or Stdio { args, command, cwd, 2 more }` A credential-free transport used to connect to an MCP server. - `HTTP object { headers, server_url, type }` Connects to an MCP server over HTTP. - `headers: map[string]` Non-secret HTTP headers sent to the MCP server. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` ### Persisted Mcp Transport Param - `PersistedMcpTransportParam = HTTP { server_url, type, headers } or Stdio { command, cwd, type, 2 more }` A credential-free transport used to connect to an MCP server. - `HTTP object { server_url, type, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `headers: optional map[string] or null` Non-secret HTTP headers sent to the MCP server. - `Stdio object { command, cwd, type, 2 more }` Starts an MCP server as a local process. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `args: optional array of string or null` Arguments passed to the MCP server command. - `env_vars: optional array of string or null` Environment variable names to inherit from the selected execution environment. ### Session Error - `SessionError object { code, message, param, type }` An error payload with the same public fields as Responses API streaming errors. - `code: string or null` The machine-readable error code, if any. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. ### Session Turn Error - `SessionTurnError object { code, message }` A customer-safe error describing why a session request failed. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. ### Setup Command Param - `SetupCommandParam object { command, cwd }` A confidential setup command executed before the hosted agent starts. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. ### Subagent - `Subagent object { id, closed_at, instructions, 6 more }` A subagent created within a session. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. ### Summary Text - `SummaryText object { text, type }` A reasoning summary content part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` ### Text Format - `TextFormat = Text { type } or JSONSchema { schema, type }` The effective output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` ### Text Format Param - `TextFormatParam = Text { type } or JSONSchema { schema, type }` The output format for generated text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` ### Token Usage - `TokenUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }` Recorded token usage for a session or turn. Usage is best effort and may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. ### Web Search Action - `WebSearchAction = Search { queries, query, type } or OpenPage { type, url } or FindInPage { pattern, type, url } or Other { type }` An action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` # Environments ## Create an agent environment **post** `/agents/environments` Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta. ### Header Parameters - `"Idempotency-Key": optional string` ### Body Parameters - `environment: object { type, capability_directories, desktop, 8 more }` The required hosting type and its configuration. - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `desktop: optional object { enabled } or null` Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. - `enabled: boolean` Whether to provision the desktop and its browser proxy. - `env: optional map[string] or null` Environment variables made available to the agent. - `environment_template_id: optional string` A reusable hosted template applied before inline configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. - `files: optional array of HostedEnvironmentFileParam or null` Files available before the agent starts. Defaults to an empty list. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: optional object { access, allowed_domains, blocked_domains } or null` Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: optional array of string or null` Domains the environment may access when network access is restricted. - `blocked_domains: optional array of string or null` Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported. - `packages: optional object { npm, python, system } or null` Packages to install in the environment. Defaults to empty package lists. - `npm: optional array of string or null` npm packages to install globally. Defaults to an empty list. - `python: optional array of string or null` Python packages to install. Defaults to an empty list. - `system: optional array of string or null` System packages to install. Defaults to an empty list. - `plugins: optional array of HostedPluginParam or null` Plugins provided as inline ZIP archives. Defaults to an empty list. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Ordered, confidential setup commands. Command bodies are never returned. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - `SkillReference object { skill_id, type, version }` References a skill uploaded through the Skills API. - `skill_id: string` The ID of the skill created through `/v1/skills`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `vault_ids: optional array of string or null` The IDs of up to 10 vaults made available to an OpenAI-hosted environment. ### Returns - `EnvironmentInfo object { id, files, object, 4 more }` Safe metadata for a first-class execution environment. - `id: string` The ID of the environment. - `files: array of HostedEnvironmentFile` Files installed in the environment, without their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `object: "agent.environment"` The object type. Always `agent.environment`. - `"agent.environment"` - `plugins: array of HostedPlugin` Plugins installed in the environment, without their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, without their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `status: "pending" or "ready" or "connected" or 4 more` The current environment connection status. - `"pending"` - `"ready"` Provisioning succeeded and the environment is available for attachment or use. - `"connected"` - `"disconnected"` - `"suspended"` The sandbox is stopped and can be resumed from its private checkpoint. - `"expired"` - `"failed"` - `type: "openai_hosted" or "self_hosted"` Whether the environment is hosted by OpenAI or by the application. - `"openai_hosted"` - `"self_hosted"` ### Example ```http curl https://api.openai.com/v1/agents/environments \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "environment": { "type": "openai_hosted" } }' ``` #### Response ```json { "id": "id", "files": [ { "id": "id", "file_id": "file_id", "path": "path", "size_bytes": 0, "type": "file_id" } ], "object": "agent.environment", "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "description": "description", "name": "name", "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "status": "pending", "type": "openai_hosted" } ``` ## List agent environments **get** `/agents/environments` Lists OpenAI-hosted environments owned by the authenticated principal. Requires access to the prewarming beta. ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. - `type: optional "openai_hosted"` The hosting type to list. Defaults to `openai_hosted`. - `"openai_hosted"` ### Returns - `data: array of EnvironmentInfo` The resources returned in this page, in the requested sort order. - `id: string` The ID of the environment. - `files: array of HostedEnvironmentFile` Files installed in the environment, without their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `object: "agent.environment"` The object type. Always `agent.environment`. - `"agent.environment"` - `plugins: array of HostedPlugin` Plugins installed in the environment, without their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, without their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `status: "pending" or "ready" or "connected" or 4 more` The current environment connection status. - `"pending"` - `"ready"` Provisioning succeeded and the environment is available for attachment or use. - `"connected"` - `"disconnected"` - `"suspended"` The sandbox is stopped and can be resumed from its private checkpoint. - `"expired"` - `"failed"` - `type: "openai_hosted" or "self_hosted"` Whether the environment is hosted by OpenAI or by the application. - `"openai_hosted"` - `"self_hosted"` - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/environments \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "files": [ { "id": "id", "file_id": "file_id", "path": "path", "size_bytes": 0, "type": "file_id" } ], "object": "agent.environment", "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "description": "description", "name": "name", "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "status": "pending", "type": "openai_hosted" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent environment **get** `/agents/environments/{environment_id}` Retrieves an execution environment's connection status and safe installed metadata. See [environment lifecycle](/api/docs/guides/agents-api/environments/lifecycle). ### Path Parameters - `environment_id: string` ### Returns - `EnvironmentInfo object { id, files, object, 4 more }` Safe metadata for a first-class execution environment. - `id: string` The ID of the environment. - `files: array of HostedEnvironmentFile` Files installed in the environment, without their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `object: "agent.environment"` The object type. Always `agent.environment`. - `"agent.environment"` - `plugins: array of HostedPlugin` Plugins installed in the environment, without their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, without their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `status: "pending" or "ready" or "connected" or 4 more` The current environment connection status. - `"pending"` - `"ready"` Provisioning succeeded and the environment is available for attachment or use. - `"connected"` - `"disconnected"` - `"suspended"` The sandbox is stopped and can be resumed from its private checkpoint. - `"expired"` - `"failed"` - `type: "openai_hosted" or "self_hosted"` Whether the environment is hosted by OpenAI or by the application. - `"openai_hosted"` - `"self_hosted"` ### Example ```http curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "files": [ { "id": "id", "file_id": "file_id", "path": "path", "size_bytes": 0, "type": "file_id" } ], "object": "agent.environment", "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "description": "description", "name": "name", "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "status": "pending", "type": "openai_hosted" } ``` ## Domain Types ### Environment Info - `EnvironmentInfo object { id, files, object, 4 more }` Safe metadata for a first-class execution environment. - `id: string` The ID of the environment. - `files: array of HostedEnvironmentFile` Files installed in the environment, without their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `object: "agent.environment"` The object type. Always `agent.environment`. - `"agent.environment"` - `plugins: array of HostedPlugin` Plugins installed in the environment, without their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, without their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `status: "pending" or "ready" or "connected" or 4 more` The current environment connection status. - `"pending"` - `"ready"` Provisioning succeeded and the environment is available for attachment or use. - `"connected"` - `"disconnected"` - `"suspended"` The sandbox is stopped and can be resumed from its private checkpoint. - `"expired"` - `"failed"` - `type: "openai_hosted" or "self_hosted"` Whether the environment is hosted by OpenAI or by the application. - `"openai_hosted"` - `"self_hosted"` # Files ## Write an agent environment file **post** `/agents/environments/{environment_id}/files` Copies inline bytes or a Files API file into a connected execution environment, replacing an existing regular file at the same path. Upload between turns and wait for success before starting the next turn. See [environment files](/api/docs/guides/agents-api/environments/files). ### Path Parameters - `environment_id: string` ### Body Parameters - `hosted_environment_file_param: HostedEnvironmentFileParam` A file materialized in an OpenAI-hosted execution environment. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Returns - `EnvironmentFile object { environment_id, object, path, size_bytes }` A live file in an execution environment. - `environment_id: string` The ID of the environment containing this file. - `object: "agent.environment.file"` The object type. Always `agent.environment.file`. - `"agent.environment.file"` - `path: string` The absolute file path inside the environment's workspace. - `size_bytes: number` The file size in bytes. ### Example ```http curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID/files \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "environment_id": "environment_id", "object": "agent.environment.file", "path": "path", "size_bytes": 0 } ``` ## List agent environment files **get** `/agents/environments/{environment_id}/files` Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination. See [environment files](/api/docs/guides/agents-api/environments/files). ### Path Parameters - `environment_id: string` ### Query Parameters - `limit: optional number or null` The maximum number of files to return, between 1 and 100. - `order: optional "asc" or "desc"` Sort by case-sensitive path components. Defaults to descending. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. - `page: optional string` The opaque token from the previous page. Keep the same path, order, and limit. - `path: optional string or null` Restrict the listing to this absolute workspace directory. ### Returns - `data: array of EnvironmentFile` Files available on the current page. - `environment_id: string` The ID of the environment containing this file. - `object: "agent.environment.file"` The object type. Always `agent.environment.file`. - `"agent.environment.file"` - `path: string` The absolute file path inside the environment's workspace. - `size_bytes: number` The file size in bytes. - `has_more: boolean` Whether more files follow this page. - `next: string or null` The opaque cursor to use when requesting the next page, if any. - `object: "page"` The object type. Always `page`. - `"page"` ### Example ```http curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID/files \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "environment_id": "environment_id", "object": "agent.environment.file", "path": "path", "size_bytes": 0 } ], "has_more": true, "next": "next", "object": "page" } ``` ## Domain Types ### Environment File - `EnvironmentFile object { environment_id, object, path, size_bytes }` A live file in an execution environment. - `environment_id: string` The ID of the environment containing this file. - `object: "agent.environment.file"` The object type. Always `agent.environment.file`. - `"agent.environment.file"` - `path: string` The absolute file path inside the environment's workspace. - `size_bytes: number` The file size in bytes. # Templates ## Create an agent environment template **post** `/agents/environments/templates` Creates reusable environment configuration without returning confidential setup commands or environment values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Body Parameters - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `desktop: optional object { enabled } or null` Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. - `enabled: boolean` Whether to provision the desktop and its browser proxy. - `env: optional map[string] or null` Environment variables made available to the agent. - `files: optional array of HostedEnvironmentFileParam or null` Files available before the agent starts. Defaults to an empty list. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: optional string or null` An optional human-readable display name for the template. - `network: optional object { access, allowed_domains, blocked_domains } or null` Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: optional array of string or null` Domains the environment may access when network access is restricted. - `blocked_domains: optional array of string or null` Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported. - `packages: optional object { npm, python, system } or null` Packages to install in the environment. Defaults to empty package lists. - `npm: optional array of string or null` npm packages to install globally. Defaults to an empty list. - `python: optional array of string or null` Python packages to install. Defaults to an empty list. - `system: optional array of string or null` System packages to install. Defaults to an empty list. - `plugins: optional array of HostedPluginParam or null` Plugins provided as inline ZIP archives. Defaults to an empty list. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Ordered, confidential setup commands. Command bodies are never returned. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - `SkillReference object { skill_id, type, version }` References a skill uploaded through the Skills API. - `skill_id: string` The ID of the skill created through `/v1/skills`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Returns - `EnvironmentTemplate object { id, capability_directories, created_at, 9 more }` Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. - `id: string` The ID of the reusable environment template. - `capability_directories: array of string` Directories that expose capabilities to the agent. - `created_at: number` The Unix timestamp, in seconds, when the template was created. - `desktop: object { enabled }` Desktop configuration for each OpenAI-hosted environment. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `FileID object { file_id, path, type }` A project-scoped Files API reference resolved separately for each session. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `network: object { access, allowed_domains }` Runtime network access for each OpenAI-hosted environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `object: "agent.environment.template"` The object type. Always `agent.environment.template`. - `"agent.environment.template"` - `packages: object { npm, python, system }` Packages installed in each fresh OpenAI-hosted environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `SkillReference object { skill_id, type, version }` A skill resolved afresh from the Skills API whenever a session starts. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Example ```http curl https://api.openai.com/v1/agents/environments/templates \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "desktop": { "enabled": true }, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ``` ## Delete an agent environment template **delete** `/agents/environments/templates/{environment_template_id}` Deletes reusable environment configuration and all confidential template inputs. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Path Parameters - `environment_template_id: string` ### Returns - `EnvironmentTemplateDeleted object { id, deleted, object }` A deleted reusable environment template. - `id: string` The ID of the deleted environment template. - `deleted: boolean` Whether the environment template was deleted. Always `true`. - `object: "agent.environment.template.deleted"` The object type. Always `agent.environment.template.deleted`. - `"agent.environment.template.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.environment.template.deleted" } ``` ## List agent environment templates **get** `/agents/environments/templates` Lists reusable environment templates without returning confidential values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of EnvironmentTemplate` The resources returned in this page, in the requested sort order. - `id: string` The ID of the reusable environment template. - `capability_directories: array of string` Directories that expose capabilities to the agent. - `created_at: number` The Unix timestamp, in seconds, when the template was created. - `desktop: object { enabled }` Desktop configuration for each OpenAI-hosted environment. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `FileID object { file_id, path, type }` A project-scoped Files API reference resolved separately for each session. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `network: object { access, allowed_domains }` Runtime network access for each OpenAI-hosted environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `object: "agent.environment.template"` The object type. Always `agent.environment.template`. - `"agent.environment.template"` - `packages: object { npm, python, system }` Packages installed in each fresh OpenAI-hosted environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `SkillReference object { skill_id, type, version }` A skill resolved afresh from the Skills API whenever a session starts. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/environments/templates \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "desktop": { "enabled": true }, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent environment template **get** `/agents/environments/templates/{environment_template_id}` Retrieves reusable environment configuration without returning confidential values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Path Parameters - `environment_template_id: string` ### Returns - `EnvironmentTemplate object { id, capability_directories, created_at, 9 more }` Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. - `id: string` The ID of the reusable environment template. - `capability_directories: array of string` Directories that expose capabilities to the agent. - `created_at: number` The Unix timestamp, in seconds, when the template was created. - `desktop: object { enabled }` Desktop configuration for each OpenAI-hosted environment. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `FileID object { file_id, path, type }` A project-scoped Files API reference resolved separately for each session. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `network: object { access, allowed_domains }` Runtime network access for each OpenAI-hosted environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `object: "agent.environment.template"` The object type. Always `agent.environment.template`. - `"agent.environment.template"` - `packages: object { npm, python, system }` Packages installed in each fresh OpenAI-hosted environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `SkillReference object { skill_id, type, version }` A skill resolved afresh from the Skills API whenever a session starts. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Example ```http curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "desktop": { "enabled": true }, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ``` ## Update an agent environment template **post** `/agents/environments/templates/{environment_template_id}` Updates reusable environment configuration without returning confidential values. See [reusing a hosted setup](/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup). ### Path Parameters - `environment_template_id: string` ### Body Parameters - `capability_directories: optional array of string or null` Directories that expose capabilities to the agent. - `desktop: optional object { enabled } or null` Replacement desktop configuration, or null to disable the desktop. - `enabled: boolean` Whether to provision the desktop and its browser proxy. - `env: optional map[string] or null` Replacement confidential environment values. - `files: optional array of HostedEnvironmentFileParam or null` Replacement file configuration materialized for each new session. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: optional string or null` A replacement human-readable display name, or `null` to clear the name. - `network: optional object { access, allowed_domains, blocked_domains } or null` Network access available after setup completes. Omit to preserve the current policy, or pass `null` to reset to the default policy. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: optional array of string or null` Domains the environment may access when network access is restricted. - `blocked_domains: optional array of string or null` Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported. - `packages: optional object { npm, python, system } or null` Packages installed before the runtime network policy applies. - `npm: optional array of string or null` npm packages to install globally. Defaults to an empty list. - `python: optional array of string or null` Python packages to install. Defaults to an empty list. - `system: optional array of string or null` System packages to install. Defaults to an empty list. - `plugins: optional array of HostedPluginParam or null` Replacement plugin configuration installed for each new session. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Replacement confidential setup commands, never included in returned resources. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Replacement skill configuration installed for each new session. - `SkillReference object { skill_id, type, version }` References a skill uploaded through the Skills API. - `skill_id: string` The ID of the skill created through `/v1/skills`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` ### Returns - `EnvironmentTemplate object { id, capability_directories, created_at, 9 more }` Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. - `id: string` The ID of the reusable environment template. - `capability_directories: array of string` Directories that expose capabilities to the agent. - `created_at: number` The Unix timestamp, in seconds, when the template was created. - `desktop: object { enabled }` Desktop configuration for each OpenAI-hosted environment. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `FileID object { file_id, path, type }` A project-scoped Files API reference resolved separately for each session. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `network: object { access, allowed_domains }` Runtime network access for each OpenAI-hosted environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `object: "agent.environment.template"` The object type. Always `agent.environment.template`. - `"agent.environment.template"` - `packages: object { npm, python, system }` Packages installed in each fresh OpenAI-hosted environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `SkillReference object { skill_id, type, version }` A skill resolved afresh from the Skills API whenever a session starts. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Example ```http curl https://api.openai.com/v1/agents/environments/templates/$ENVIRONMENT_TEMPLATE_ID \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "capability_directories": [ "string" ], "created_at": 0, "desktop": { "enabled": true }, "files": [ { "file_id": "file_id", "path": "path", "type": "file_id" } ], "name": "name", "network": { "access": "enabled", "allowed_domains": [ "string" ] }, "object": "agent.environment.template", "packages": { "npm": [ "string" ], "python": [ "string" ], "system": [ "string" ] }, "plugins": [ { "description": "description", "name": "name", "type": "inline" } ], "skills": [ { "skill_id": "skill_id", "type": "skill_reference", "version": "version" } ], "updated_at": 0 } ``` ## Domain Types ### Environment Template - `EnvironmentTemplate object { id, capability_directories, created_at, 9 more }` Reusable configuration that provisions a fresh OpenAI-hosted environment for each session. - `id: string` The ID of the reusable environment template. - `capability_directories: array of string` Directories that expose capabilities to the agent. - `created_at: number` The Unix timestamp, in seconds, when the template was created. - `desktop: object { enabled }` Desktop configuration for each OpenAI-hosted environment. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }` Safe file metadata, excluding contents and session-scoped file IDs. - `FileID object { file_id, path, type }` A project-scoped Files API reference resolved separately for each session. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { path, size_bytes, type }` Metadata for confidential inline file contents. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded size of the inline file in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `name: string or null` An optional human-readable display name for the template. - `network: object { access, allowed_domains }` Runtime network access for each OpenAI-hosted environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `object: "agent.environment.template"` The object type. Always `agent.environment.template`. - `"agent.environment.template"` - `packages: object { npm, python, system }` Packages installed in each fresh OpenAI-hosted environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Safe plugin metadata, excluding inline archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }` Safe skill metadata, preserving unresolved version selectors. - `SkillReference object { skill_id, type, version }` A skill resolved afresh from the Skills API whenever a session starts. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string or null` The requested version selector, including `latest`. - `Inline object { description, name, type }` Safe metadata for an inline skill archive. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `updated_at: number` The Unix timestamp, in seconds, when the template was last updated. ### Environment Template Deleted - `EnvironmentTemplateDeleted object { id, deleted, object }` A deleted reusable environment template. - `id: string` The ID of the deleted environment template. - `deleted: boolean` Whether the environment template was deleted. Always `true`. - `object: "agent.environment.template.deleted"` The object type. Always `agent.environment.template.deleted`. - `"agent.environment.template.deleted"` # Sessions ## Create an agent session **post** `/agents/sessions` Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See [running sessions](/api/docs/guides/agents-api/sessions). ### Body Parameters - `environment: EnvironmentParam` An inline execution environment or a reference to an environment template. - `None object { type }` Runs the agent without an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { type, capability_directories, container_size, 10 more }` An existing OpenAI-hosted environment or new inline/template-based hosted configuration. - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `container_size: optional "small" or "medium" or "large"` The hosted container size. Omission selects the medium tier. - `"small"` - `"medium"` - `"large"` - `desktop: optional object { enabled } or null` Desktop provisioning. Omission or null inherits the template setting, or defaults to disabled. - `enabled: boolean` Whether to provision the desktop and its browser proxy. - `env: optional map[string] or null` Environment variables made available to the agent. - `environment_id: optional string` An existing prewarmed environment. Cannot be combined with a template or inline configuration. - `environment_template_id: optional string` A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy. - `files: optional array of HostedEnvironmentFileParam or null` Files available before the agent starts. Defaults to an empty list. - `FileID object { file_id, path, type }` A file previously uploaded through the OpenAI Files API. - `file_id: string` The ID of the uploaded file. - `path: string` The absolute destination path inside `/workspace`. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { data, path, type }` A file supplied directly as standard-base64 data. - `data: string` The standard-base64-encoded file contents. - `path: string` The absolute destination path inside `/workspace`. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: optional object { access, allowed_domains, blocked_domains } or null` Network access policy for the environment. If omitted, the API version determines whether network access is enabled or disabled. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: optional array of string or null` Domains the environment may access when network access is restricted. - `blocked_domains: optional array of string or null` Domains blocked for both executor and browser when access is restricted. A nonempty list requires `access: restricted` and cannot be combined with nonempty `allowed_domains`. Wildcard domains are not supported. - `packages: optional object { npm, python, system } or null` Packages to install in the environment. Defaults to empty package lists. - `npm: optional array of string or null` npm packages to install globally. Defaults to an empty list. - `python: optional array of string or null` Python packages to install. Defaults to an empty list. - `system: optional array of string or null` System packages to install. Defaults to an empty list. - `plugins: optional array of HostedPluginParam or null` Plugins provided as inline ZIP archives. Defaults to an empty list. - `description: string` The plugin description declared in `.codex-plugin/plugin.json`. - `name: string` The plugin name declared in `.codex-plugin/plugin.json`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `data: string` Standard-base64 encoded ZIP archive bytes. - `media_type: "application/zip"` The archive media type, always `application/zip`. - `"application/zip"` A ZIP archive. - `type: "base64"` The type of the object. Always `base64`. - `"base64"` - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `setup_commands: optional array of SetupCommandParam or null` Ordered, confidential setup commands. Command bodies are never returned. - `command: string` The shell command to execute. - `cwd: optional string or null` The absolute working directory. Defaults to `/workspace`. - `skills: optional array of HostedSkillParam or null` Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list. - `SkillReference object { skill_id, type, version }` References a skill uploaded through the Skills API. - `skill_id: string` The ID of the skill created through `/v1/skills`. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: optional string or null` The skill version, a positive integer or `latest`; omission selects the default. - `Inline object { description, name, source, type }` Supplies a skill ZIP directly in the session request. - `description: string` The skill description declared in `SKILL.md`. - `name: string` The skill name declared in `SKILL.md`. - `source: InlineCapabilitySourceParam` Provides ZIP bytes encoded with standard base64. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `SelfHosted object { type, workspace_directory, capability_directories }` An application-hosted environment configured inline. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` Absolute project directory inside the self-hosted environment. - `capability_directories: optional array of string or null` Directories that contain capabilities exposed to the agent. Defaults to an empty list. - `agent: optional object { instructions, model, multi_agent, 4 more }` Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required. - `instructions: optional string or null` Additional instructions appended to the agent's default base instructions. Omit to leave unchanged. - `model: optional string` The model to use for the agent. The requested model name is preserved. - `multi_agent: optional MultiAgentConfigParam or null` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. - `max_concurrent_subagents: optional number` Maximum number of subagents that may run concurrently. Defaults to 6. - `reasoning: optional AgentReasoningParam or null` Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort. - `effort: optional "none" or "minimal" or "low" or 4 more or null` The amount of reasoning effort the model should use. Omission lets the model select it. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: optional "concise" or "detailed" or "auto" or null` Controls whether the response includes a reasoning summary. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: optional "auto" or "default" or "flex" or 3 more or null` The service tier used for model requests. - `"auto"` Selects the service tier automatically. - `"default"` Uses the default service tier. - `"flex"` Uses the flex service tier. - `"priority"` Uses the priority service tier. - `"fast"` Uses the fast service tier. - `"ultrafast"` Uses the ultrafast service tier. - `text: optional AgentTextParam or null` Configuration for text generated by the agent. - `format: optional TextFormatParam or null` The output format. Omission uses ordinary text (`{"type": "text"}`). - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: optional "low" or "medium" or "high" or null` The amount of text the model should produce. Defaults to `medium`, matching Responses. - `"low"` Produces less text. - `"medium"` Uses the default amount of text. - `"high"` Produces more text. - `tools: optional array of AgentToolParam or null` Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON. - `Function object { description, name, parameters, 2 more }` A function defined by the application. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `defer_loading: optional boolean` Whether this function is deferred and discovered through tool search. Defaults to `false`. - `ToolSearch object { type }` Discovers deferred function tools and loads them into the model context. - `type: "tool_search"` The type of the object. Always `tool_search`. - `"tool_search"` - `ProgrammaticToolCalling object { type, enabled }` Enables calling tools from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `enabled: optional boolean` Whether tools can be called from model-generated code. Defaults to `true`. - `Mcp object { server_label, transport, type, 5 more }` Tools provided by a remote MCP server. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransportParam` The transport used to connect to the MCP server. - `HTTP object { server_url, type, authorization, headers }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `authorization: optional string or null` The authorization value sent to the MCP server, if any. - `headers: optional map[string] or null` Additional HTTP headers sent to the MCP server. - `Stdio object { command, cwd, type, 3 more }` Starts an MCP server as a local process. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `args: optional array of string or null` Arguments passed to the MCP server command. - `env: optional map[string] or null` Environment variables set for the MCP server process. - `env_vars: optional array of string or null` Environment variable names to inherit from the selected execution environment. - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `allowed_tools: optional array of string or null` The MCP tools the agent may call. All server tools are allowed when omitted. - `connection_origin: optional "service" or "environment" or null` Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment. - `"service"` Uses the Managed Agents service network. - `"environment"` Uses the session's execution environment. - `credential_id: optional string or null` The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL. - `request_metadata: optional map[unknown] or null` Metadata included with requests to this MCP server. - `required: optional boolean` Whether this MCP server must initialize before the first turn. Defaults to `false`. - `WebSearch object { type, allowed_domains, context_size, 2 more }` Web search. - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `allowed_domains: optional array of string or null` Domains the search may include. - `context_size: optional "low" or "medium" or "high" or null` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: optional object { city, country, region, timezone } or null` Approximate location used to localize search results. - `city: optional string or null` The city name. - `country: optional string or null` The two-letter ISO country code, such as `US`. - `region: optional string or null` The region or state name. - `timezone: optional string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: optional "disabled" or "cached" or "live" or null` The source used for web search results. Defaults to `live`. - `"disabled"` Disables web search. - `"cached"` Uses cached search results. - `"live"` Searches the live web. - `ComputerUse object { type, include_screenshots }` Browser use in an OpenAI-hosted session. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `include_screenshots: optional boolean` Whether computer tool outputs include screenshots. Defaults to `false`. - `agent_id: optional string` The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged. - `input: optional string or array of AgentSessionInputMessageParam or null` Initial input to submit when the session is created. A string is shorthand for a single user message. Required when `environment.type` is `none`, or when `stream` is `true` for an environment that is not `self_hosted`; optional for self-hosted and non-streaming execution environments. - `string` - `array of AgentSessionInputMessageParam` - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` - `metadata: optional map[string] or null` Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map. - `stream: optional boolean` Whether to stream session events as server-sent events. Defaults to `false`. - `vault_ids: optional array of string or null` The IDs of vaults made available to the session. ### Returns - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Example ```http curl https://api.openai.com/v1/agents/sessions \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "environment": { "type": "none" } }' ``` #### Response ```json { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "request": { "credential_origin": "credential_origin", "fields": [ { "id": "id", "label": "label", "required": true, "type": "type" } ], "options": [ { "id": "id", "field_ids": [ "string" ], "label": "label" } ], "reason": "reason", "type": "browser_authentication" }, "request_id": "request_id", "turn_id": "turn_id", "type": "computer_use_approval_request" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ``` ## Delete an agent session **delete** `/agents/sessions/{session_id}` Removes a managed agent session from the public API and returns a deletion confirmation. If backend execution has ended, deletion can cancel a still-open public turn and abandon unpublished outputs. Running execution must be cancelled first. Physical cleanup may continue asynchronously. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Path Parameters - `session_id: string` ### Returns - `AgentSessionDeleted object { id, deleted, object }` A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously. - `id: string` The ID of the deleted session. - `deleted: boolean` Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress. - `object: "agent.session.deleted"` The object type. Always `agent.session.deleted`. - `"agent.session.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.session.deleted" } ``` ## List agent sessions **get** `/agents/sessions` Lists managed agent sessions using ID-based pagination and the requested sort order. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `agent_id: optional string` Only return sessions whose root agent has this ID. Omit to return sessions for all agents. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSession` The resources returned in this page, in the requested sort order. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "request": { "credential_origin": "credential_origin", "fields": [ { "id": "id", "label": "label", "required": true, "type": "type" } ], "options": [ { "id": "id", "field_ids": [ "string" ], "label": "label" } ], "reason": "reason", "type": "browser_authentication" }, "request_id": "request_id", "turn_id": "turn_id", "type": "computer_use_approval_request" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent session **get** `/agents/sessions/{session_id}` Retrieves the current state of a managed agent session. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Path Parameters - `session_id: string` ### Returns - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "request": { "credential_origin": "credential_origin", "fields": [ { "id": "id", "label": "label", "required": true, "type": "type" } ], "options": [ { "id": "id", "field_ids": [ "string" ], "label": "label" } ], "reason": "reason", "type": "browser_authentication" }, "request_id": "request_id", "turn_id": "turn_id", "type": "computer_use_approval_request" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ``` ## Update an agent session **post** `/agents/sessions/{session_id}` Updates session metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See [managing sessions](/api/docs/guides/agents-api/sessions/manage). ### Path Parameters - `session_id: string` ### Body Parameters - `agent: optional object { model, reasoning, service_tier }` Model settings for subsequent turns. Omitted fields stay unchanged. - `model: optional string` The model for subsequent turns. Omit to keep the current model. - `reasoning: optional object { effort }` Reasoning settings to update. Omit to keep the current effort. - `effort: optional "none" or "minimal" or "low" or 4 more or null` Omit to keep the current effort. Null selects the model's default effort. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `service_tier: optional "auto" or "default" or "flex" or 3 more or null` Omit to keep the current tier. Null resets it to auto. - `"auto"` Selects the service tier automatically. - `"default"` Uses the default service tier. - `"flex"` Uses the flex service tier. - `"priority"` Uses the priority service tier. - `"fast"` Uses the fast service tier. - `"ultrafast"` Uses the ultrafast service tier. - `metadata: optional map[string] or null` Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. ### Returns - `AgentSession object { id, agent, created_at, 9 more }` A Managed Agents session. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent": { "id": "id", "instructions": "instructions", "model": "model", "multi_agent": { "enabled": true, "max_concurrent_subagents": 1 }, "name": "name", "reasoning": { "effort": "none", "summary": "concise" }, "service_tier": "auto", "text": { "format": { "type": "text" }, "verbosity": "low" }, "tools": [ { "defer_loading": true, "description": "description", "name": "name", "parameters": { "foo": "bar" }, "type": "function" } ] }, "created_at": 0, "environment": { "type": "none" }, "error": "error", "last_active_at": 0, "metadata": { "foo": "string" }, "object": "agent.session", "required_actions": [ { "request": { "credential_origin": "credential_origin", "fields": [ { "id": "id", "label": "label", "required": true, "type": "type" } ], "options": [ { "id": "id", "field_ids": [ "string" ], "label": "label" } ], "reason": "reason", "type": "browser_authentication" }, "request_id": "request_id", "turn_id": "turn_id", "type": "computer_use_approval_request" } ], "status": "idle", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 }, "vault_ids": [ "string" ] } ``` # Artifacts ## Retrieve agent session artifact content **get** `/agents/sessions/{session_id}/artifacts/{artifact_id}/content` Downloads immutable session artifact bytes after the execution environment expires. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` - `artifact_id: string` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID/content \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` ## Delete an agent session artifact **delete** `/agents/sessions/{session_id}/artifacts/{artifact_id}` Deletes an immutable session artifact without deleting its live environment file or original Files API object. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` - `artifact_id: string` ### Returns - `SessionArtifactDeleted object { id, deleted, object }` Confirmation that an immutable session artifact was deleted. - `id: string` The ID of the deleted session artifact. - `deleted: boolean` Whether the session artifact was deleted. Always `true`. - `object: "agent.session.artifact.deleted"` The object type. Always `agent.session.artifact.deleted`. - `"agent.session.artifact.deleted"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "agent.session.artifact.deleted" } ``` ## List agent session artifacts **get** `/agents/sessions/{session_id}/artifacts` Lists immutable artifacts published by completed hosted session turns. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `environment_id: optional string or null` Restrict the listing to artifacts produced by this environment. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of SessionArtifact` The resources returned in this page, in the requested sort order. - `id: string` The immutable artifact ID. - `created_at: number` The Unix timestamp, in seconds, when the artifact was published. - `environment_id: string` The ID of the environment that produced the artifact. - `object: "agent.session.artifact"` The object type. Always `agent.session.artifact`. - `"agent.session.artifact"` - `path: string` The original absolute file path in the execution environment. - `session_id: string` The ID of the session that owns the artifact. - `size_bytes: number` The immutable artifact size in bytes. - `turn_id: string` The ID of the completed turn that published the artifact. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "created_at": 0, "environment_id": "environment_id", "object": "agent.session.artifact", "path": "path", "session_id": "session_id", "size_bytes": 0, "turn_id": "turn_id" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent session artifact **get** `/agents/sessions/{session_id}/artifacts/{artifact_id}` Retrieves immutable metadata for one durable session artifact. See [session artifacts](/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts). ### Path Parameters - `session_id: string` - `artifact_id: string` ### Returns - `SessionArtifact object { id, created_at, environment_id, 5 more }` An immutable file published by a completed hosted session turn. - `id: string` The immutable artifact ID. - `created_at: number` The Unix timestamp, in seconds, when the artifact was published. - `environment_id: string` The ID of the environment that produced the artifact. - `object: "agent.session.artifact"` The object type. Always `agent.session.artifact`. - `"agent.session.artifact"` - `path: string` The original absolute file path in the execution environment. - `session_id: string` The ID of the session that owns the artifact. - `size_bytes: number` The immutable artifact size in bytes. - `turn_id: string` The ID of the completed turn that published the artifact. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/artifacts/$ARTIFACT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "environment_id": "environment_id", "object": "agent.session.artifact", "path": "path", "session_id": "session_id", "size_bytes": 0, "turn_id": "turn_id" } ``` ## Domain Types ### Session Artifact - `SessionArtifact object { id, created_at, environment_id, 5 more }` An immutable file published by a completed hosted session turn. - `id: string` The immutable artifact ID. - `created_at: number` The Unix timestamp, in seconds, when the artifact was published. - `environment_id: string` The ID of the environment that produced the artifact. - `object: "agent.session.artifact"` The object type. Always `agent.session.artifact`. - `"agent.session.artifact"` - `path: string` The original absolute file path in the execution environment. - `session_id: string` The ID of the session that owns the artifact. - `size_bytes: number` The immutable artifact size in bytes. - `turn_id: string` The ID of the completed turn that published the artifact. ### Session Artifact Deleted - `SessionArtifactDeleted object { id, deleted, object }` Confirmation that an immutable session artifact was deleted. - `id: string` The ID of the deleted session artifact. - `deleted: boolean` Whether the session artifact was deleted. Always `true`. - `object: "agent.session.artifact.deleted"` The object type. Always `agent.session.artifact.deleted`. - `"agent.session.artifact.deleted"` # Events ## Create agent session input events **post** `/agents/sessions/{session_id}/events` Submits message, cancellation, tool-result, or computer-use approval-response events to a managed agent session. Cancellation can recover a still-open turn whose backend execution has ended by marking it cancelled and abandoning unpublished outputs. Saved results, published files, and existing terminal outcomes are preserved. HTTP 202 confirms acceptance, not durable completion. See [session events](/api/docs/guides/agents-api/sessions/events). ### Header Parameters - `"Idempotency-Key": optional string` ### Path Parameters - `session_id: string` ### Body Parameters - `events: array of AgentSessionInputParam` The input events to submit to the session. - `AgentSessionInputComputerUseApprovalRequestResult object { request_id, response, type }` Responds to a pending Computer Use approval request. - `request_id: string` The registered request ID from the required action. - `response: AgentBrowserAuthenticationSubmitParam or AgentBrowserAuthenticationCancelParam or AgentBrowserOriginAccessParam` The response for this request type. - `AgentBrowserAuthenticationSubmitParam object { action, fields, type, selected_option }` - `action: "submit"` - `"submit"` - `fields: array of object { field_id, value }` Values for up to six active fields in the required action. The submitted field-value mapping and selected option must fit within 120 KiB of JSON. - `field_id: string` The field ID from the required action. - `value: string` The value to enter into the registered control. - `type: "browser_authentication"` - `"browser_authentication"` - `selected_option: optional string or null` The chosen method. Required when the required action contains options. - `AgentBrowserAuthenticationCancelParam object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `AgentBrowserOriginAccessParam object { decision, type }` - `decision: "approve" or "deny" or "cancel"` Whether to allow, deny, or cancel the requested origin access. - `"approve"` Allow the browser to access this origin. - `"deny"` Deny access to this origin. - `"cancel"` Dismiss this request without approving access. - `type: "browser_origin_access"` - `"browser_origin_access"` - `type: "agent.session.input.computer_use_approval_request_result"` The type of the object. Always `agent.session.input.computer_use_approval_request_result`. - `"agent.session.input.computer_use_approval_request_result"` - `AgentSessionInputMessage object { input, type }` Adds one or more user messages and starts a turn. - `input: array of AgentSessionInputMessageParam` The user messages to add to the session. - `content: array of InputContentParam` The content of the message. - `InputText object { text, type }` Text input to the model. - `text: string` The text sent to the model. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input to the model. - `image_url: string` The URL of the image sent to the model. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `role: "user"` The role of the message author. Always `user`. - `"user"` - `type: optional "message"` The type of the input item. Always `message`. - `"message"` - `type: "agent.session.input.message"` The type of the object. Always `agent.session.input.message`. - `"agent.session.input.message"` - `AgentSessionInputCancel object { type }` Cancels the session's active turn. - `type: "agent.session.input.cancel"` The type of the object. Always `agent.session.input.cancel`. - `"agent.session.input.cancel"` - `AgentSessionInputToolResult object { call_id, success, turn_id, 3 more }` Submits the result of a function call. - `call_id: string` The ID of the function call. - `success: boolean` Whether the function call succeeded. - `turn_id: string` The ID of the turn that requested the function call. - `type: "agent.session.input.tool_result"` The type of the object. Always `agent.session.input.tool_result`. - `"agent.session.input.tool_result"` - `error: optional string or null` The error message when the call failed. - `output: optional AgentFunctionCallOutputParam or null` The function result when the call succeeded. - `string` - `array of InputContentParam` - `InputText object { text, type }` Text input to the model. - `InputImage object { image_url, type }` Image input to the model. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "events": [ { "request_id": "request_id", "response": { "action": "submit", "fields": [ { "field_id": "field_id", "value": "value" } ], "type": "browser_authentication" }, "type": "agent.session.input.computer_use_approval_request_result" } ] }' ``` ## Stream agent session events **get** `/agents/sessions/{session_id}/events` Streams live events for an agent session. See [session events](/api/docs/guides/agents-api/sessions/events). ### Path Parameters - `session_id: string` ### Returns - `AgentSessionEvent = AgentSessionErrorEvent or AgentSessionEnvironmentReadyEvent or AgentSessionEnvironmentSuspendedEvent or 30 more` An event emitted by a Managed Agents session. - `AgentSessionErrorEvent object { error, event_id, session_id, type }` Emitted when a turn or session fails. - `error: SessionError` The error that occurred. - `code: string or null` The machine-readable error code, if any. - `message: string` A customer-safe explanation of the error. - `param: string or null` The request parameter associated with the error, if any. - `type: string` The error type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `type: "error"` The type of the object. Always `error`. - `"error"` - `AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 2 more }` Emitted when a hosted session environment is ready to connect. - `environment: AgentSessionEnvironmentState` The current environment state. - `id: string` The public ID of the environment. - `error: object { code, message, type } or null` The error reported while preparing the environment, if any. - `code: string` A machine-readable error code. - `message: string` A human-readable error message. - `type: string` The error type. - `status: "pending" or "ready" or "connected" or 4 more` The environment's connection status. - `"pending"` The environment is being prepared. - `"ready"` The environment is ready to connect. - `"connected"` The environment is connected. - `"disconnected"` The environment is disconnected. - `"suspended"` The environment is stopped and can be resumed from its private checkpoint. - `"expired"` The environment and its private checkpoint have expired. - `"failed"` The environment failed to connect. - `type: string` The environment type. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.ready"` The type of the object. Always `agent.session.environment.ready`. - `"agent.session.environment.ready"` - `AgentSessionEnvironmentSuspendedEvent object { environment, event_id, session_id, 2 more }` Emitted after an idle hosted session environment is checkpointed and stopped. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.suspended"` The type of the object. Always `agent.session.environment.suspended`. - `"agent.session.environment.suspended"` - `AgentSessionEnvironmentExpiredEvent object { environment, event_id, session_id, 2 more }` Emitted after a suspended hosted session environment and its checkpoint expire. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.expired"` The type of the object. Always `agent.session.environment.expired`. - `"agent.session.environment.expired"` - `AgentSessionEnvironmentResetEvent object { environment_id, event_id, reset_count, 3 more }` Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox's files and processes do not. - `environment_id: string` The stable environment ID, retained across sandbox replacements. - `event_id: string` The unique ID of the event. - `reset_count: number` Monotonically increasing reset number. Repeated notifications share this number. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The associated turn, when applicable. - `type: "agent.session.environment.reset"` The type of the object. Always `agent.session.environment.reset`. - `"agent.session.environment.reset"` - `AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 4 more }` Emitted when command execution produces an output delta. - `delta: string` The output text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the command execution item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.output.command_execution_output.delta"` The type of the object. Always `agent.output.command_execution_output.delta`. - `"agent.output.command_execution_output.delta"` - `AgentSessionCreatedEvent object { event_id, session, type }` Emitted when a session is created. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that was created. - `id: string` The ID of the session. - `agent: object { id, instructions, model, 6 more }` The agent running in the session. - `id: string` The ID of the agent. - `instructions: string or null` Custom instructions appended to the agent's default base instructions. - `model: string` The model used by the agent. - `multi_agent: MultiAgentConfig` Configuration for creating and coordinating subagents. - `enabled: boolean` Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents: number or null` Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `name: string or null` The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `reasoning: AgentReasoning` The agent's reasoning configuration. - `effort: "none" or "minimal" or "low" or 4 more or null` The requested reasoning effort, or `null` when the model selects its own default. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `summary: "concise" or "detailed" or "auto" or null` The requested reasoning summary format, or `null` when summaries are disabled. - `"concise"` Returns a concise reasoning summary when supported. - `"detailed"` Returns a detailed reasoning summary when supported. - `"auto"` Automatically selects the most detailed summary supported by the model. - `service_tier: "auto" or "default" or "flex" or 3 more` The effective service-tier policy for model requests. Defaults to `auto`. - `"auto"` - `"default"` - `"flex"` - `"priority"` - `"fast"` - `"ultrafast"` - `text: AgentText` Configuration for text generated by the agent. - `format: TextFormat` The effective output format. Defaults to ordinary text. - `Text object { type }` Generates ordinary text without a structured-output constraint. - `type: "text"` The type of the object. Always `text`. - `"text"` - `JSONSchema object { schema, type }` Constrains generated text to a JSON Schema. - `schema: map[unknown]` The JSON Schema that generated text must match. - `type: "json_schema"` The type of the object. Always `json_schema`. - `"json_schema"` - `verbosity: "low" or "medium" or "high"` The amount of text produced by the agent. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `tools: array of AgentTool` Tools available to the agent. - `Function object { defer_loading, description, name, 2 more }` A function defined by the application. - `defer_loading: boolean` Whether the function is deferred and discovered through tool search. - `description: string` A description of what the function does. - `name: string` The name of the function. - `parameters: map[unknown]` A JSON Schema object describing the function's arguments. - `type: "function"` The type of the object. Always `function`. - `"function"` - `ProgrammaticToolCalling object { enabled, type }` Enables calling tools from model-generated code. - `enabled: boolean` Whether tools can be called from model-generated code. - `type: "programmatic_tool_calling"` The type of the object. Always `programmatic_tool_calling`. - `"programmatic_tool_calling"` - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }` Tools provided by a remote MCP server. - `allowed_tools: array of string or null` The MCP tools the agent may call. - `connection_origin: "service" or "environment"` Where outbound MCP HTTP connections originate. - `"service"` - `"environment"` - `credential_id: string or null` The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `request_metadata: map[unknown]` Metadata included with requests to this MCP server. - `required: boolean` Whether this MCP server must initialize before the first turn. - `server_label: string` A label used to identify the MCP server in tool calls. - `transport: McpTransport` The transport used to connect to the MCP server. - `HTTP object { server_url, type }` Connects to an MCP server over HTTP. - `server_url: string` The URL of the MCP server. - `type: "http"` The type of the object. Always `http`. - `"http"` - `Stdio object { args, command, cwd, 2 more }` Starts an MCP server as a local process. - `args: array of string` Arguments passed to the MCP server command. - `command: string` The command used to start the MCP server. - `cwd: string` The working directory used to start the MCP server. - `env_vars: array of string` Environment variable names inherited from the execution environment. - `type: "stdio"` The type of the object. Always `stdio`. - `"stdio"` - `type: "mcp"` The type of the object. Always `mcp`. - `"mcp"` - `WebSearch object { allowed_domains, context_size, location, 2 more }` Web search. - `allowed_domains: array of string or null` Allowed search domains, or `null` when the search is unrestricted. - `context_size: "low" or "medium" or "high"` The amount of search context made available to the model. Defaults to `medium`. - `"low"` - `"medium"` - `"high"` - `location: object { city, country, region, timezone } or null` Approximate location used to localize search results, if provided. - `city: string or null` The city name. - `country: string or null` The two-letter ISO country code, such as `US`. - `region: string or null` The region or state name. - `timezone: string or null` The IANA timezone, such as `America/Los_Angeles`. - `mode: "disabled" or "cached" or "live"` The source used for web search results. - `"disabled"` - `"cached"` - `"live"` - `type: "web_search"` The type of the object. Always `web_search`. - `"web_search"` - `ComputerUse object { include_screenshots, type }` Browser use in an OpenAI-hosted session. - `include_screenshots: boolean` Whether computer tool outputs include screenshots. - `type: "computer_use"` The type of the object. Always `computer_use`. - `"computer_use"` - `created_at: number` The Unix timestamp, in seconds, when the session was created. - `environment: Environment` The execution environment for the session. - `None object { type }` The session talks to CCA without selecting or provisioning an execution environment. - `type: "none"` The type of the object. Always `none`. - `"none"` - `OpenAIHosted object { id, capability_directories, desktop, 7 more }` An environment hosted by OpenAI. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `desktop: object { enabled }` The effective desktop configuration. - `enabled: boolean` Whether the environment provisions a desktop and browser proxy. - `files: array of HostedEnvironmentFile` Files available in the environment, excluding their contents. - `HostedEnvironmentFileID object { id, file_id, path, 2 more }` A file copied from the OpenAI Files API. - `id: string` The session-scoped ID of the file in the execution environment. - `file_id: string` The ID of the uploaded file. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "file_id"` The type of the object. Always `file_id`. - `"file_id"` - `Inline object { id, path, size_bytes, type }` A file supplied inline when the session was created. - `id: string` The session-scoped ID of the file in the execution environment. - `path: string` The file's absolute path inside the environment. - `size_bytes: number` The decoded file size in bytes. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `network: object { access, allowed_domains }` The effective network access policy for the environment. - `access: "enabled" or "disabled" or "restricted"` The environment's network access mode. - `"enabled"` Allows unrestricted network access. - `"disabled"` Disables network access. - `"restricted"` Applies the configured domain restrictions. - `allowed_domains: array of string` Domains the environment may access when network access is restricted. - `packages: object { npm, python, system }` Packages installed in the environment. - `npm: array of string` npm packages installed globally in the environment. - `python: array of string` Python packages installed in the environment. - `system: array of string` System packages installed in the environment. - `plugins: array of HostedPlugin` Plugins installed in the environment, excluding their archive contents. - `description: string` The installed plugin description. - `name: string` The installed plugin name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `skills: array of HostedSkill` Skills installed in the environment, excluding their archive contents. - `HostedSkillReference object { description, name, skill_id, 2 more }` A skill installed from the Skills API. - `description: string` The installed skill description. - `name: string` The installed skill name. - `skill_id: string` The referenced skill ID. - `type: "skill_reference"` The type of the object. Always `skill_reference`. - `"skill_reference"` - `version: string` The concrete skill version installed for this session. - `Inline object { description, name, type }` A skill installed from an inline ZIP archive. - `description: string` The installed skill description. - `name: string` The installed skill name. - `type: "inline"` The type of the object. Always `inline`. - `"inline"` - `type: "openai_hosted"` The type of the object. Always `openai_hosted`. - `"openai_hosted"` - `container_size: optional "small" or "medium" or "large" or null` The effective CPU and memory tier, or null when unknown or outside the public tiers. - `"small"` - `"medium"` - `"large"` - `SelfHosted object { id, capability_directories, remote_url, 2 more }` An environment hosted by the application. - `id: string` The public ID of the environment. - `capability_directories: array of string` Directories that contain capabilities exposed to the agent. - `remote_url: string` Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `type: "self_hosted"` The type of the object. Always `self_hosted`. - `"self_hosted"` - `workspace_directory: string` The absolute project directory inside the environment. Defaults to `/workspace`. - `error: string or null` The error that caused the session to fail, if any. - `last_active_at: number` The Unix timestamp, in seconds, when the session was last active. - `metadata: map[string]` Custom string key-value pairs attached to the session. - `object: "agent.session"` The object type. Always `agent.session`. - `"agent.session"` - `required_actions: array of ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }` Actions that must be completed before the session can continue. - `ComputerUseApprovalRequest object { request, request_id, turn_id, type }` Respond to a computer-use request. - `request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }` The information needed to render the request. - `BrowserAuthentication object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `BrowserOriginAccess object { origin, reason, type }` A browser origin awaiting the application's approval decision. - `origin: string` The origin the browser needs permission to access. - `reason: string or null` The browser's explanation for this request, or null when unavailable. - `type: "browser_origin_access"` The type of the object. Always `browser_origin_access`. - `"browser_origin_access"` - `request_id: string` The registered request ID to echo when responding. - `turn_id: string` The turn that requested approval. - `type: "computer_use_approval_request"` The type of the object. Always `computer_use_approval_request`. - `"computer_use_approval_request"` - `FunctionCall object { arguments, call_id, name, 2 more }` Run a function tool and submit its result. - `arguments: unknown` The arguments supplied by the model. - `call_id: string` The ID to include when submitting the function result. - `name: string` The function name. - `turn_id: string` The ID of the turn that requested the function call. - `type: "function_call"` The type of the object. Always `function_call`. - `"function_call"` - `EnvironmentConnection object { environment_id, type }` Reconnect a session environment. - `environment_id: string` The ID of the environment to reconnect. - `type: "environment_connection"` The type of the object. Always `environment_connection`. - `"environment_connection"` - `status: "idle" or "in_progress" or "requires_action" or "failed"` The current status of the session. - `"idle"` The session has no turn in progress and is ready for input. A hosted environment may still be provisioning. - `"in_progress"` The session is processing a turn. - `"requires_action"` The session is waiting for one or more required actions. - `"failed"` The session failed. - `usage: TokenUsage or null` Best-effort token usage for the session, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `vault_ids: array of string` The IDs of vaults made available to the session. - `type: "agent.session.created"` The type of the object. Always `agent.session.created`. - `"agent.session.created"` - `AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn is created. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it was created. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.created"` The type of the object. Always `agent.session.turn.created`. - `"agent.session.turn.created"` - `AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 2 more }` Emitted when a turn starts running. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The turn at the time it started running. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.in_progress"` The type of the object. Always `agent.session.turn.in_progress`. - `"agent.session.turn.in_progress"` - `AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn completes. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The completed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.completed"` The type of the object. Always `agent.session.turn.completed`. - `"agent.session.turn.completed"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. - `AgentSessionTurnFailedEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn fails. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The failed turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.failed"` The type of the object. Always `agent.session.turn.failed`. - `"agent.session.turn.failed"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. - `AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 3 more }` Emitted when a turn is cancelled. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn: Turn` The cancelled turn. - `turn_id: string` The ID of the turn associated with the event. - `type: "agent.session.turn.cancelled"` The type of the object. Always `agent.session.turn.cancelled`. - `"agent.session.turn.cancelled"` - `usage: TokenUsage or null` Token usage by the root agent during the turn, when available. - `AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 3 more }` Emitted when an item is added to a turn. - `event_id: string` The unique ID of the event. - `item: AgentSessionItem` The item that was added. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `output_index: number or null` The index of the item in the turn output, when the item is agent output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.added"` The type of the object. Always `agent.session.turn.item.added`. - `"agent.session.turn.item.added"` - `AgentSessionIdleEvent object { event_id, session, type }` Emitted when a session becomes idle. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that became idle. - `type: "agent.session.idle"` The type of the object. Always `agent.session.idle`. - `"agent.session.idle"` - `AgentSessionInProgressEvent object { event_id, session, type }` Emitted when a session starts processing a turn. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session that started processing. - `type: "agent.session.in_progress"` The type of the object. Always `agent.session.in_progress`. - `"agent.session.in_progress"` - `AgentSessionRequiresActionEvent object { event_id, session, type }` Emitted when a session is waiting for one or more required actions. - `event_id: string` The unique ID of the event. - `session: AgentSession` The session and its current required actions. - `type: "agent.session.requires_action"` The type of the object. Always `agent.session.requires_action`. - `"agent.session.requires_action"` - `AgentSessionFailedEvent object { event_id, session, type }` Emitted when a session fails. - `event_id: string` The unique ID of the event. - `session: AgentSession` The failed session. - `type: "agent.session.failed"` The type of the object. Always `agent.session.failed`. - `"agent.session.failed"` - `AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 2 more }` Emitted while a session environment is being prepared. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.pending"` The type of the object. Always `agent.session.environment.pending`. - `"agent.session.environment.pending"` - `AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment connects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.connected"` The type of the object. Always `agent.session.environment.connected`. - `"agent.session.environment.connected"` - `AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment disconnects. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.disconnected"` The type of the object. Always `agent.session.environment.disconnected`. - `"agent.session.environment.disconnected"` - `AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 2 more }` Emitted when a session environment fails. - `environment: AgentSessionEnvironmentState` The current environment state. - `event_id: string` The unique ID of the event. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.environment.failed"` The type of the object. Always `agent.session.environment.failed`. - `"agent.session.environment.failed"` - `AgentSessionSubagentCreatedEvent object { event_id, subagent, type }` Emitted when a subagent is created. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was created. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `type: "agent.session.subagent.created"` The type of the object. Always `agent.session.subagent.created`. - `"agent.session.subagent.created"` - `AgentSessionSubagentActiveEvent object { event_id, subagent, type }` Emitted when a closed subagent successfully resumes. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that resumed. - `type: "agent.session.subagent.active"` The type of the object. Always `agent.session.subagent.active`. - `"agent.session.subagent.active"` - `AgentSessionSubagentClosedEvent object { event_id, subagent, type }` Emitted when a subagent is closed. - `event_id: string` The unique ID of the event. - `subagent: Subagent` The subagent that was closed. - `type: "agent.session.subagent.closed"` The type of the object. Always `agent.session.subagent.closed`. - `"agent.session.subagent.closed"` - `AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 3 more }` Emitted when an output item is complete. - `event_id: string` The unique ID of the event. - `item: AgentOutputItem` The completed output item. - `AgentSessionAssistantMessage object { id, content, phase, 4 more }` An assistant message produced by the agent. - `id: string` The ID of the message. - `content: array of OutputText` The content of the message. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `phase: "commentary" or "final_answer" or null` The phase of the assistant message. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "assistant"` The role of the message author. Always `assistant`. - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `output_index: number` The index of the output item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.item.done"` The type of the object. Always `agent.session.turn.item.done`. - `"agent.session.turn.item.done"` - `AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output text content part is added. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The initial content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.added"` The type of the object. Always `agent.session.turn.content_part.added`. - `"agent.session.turn.content_part.added"` - `AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output content part is complete. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `part: OutputText` The completed content part. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.content_part.done"` The type of the object. Always `agent.session.turn.content_part.done`. - `"agent.session.turn.content_part.done"` - `AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 5 more }` Emitted when text is appended to an output text content part. - `content_index: number` The index of the content part in the message. - `delta: string` The text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.delta"` The type of the object. Always `agent.session.turn.output_text.delta`. - `"agent.session.turn.output_text.delta"` - `AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 5 more }` Emitted when an output text content part is complete. - `content_index: number` The index of the content part in the message. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the message item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `text: string` The complete output text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.output_text.done"` The type of the object. Always `agent.session.turn.output_text.done`. - `"agent.session.turn.output_text.done"` - `AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 5 more }` Emitted when a reasoning summary content part is added. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The initial summary part. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.added"` The type of the object. Always `agent.session.turn.reasoning_summary_part.added`. - `"agent.session.turn.reasoning_summary_part.added"` - `AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 6 more }` Emitted when a reasoning summary part is complete. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `part: SummaryText` The completed summary part. - `session_id: string` The ID of the session associated with the event. - `status: "incomplete" or null` Present as `incomplete` when summary generation was interrupted. - `"incomplete"` - `summary_index: number` The index of the summary part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_part.done"` The type of the object. Always `agent.session.turn.reasoning_summary_part.done`. - `"agent.session.turn.reasoning_summary_part.done"` - `AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 5 more }` Emitted when text is appended to a reasoning summary. - `delta: string` The summary text that was appended. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.delta"` The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`. - `"agent.session.turn.reasoning_summary_text.delta"` - `AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 5 more }` Emitted when a reasoning summary content part is complete. - `event_id: string` The unique ID of the event. - `item_id: string` The ID of the reasoning item. - `output_index: number` The index of the item in the turn output. - `session_id: string` The ID of the session associated with the event. - `summary_index: number` The index of the summary content part. - `text: string` The complete reasoning summary text. - `turn_id: string or null` The ID of the turn associated with the event, when applicable. - `type: "agent.session.turn.reasoning_summary_text.done"` The type of the object. Always `agent.session.turn.reasoning_summary_text.done`. - `"agent.session.turn.reasoning_summary_text.done"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/events \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` # Items ## List agent session items **get** `/agents/sessions/{session_id}/items` Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history. See [inspecting agent output](/api/docs/guides/agents-api/observability). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSessionItem` The resources returned in this page, in the requested sort order. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/items \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "content": [ { "text": "text", "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "turn_id": "turn_id", "type": "message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` # Subagents ## List session subagents **get** `/agents/sessions/{session_id}/subagents` Lists subagents in a session, including nested and closed subagents. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Subagent` The resources returned in this page, in the requested sort order. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "closed_at": 0, "instructions": [ { "text": "text", "type": "output_text" } ], "name": "name", "object": "agent.session.subagent", "opened_at": 0, "parent_agent_id": "parent_agent_id", "session_id": "session_id", "status": "active" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a session subagent **get** `/agents/sessions/{session_id}/subagents/{subagent_id}` Retrieves a subagent belonging to this session. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` ### Returns - `Subagent object { id, closed_at, instructions, 6 more }` A subagent created within a session. - `id: string` The ID of the subagent. - `closed_at: number or null` The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume. - `instructions: array of AgentContent or null` Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `name: string or null` The runner-assigned nickname, or null when unavailable. - `object: "agent.session.subagent"` The object type. Always `agent.session.subagent`. - `"agent.session.subagent"` - `opened_at: number` The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it. - `parent_agent_id: string` The ID of the agent that created this subagent. - `session_id: string` The ID of the session that owns the subagent. - `status: "active" or "closed"` The current status of the subagent. - `"active"` The subagent remains available, including while idle between turns. - `"closed"` The subagent is closed. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "closed_at": 0, "instructions": [ { "text": "text", "type": "output_text" } ], "name": "name", "object": "agent.session.subagent", "opened_at": 0, "parent_agent_id": "parent_agent_id", "session_id": "session_id", "status": "active" } ``` # Items ## List subagent items **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/items` Lists this subagent's own items across all of its turns. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSessionItem` The resources returned in this page, in the requested sort order. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/items \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "content": [ { "text": "text", "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "turn_id": "turn_id", "type": "message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` # Turns ## List subagent turns **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/turns` Lists all turns of this subagent, including turns after a resume. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Turn` The resources returned in this page, in the requested sort order. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a subagent turn **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}` Retrieves a turn belonging to this subagent. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` - `turn_id: string` ### Returns - `Turn object { id, agent_id, completed_at, 8 more }` The canonical public representation of a session turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns/$TURN_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ``` # Items ## List subagent turn items **get** `/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items` Lists items belonging to one turn of this subagent. See [subagent workflows](/api/docs/guides/agents-api/multi-agent). ### Path Parameters - `session_id: string` - `subagent_id: string` - `turn_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSessionItem` The resources returned in this page, in the requested sort order. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/turns/$TURN_ID/items \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "content": [ { "text": "text", "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "turn_id": "turn_id", "type": "message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` # Traces ## List agent session traces **get** `/agents/sessions/{session_id}/traces` Lists published root-turn traces as OTLP JSON, ordered by turn creation time and ID. Unpublished traces are skipped. Each page returns data available when read; it does not wait for late traces. Trace reads and the JSON response are limited to 16 MiB per request. If the limit is exceeded, request fewer traces. ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of SessionTrace` The resources returned in this page, in the requested sort order. - `id: string` The root turn ID. Use this ID as the pagination anchor. - `created_at: number` The Unix timestamp in seconds when the root turn was created. - `object: "agent.session.trace"` The object type, which is always `agent.session.trace`. - `"agent.session.trace"` - `otlp: map[unknown]` An OTLP JSON ExportTraceServiceRequest containing resourceSpans. Only currently published data is returned; later trace updates are not awaited. - `session_id: string` The session that owns this trace. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/traces \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "created_at": 0, "object": "agent.session.trace", "otlp": { "foo": "bar" }, "session_id": "session_id" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Domain Types ### Session Trace - `SessionTrace object { id, created_at, object, 2 more }` - `id: string` The root turn ID. Use this ID as the pagination anchor. - `created_at: number` The Unix timestamp in seconds when the root turn was created. - `object: "agent.session.trace"` The object type, which is always `agent.session.trace`. - `"agent.session.trace"` - `otlp: map[unknown]` An OTLP JSON ExportTraceServiceRequest containing resourceSpans. Only currently published data is returned; later trace updates are not awaited. - `session_id: string` The session that owns this trace. # Turns ## List agent session turns **get** `/agents/sessions/{session_id}/turns` Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order. See [session turns](/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). ### Path Parameters - `session_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of Turn` The resources returned in this page, in the requested sort order. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve an agent session turn **get** `/agents/sessions/{session_id}/turns/{turn_id}` Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session. See [session turns](/api/docs/guides/agents-api/sessions/manage#inspect-session-turns). ### Path Parameters - `session_id: string` - `turn_id: string` ### Returns - `Turn object { id, agent_id, completed_at, 8 more }` The canonical public representation of a session turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns/$TURN_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "completed_at": 0, "created_at": 0, "error": { "code": "context_length_exceeded", "message": "message" }, "object": "agent.session.turn", "session_id": "session_id", "started_at": 0, "status": "queued", "subagent_id": "subagent_id", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 0 } } ``` ## Domain Types ### Turn - `Turn object { id, agent_id, completed_at, 8 more }` The canonical public representation of a session turn. - `id: string` The ID of the turn. - `agent_id: string` The ID of the agent that ran the turn. - `completed_at: number or null` The Unix timestamp, in seconds, when the turn reached a terminal state. - `created_at: number` The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable. - `error: SessionTurnError or null` A customer-safe error. Non-null only for a failed turn. - `code: "context_length_exceeded" or "session_budget_exceeded" or "usage_limit_exceeded" or 20 more` A stable, machine-readable failure category. - `"context_length_exceeded"` The request exceeds the model's context window. - `"session_budget_exceeded"` The session has reached its usage budget. - `"usage_limit_exceeded"` The organization has reached a usage, plan, or billing limit. - `"project_spend_limit_exceeded"` The project has reached its enforced spend limit. - `"organization_spend_limit_exceeded"` The organization has reached its enforced spend limit. - `"organization_usage_limit_exceeded"` The organization has reached its OpenAI-assigned usage limit. - `"billing_not_active"` Billing is not active for the account. - `"credit_balance_exhausted"` The organization has no API credits remaining. - `"rate_limit_exceeded"` The request exceeds the available rate limit. - `"flex_unavailable"` Flex processing is temporarily unavailable. - `"server_overloaded"` The model service is temporarily overloaded. - `"cyber_policy"` The request was rejected by a safety policy. - `"misalignment_policy_violation"` The request was blocked by the safety systems. - `"connection_failed"` The request could not connect to the model service. - `"server_error"` The model service encountered an unexpected error. - `"authentication_error"` The API credentials are invalid or lack the required access. - `"invalid_request"` The request contains invalid input or configuration. - `"resource_not_found"` The requested model or resource is unavailable. - `"sandbox_error"` The request could not complete in its execution environment. - `"executor_version_incompatible"` The executor must be upgraded before it can run this turn. - `"active_turn_not_steerable"` The session cannot accept additional input while a request is running. - `"request_timeout"` The request timed out before the model service responded. - `"internal_error"` An unexpected internal error prevented the session request from completing. - `message: string` A customer-safe explanation of the failure. - `object: "agent.session.turn"` The object type. Always `agent.session.turn`. - `"agent.session.turn"` - `session_id: string` The ID of the session that owns the turn. - `started_at: number or null` The Unix timestamp, in seconds, when the turn started. - `status: "queued" or "in_progress" or "waiting" or 3 more` The current status of the turn. - `"queued"` The turn is waiting to start. - `"in_progress"` The turn is in progress. - `"waiting"` The turn is waiting for external input. - `"completed"` The turn completed successfully. - `"failed"` The turn failed. - `"cancelled"` The turn was cancelled. - `subagent_id: string or null` The ID of the subagent that ran the turn, if applicable. - `usage: TokenUsage or null` Best-effort token usage for the turn, or null if unknown. Recorded usage may change. - `input_tokens: number` The number of input tokens used by the agent. - `input_tokens_details: object { cached_tokens }` A breakdown of the agent's input token usage. - `cached_tokens: number` The number of input tokens retrieved from the prompt cache. - `output_tokens: number` The number of output tokens generated by the agent. - `output_tokens_details: object { reasoning_tokens }` A breakdown of the agent's output token usage. - `reasoning_tokens: number` The number of output tokens used for reasoning. - `total_tokens: number` The total number of input and output tokens used by the agent. # Items ## List agent session turn items **get** `/agents/sessions/{session_id}/turns/{turn_id}/items` Lists items belonging to one root-agent turn, including its interactions with subagents. See [inspecting agent output](/api/docs/guides/agents-api/observability). ### Path Parameters - `session_id: string` - `turn_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. ### Returns - `data: array of AgentSessionItem` The resources returned in this page, in the requested sort order. - `AgentSessionMessage object { id, content, phase, 4 more }` A user or assistant message recorded in a session. - `id: string or null` The ID of this item, or null for legacy user messages whose ID was not recorded. - `content: array of AgentSessionMessageContent` The content of the message. User messages contain input text or images; assistant messages contain output text. - `InputText object { text, type }` Text supplied by the user. - `text: string` The text supplied by the user. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` An image supplied by the user. - `image_url: string` The URL of the image supplied by the user, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `OutputText object { text, type }` Text produced by the assistant. - `text: string` The text produced by the assistant. - `type: "output_text"` The type of the object. Always `output_text`. - `"output_text"` - `phase: "commentary" or "final_answer" or null` The phase of an assistant message. Null for user messages. - `"commentary"` Commentary produced while the agent works. - `"final_answer"` The agent's final answer. - `role: "user" or "assistant"` The role of the message author. - `"user"` - `"assistant"` - `status: AgentOutputItemStatus` The status of the message. User messages are always `completed`. - `"in_progress"` The item is in progress. - `"completed"` The item is complete. - `"incomplete"` The item stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "message"` The item type. Always `message`. - `"message"` - `AgentReasoningItem object { id, status, summary, 2 more }` A reasoning item produced by the agent. - `id: string` The ID of the reasoning item. - `status: AgentOutputItemStatus or null` The status of the reasoning item. - `summary: array of SummaryText` The reasoning summaries produced by the agent. - `text: string` The reasoning summary text. - `type: "summary_text"` The content type. Always `summary_text`. - `"summary_text"` - `turn_id: string` The ID of the turn that contains this item. - `type: "reasoning"` The item type. Always `reasoning`. - `"reasoning"` - `AgentFunctionCallItem object { id, arguments, call_id, 4 more }` A function call produced by the agent. - `id: string` The ID of the function call item. - `arguments: unknown` The arguments to pass to the function. - `call_id: string` The ID used to submit the function result. - `name: string` The name of the function to call. - `status: AgentFunctionCallStatus` The status of the function call. - `"in_progress"` The call is in progress. - `"completed"` The call completed successfully. - `"failed"` The call failed. - `"incomplete"` The call stopped before completing. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call"` The item type. Always `function_call`. - `"function_call"` - `FunctionCallOutput object { id, call_id, error, 4 more }` The result supplied for a function call. - `id: string` The ID of the function call output item. - `call_id: string` The ID of the function call that produced this output. - `error: string or null` The error message, if the call failed. - `output: AgentFunctionCallOutput or null` The function result, if the call succeeded. - `string` - `array of InputContent` - `InputText object { text, type }` Text input recorded in a session item. - `text: string` The text supplied to the agent. - `type: "input_text"` The type of the object. Always `input_text`. - `"input_text"` - `InputImage object { image_url, type }` Image input recorded in a session item. - `image_url: string` The URL of the image supplied to the agent, which may be a base64-encoded data URL. - `type: "input_image"` The type of the object. Always `input_image`. - `"input_image"` - `status: AgentFunctionCallStatus` The status of the function call. - `turn_id: string` The ID of the turn that contains this item. - `type: "function_call_output"` The item type. Always `function_call_output`. - `"function_call_output"` - `AgentMessage object { id, content, recipient_agent_id, 3 more }` A message exchanged between agent threads. - `id: string` The ID of the message. - `content: array of AgentContent` The content exchanged between the agents. - `OutputText object { text, type }` A text content part produced by the agent. - `text: string` The text produced by the agent. - `type: "output_text"` The content type. Always `output_text`. - `"output_text"` - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `encrypted_content: string` The encrypted content payload. - `type: "encrypted_content"` The content type. Always `encrypted_content`. - `"encrypted_content"` - `recipient_agent_id: string` The ID or name of the receiving agent. - `sender_agent_id: string` The ID or name of the sending agent. - `turn_id: string` The ID of the turn that contains this item. - `type: "agent_message"` The item type. Always `agent_message`. - `"agent_message"` - `AgentMcpCallItem object { id, arguments, error, 6 more }` A call to a tool on an MCP server. - `id: string` The ID of the MCP call item. - `arguments: unknown` The arguments passed to the MCP tool. - `error: unknown` The error returned by the MCP tool, if any. - `name: string` The name of the MCP tool. - `output: unknown` The output returned by the MCP tool, if any. - `server_label: string` The label of the MCP server. - `status: AgentFunctionCallStatus` The status of the MCP tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "mcp_call"` The item type. Always `mcp_call`. - `"mcp_call"` - `ComputerUseCall object { id, output, status, 3 more }` One execution of the platform-provided computer-use capability. - `id: string` The ID of the activity item. - `output: object { image_url, type } or null` The last screenshot emitted by the model. Null when screenshot inclusion is disabled or the call emitted no screenshot. - `image_url: string` The complete JPEG image as a base64 data URL. - `type: "computer_screenshot"` The content type. Always `computer_screenshot`. - `"computer_screenshot"` - `status: AgentFunctionCallStatus` The execution status of the activity. - `title: string or null` A model-generated description of the activity, when available. - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_call"` The item type. Always `computer_use_call`. - `"computer_use_call"` - `ComputerUseApprovalRequest object { id, request, request_id, 2 more }` A credential-free history record of the emitted login request. - `id: string` The stable history item ID. - `request: object { credential_origin, fields, options, 2 more }` A registered form awaiting the application's response. - `credential_origin: string or null` The registered form or frame origin where values will be entered. - `fields: array of object { id, label, required, type }` Controls to render. All submitted values are sensitive. - `id: string` The field ID to submit as field_id in a fields entry. - `label: string` The label to display beside the control. - `required: boolean` Whether this control requires a nonempty value. - `type: string` The rendering type, such as email, password, or text. - `options: array of object { id, field_ids, label }` Sign-in methods. Empty for a plain form. - `id: string` The option ID to submit as selected_option. - `field_ids: array of string` IDs from the registered fields that this method accepts. - `label: string` The method label to display. - `reason: string or null` Why the agent needs the user to sign in. - `type: "browser_authentication"` The type of the object. Always `browser_authentication`. - `"browser_authentication"` - `request_id: string` - `turn_id: string` - `type: "computer_use_approval_request"` The item type. Always computer_use_approval_request. - `"computer_use_approval_request"` - `ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }` A credential-free record of an admitted response, not proof of completion. - `id: string` The stable history item ID. - `request_id: string` The registered request answered by this item. - `response: Submit { action, selected_option, type } or Cancel { action, type }` The admitted response, without submitted credential values. - `Submit object { action, selected_option, type }` - `action: "submit"` - `"submit"` - `selected_option: string or null` The chosen sign-in method, or null when no options were offered. - `type: "browser_authentication"` - `"browser_authentication"` - `Cancel object { action, type }` - `action: "cancel"` - `"cancel"` - `type: "browser_authentication"` - `"browser_authentication"` - `turn_id: string` The ID of the turn that contains this item. - `type: "computer_use_approval_request_result"` - `"computer_use_approval_request_result"` - `AgentWebSearchCallItem object { id, action, status, 2 more }` A web search call produced by the agent. - `id: string` The ID of the web search call. - `action: WebSearchAction or null` The action performed by the web search tool. - `Search object { queries, query, type }` A search query or group of search queries. - `queries: array of string or null` The search queries, when multiple queries were used. - `query: string or null` The search query, when a single query was used. - `type: "search"` The type of the object. Always `search`. - `"search"` - `OpenPage object { type, url }` Opens a web page. - `type: "open_page"` The type of the object. Always `open_page`. - `"open_page"` - `url: string or null` The URL of the page that was opened. - `FindInPage object { pattern, type, url }` Finds text within a web page. - `pattern: string or null` The text pattern that was searched for. - `type: "find_in_page"` The type of the object. Always `find_in_page`. - `"find_in_page"` - `url: string or null` The URL of the page that was searched. - `Other object { type }` Another web search action. - `type: "other"` The type of the object. Always `other`. - `"other"` - `status: AgentOutputItemStatus` The status of the web search call. - `turn_id: string` The ID of the turn that contains this item. - `type: "web_search_call"` The item type. Always `web_search_call`. - `"web_search_call"` - `AgentCommandExecutionItem object { id, command, cwd, 6 more }` A command execution produced by the agent. - `id: string` The ID of the command execution item. - `command: string` The command that was executed. - `cwd: string or null` The working directory used to execute the command. - `duration_ms: number or null` The command duration in milliseconds. - `exit_code: number or null` The process exit code, if the command completed. - `output: string or null` The command output, if available. - `status: AgentFunctionCallStatus` The status of the command execution. - `turn_id: string` The ID of the turn that contains this item. - `type: "command_execution"` The item type. Always `command_execution`. - `"command_execution"` - `AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }` A request to spawn a subagent. - `id: string` The ID of the tool call item. - `agent_id: string` The ID of the agent that requested the subagent. - `content: array of AgentContent` The task given to the spawned agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `model: string or null` The model requested for the spawned agent. - `reasoning_effort: string or null` The reasoning effort requested for the spawned agent. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "create_subagent_call"` The item type. Always `create_subagent_call`. - `"create_subagent_call"` The current public item type. - `AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }` A request to send input to another agent. - `id: string` The ID of the tool call item. - `content: array of AgentContent` The input sent to the receiving agent. - `OutputText object { text, type }` A text content part produced by the agent. - `EncryptedContent object { encrypted_content, type }` Encrypted content exchanged between agents. - `recipient_agent_id: string` The ID of the agent receiving the input. - `sender_agent_id: string` The ID of the agent sending the input. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "send_subagent_input_call"` The item type. Always `send_subagent_input_call`. - `"send_subagent_input_call"` The current public item type. - `AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to resume a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to resume. - `sender_agent_id: string` The ID of the agent requesting the resume. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "resume_subagent_call"` The item type. Always `resume_subagent_call`. - `"resume_subagent_call"` The current public item type. - `AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }` A request to wait for one or more subagents. - `id: string` The ID of the tool call item. - `recipient_agent_ids: array of string` The IDs of the agents to wait for. - `sender_agent_id: string` The ID of the agent waiting for results. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "wait_for_subagents_call"` The item type. Always `wait_for_subagents_call`. - `"wait_for_subagents_call"` The current public item type. - `AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to interrupt a subagent's current turn. The subagent remains available. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to interrupt. - `sender_agent_id: string` The ID of the agent requesting the interrupt. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "interrupt_subagent_call"` The item type. Always `interrupt_subagent_call`. - `"interrupt_subagent_call"` The current public item type. - `AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }` A request to close a subagent. - `id: string` The ID of the tool call item. - `recipient_agent_id: string` The ID of the agent to close. - `sender_agent_id: string` The ID of the agent requesting the close. - `status: AgentFunctionCallStatus` The status of the tool call. - `turn_id: string` The ID of the turn that contains this item. - `type: "close_subagent_call"` The item type. Always `close_subagent_call`. - `"close_subagent_call"` The current public item type. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns/$TURN_ID/items \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "content": [ { "text": "text", "type": "input_text" } ], "phase": "commentary", "role": "user", "status": "in_progress", "turn_id": "turn_id", "type": "message" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` # Vaults ## Create a vault **post** `/vaults` Creates a vault for the current project. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Body Parameters - `metadata: optional map[string] or null` Key-value pairs to associate with the vault, such as an application or team identifier. - `name: optional string` The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. ### Returns - `Vault object { id, created_at, metadata, 2 more }` A collection of credentials for MCP servers and OpenAI-hosted environments. - `id: string` The ID of the vault. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `metadata: map[string]` Key-value pairs associated with the vault, such as an application or team identifier. - `name: string or null` The human-readable name of the vault, if set. - `object: "vault"` The object type. Always `vault`. - `"vault"` ### Example ```http curl https://api.openai.com/v1/vaults \ -X POST \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault" } ``` ## Delete a vault **delete** `/vaults/{vault_id}` Deletes a vault and all its credentials. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Returns - `VaultDeleted object { id, deleted, object }` Confirmation that a vault was deleted. - `id: string` The ID of the deleted vault. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.deleted"` The object type. Always `vault.deleted`. - `"vault.deleted"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "vault.deleted" } ``` ## List vaults **get** `/vaults` Lists vaults using ID-based pagination. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `metadata: optional map[string]` Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. Filtering is eventually consistent; metadata changes may take time to appear. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. - `status: optional VaultStatusFilter` Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default. - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` - `array of VaultStatus` - `"active"` - `"archived"` ### Returns - `data: array of Vault` The resources returned in this page, in the requested sort order. - `id: string` The ID of the vault. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `metadata: map[string]` Key-value pairs associated with the vault, such as an application or team identifier. - `name: string or null` The human-readable name of the vault, if set. - `object: "vault"` The object type. Always `vault`. - `"vault"` - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/vaults \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a vault **get** `/vaults/{vault_id}` Retrieves a vault by its ID. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Returns - `Vault object { id, created_at, metadata, 2 more }` A collection of credentials for MCP servers and OpenAI-hosted environments. - `id: string` The ID of the vault. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `metadata: map[string]` Key-value pairs associated with the vault, such as an application or team identifier. - `name: string or null` The human-readable name of the vault, if set. - `object: "vault"` The object type. Always `vault`. - `"vault"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault" } ``` ## Update a vault **post** `/vaults/{vault_id}` Updates the name or metadata of an active vault. Omitted fields remain unchanged. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Body Parameters - `metadata: optional map[string]` Replaces all metadata. Omit to leave unchanged, or pass {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. - `name: optional string or null` A replacement name. Omit to leave unchanged, or pass null to clear it. The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. ### Returns - `Vault object { id, created_at, metadata, 2 more }` A collection of credentials for MCP servers and OpenAI-hosted environments. - `id: string` The ID of the vault. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `metadata: map[string]` Key-value pairs associated with the vault, such as an application or team identifier. - `name: string or null` The human-readable name of the vault, if set. - `object: "vault"` The object type. Always `vault`. - `"vault"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "id", "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault" } ``` ## Domain Types ### Vault - `Vault object { id, created_at, metadata, 2 more }` A collection of credentials for MCP servers and OpenAI-hosted environments. - `id: string` The ID of the vault. - `created_at: number` The Unix timestamp, in seconds, when the vault was created. - `metadata: map[string]` Key-value pairs associated with the vault, such as an application or team identifier. - `name: string or null` The human-readable name of the vault, if set. - `object: "vault"` The object type. Always `vault`. - `"vault"` ### Vault Deleted - `VaultDeleted object { id, deleted, object }` Confirmation that a vault was deleted. - `id: string` The ID of the deleted vault. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.deleted"` The object type. Always `vault.deleted`. - `"vault.deleted"` ### Vault Status - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` ### Vault Status Filter - `VaultStatusFilter = VaultStatus or array of VaultStatus` One or more lifecycle statuses to include when listing vaults or credentials. - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` - `array of VaultStatus` - `"active"` - `"archived"` # Credentials ## Create a vault credential **post** `/vaults/{vault_id}/credentials` Creates a vault credential. Secret values are write-only and are never returned. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Body Parameters - `auth: CredentialAuthCreateParam` The authentication method and write-only secret values to store. - `McpOauth object { access_token, mcp_server_url, type, 2 more }` An OAuth credential for an HTTPS MCP destination. - `access_token: string` A write-only OAuth access token; never returned by credential resources. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `expires_at: optional string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `refresh: optional object { client_id, refresh_token, token_endpoint, 3 more } or null` Optional refresh configuration for an HTTPS OAuth token endpoint. - `client_id: string` The OAuth client ID used when requesting a new access token. - `refresh_token: string` The refresh token to store. This secret is never returned in credential resources. - `token_endpoint: string` The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token. - `token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam` How the OAuth client authenticates to the token endpoint. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { client_secret, type }` Sends the client ID and secret using HTTP Basic authentication. - `client_secret: string` The OAuth client secret to store. Never returned in credential resources. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { client_secret, type }` Sends the client ID and secret in the token request body. - `client_secret: string` The OAuth client secret to store. Never returned in credential resources. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `resource: optional string or null` The resource URI to send to the OAuth token endpoint during refresh, if required. - `scope: optional string or null` Space-separated OAuth scopes to request during refresh, if required. - `StaticBearer object { token, mcp_server_url, type }` A bearer token for an MCP server, without automatic OAuth refresh. - `token: string` The bearer token to store. This secret is never returned in credential resources. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, secret_value, type }` An HTTP credential for OpenAI-hosted environments only. The sandbox receives an environment variable containing a placeholder, not the secret. Use the placeholder unchanged in outgoing requests. The egress proxy replaces the placeholder with the secret for allowed HTTPS destinations on ports 443 and 8443. Sandbox code cannot read the real secret or use it for local computation, such as signing a request. - `networking: CredentialNetworkingParam` The destinations where the proxy can substitute this secret. The environment network policy must also allow them. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder, such as `SERVICE_API_KEY`. Use ASCII letters, digits, and underscores, starting with a letter or underscore. Names starting with `CODEX_` and managed proxy or certificate variable names are reserved. - `secret_value: string` The write-only secret to store. Never returned in credential resources or supplied directly to sandbox code. Must be nonempty and must not contain carriage returns, newlines, or NUL bytes. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` - `name: string` The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. - `metadata: optional map[string]` Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Defaults to an empty map. ### Returns - `Credential object { id, auth, created_at, 5 more }` Metadata for a stored credential. Secret values are never returned. - `id: string` The ID of the credential. - `auth: CredentialAuth` The authentication method and non-secret configuration of the credential. - `McpOauth object { expires_at, mcp_server_url, refresh, type }` Public metadata for an OAuth credential; tokens and client secrets are never returned. - `expires_at: string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `refresh: object { client_id, resource, scope, 2 more } or null` Public refresh metadata without refresh tokens or OAuth client secrets. - `client_id: string` The OAuth client ID used when requesting a new access token. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { type }` Sends the client ID and secret using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { type }` Sends the client ID and secret in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `StaticBearer object { mcp_server_url, type }` Metadata for a bearer-token credential, without automatic OAuth refresh. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, type }` Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource. - `networking: CredentialNetworking` The destinations where the proxy can substitute the secret, subject to the environment network policy. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder in the sandbox. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `metadata: map[string]` Application-defined key-value pairs associated with this credential. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "auth": { "access_token": "access_token", "mcp_server_url": "mcp_server_url", "type": "mcp_oauth" }, "name": "x" }' ``` #### Response ```json { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ``` ## Delete a vault credential **delete** `/vaults/{vault_id}/credentials/{credential_id}` Deletes a vault credential. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` - `credential_id: string` ### Returns - `CredentialDeleted object { id, deleted, object }` Confirmation that a vault credential was deleted. - `id: string` The ID of the deleted credential. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.credential.deleted"` The object type. Always `vault.credential.deleted`. - `"vault.credential.deleted"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ -X DELETE \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "deleted": true, "object": "vault.credential.deleted" } ``` ## List vault credentials **get** `/vaults/{vault_id}/credentials` Lists a vault's credentials using ID-based pagination without returning secret values. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` ### Query Parameters - `after: optional string` Return resources after this resource ID in the selected order. - `limit: optional number` The maximum number of resources to return, between 1 and 100. Defaults to 20. - `metadata: optional map[string]` Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. Filtering is eventually consistent; metadata changes may take time to appear. - `order: optional "asc" or "desc"` The order in which resources are returned. Defaults to `desc`. - `"asc"` Returns resources in ascending order. - `"desc"` Returns resources in descending order. - `status: optional VaultStatusFilter` Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default. - `VaultStatus = "active" or "archived"` Whether a vault or credential is active or archived. - `"active"` - `"archived"` - `array of VaultStatus` - `"active"` - `"archived"` ### Returns - `data: array of Credential` The resources returned in this page, in the requested sort order. - `id: string` The ID of the credential. - `auth: CredentialAuth` The authentication method and non-secret configuration of the credential. - `McpOauth object { expires_at, mcp_server_url, refresh, type }` Public metadata for an OAuth credential; tokens and client secrets are never returned. - `expires_at: string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `refresh: object { client_id, resource, scope, 2 more } or null` Public refresh metadata without refresh tokens or OAuth client secrets. - `client_id: string` The OAuth client ID used when requesting a new access token. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { type }` Sends the client ID and secret using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { type }` Sends the client ID and secret in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `StaticBearer object { mcp_server_url, type }` Metadata for a bearer-token credential, without automatic OAuth refresh. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, type }` Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource. - `networking: CredentialNetworking` The destinations where the proxy can substitute the secret, subject to the environment network policy. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder in the sandbox. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `metadata: map[string]` Application-defined key-value pairs associated with this credential. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. - `first_id: string or null` The ID of the first resource in `data`, or `null` if the page is empty. - `has_more: boolean` Whether there are more resources to retrieve after this page. - `last_id: string or null` The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `object: "list"` The object type, which is always `list`. - `"list"` ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "data": [ { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id", "object": "list" } ``` ## Retrieve a vault credential **get** `/vaults/{vault_id}/credentials/{credential_id}` Retrieves vault credential metadata without returning secret values. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` - `credential_id: string` ### Returns - `Credential object { id, auth, created_at, 5 more }` Metadata for a stored credential. Secret values are never returned. - `id: string` The ID of the credential. - `auth: CredentialAuth` The authentication method and non-secret configuration of the credential. - `McpOauth object { expires_at, mcp_server_url, refresh, type }` Public metadata for an OAuth credential; tokens and client secrets are never returned. - `expires_at: string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `refresh: object { client_id, resource, scope, 2 more } or null` Public refresh metadata without refresh tokens or OAuth client secrets. - `client_id: string` The OAuth client ID used when requesting a new access token. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { type }` Sends the client ID and secret using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { type }` Sends the client ID and secret in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `StaticBearer object { mcp_server_url, type }` Metadata for a bearer-token credential, without automatic OAuth refresh. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, type }` Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource. - `networking: CredentialNetworking` The destinations where the proxy can substitute the secret, subject to the environment network policy. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder in the sandbox. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `metadata: map[string]` Application-defined key-value pairs associated with this credential. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ``` ## Update a vault credential **post** `/vaults/{vault_id}/credentials/{credential_id}` Updates credential metadata or rotates its write-only secret. See [vaults](/api/docs/guides/agents-api/tools/vaults). ### Path Parameters - `vault_id: string` - `credential_id: string` ### Body Parameters - `auth: optional CredentialAuthRotateParam` Replacement values for the credential's existing authentication method. - `McpOauth object { type, access_token, expires_at, refresh }` Rotate an OAuth credential for an HTTPS MCP destination. - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `access_token: optional string or null` A write-only replacement OAuth access token. - `expires_at: optional string or null` The replacement expiry as an RFC 3339 timestamp, or `null` to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared. - `refresh: optional object { refresh_token, scope, token_endpoint_auth } or null` Optional write-only refresh-token and client-secret updates. - `refresh_token: optional string or null` The replacement refresh token. Omit or pass `null` to keep the stored token. This secret is never returned in resources. - `scope: optional string or null` Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass `null` to stop sending a scope parameter. - `token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null` Client-secret updates for the existing token endpoint authentication method. - `ClientSecretBasic object { type, client_secret }` Updates credentials sent using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `client_secret: optional string or null` The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. - `ClientSecretPost object { type, client_secret }` Updates credentials sent in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `client_secret: optional string or null` The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. - `StaticBearer object { token, type }` Replace the bearer token for the credential's MCP server. - `token: string` The replacement bearer token. This secret is never returned in credential resources. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { secret_value, type }` Replace the secret for an OpenAI-hosted environment credential. The environment variable name and networking configuration remain unchanged. - `secret_value: string` The write-only replacement secret. Never returned in credential resources or supplied directly to sandbox code. Must be nonempty and must not contain carriage returns, newlines, or NUL bytes. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` - `metadata: optional map[string]` Replaces all metadata. Omit to preserve it, or pass {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. ### Returns - `Credential object { id, auth, created_at, 5 more }` Metadata for a stored credential. Secret values are never returned. - `id: string` The ID of the credential. - `auth: CredentialAuth` The authentication method and non-secret configuration of the credential. - `McpOauth object { expires_at, mcp_server_url, refresh, type }` Public metadata for an OAuth credential; tokens and client secrets are never returned. - `expires_at: string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `refresh: object { client_id, resource, scope, 2 more } or null` Public refresh metadata without refresh tokens or OAuth client secrets. - `client_id: string` The OAuth client ID used when requesting a new access token. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { type }` Sends the client ID and secret using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { type }` Sends the client ID and secret in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `StaticBearer object { mcp_server_url, type }` Metadata for a bearer-token credential, without automatic OAuth refresh. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, type }` Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource. - `networking: CredentialNetworking` The destinations where the proxy can substitute the secret, subject to the environment network policy. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder in the sandbox. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `metadata: map[string]` Application-defined key-value pairs associated with this credential. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Example ```http curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: agents=v1' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "id", "auth": { "expires_at": "expires_at", "mcp_server_url": "mcp_server_url", "refresh": { "client_id": "client_id", "resource": "resource", "scope": "scope", "token_endpoint": "token_endpoint", "token_endpoint_auth": { "type": "none" } }, "type": "mcp_oauth" }, "created_at": 0, "metadata": { "foo": "string" }, "name": "name", "object": "vault.credential", "updated_at": 0, "vault_id": "vault_id" } ``` ## Domain Types ### Credential - `Credential object { id, auth, created_at, 5 more }` Metadata for a stored credential. Secret values are never returned. - `id: string` The ID of the credential. - `auth: CredentialAuth` The authentication method and non-secret configuration of the credential. - `McpOauth object { expires_at, mcp_server_url, refresh, type }` Public metadata for an OAuth credential; tokens and client secrets are never returned. - `expires_at: string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `refresh: object { client_id, resource, scope, 2 more } or null` Public refresh metadata without refresh tokens or OAuth client secrets. - `client_id: string` The OAuth client ID used when requesting a new access token. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { type }` Sends the client ID and secret using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { type }` Sends the client ID and secret in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `StaticBearer object { mcp_server_url, type }` Metadata for a bearer-token credential, without automatic OAuth refresh. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, type }` Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource. - `networking: CredentialNetworking` The destinations where the proxy can substitute the secret, subject to the environment network policy. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder in the sandbox. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` - `created_at: number` The Unix timestamp, in seconds, when the credential was created. - `metadata: map[string]` Application-defined key-value pairs associated with this credential. - `name: string` The human-readable name of the credential. - `object: "vault.credential"` The object type. Always `vault.credential`. - `"vault.credential"` - `updated_at: number` The Unix timestamp, in seconds, when the credential was last updated. - `vault_id: string` The ID of the vault containing this credential. ### Credential Auth - `CredentialAuth = McpOauth { expires_at, mcp_server_url, refresh, type } or StaticBearer { mcp_server_url, type } or EnvironmentVariable { networking, secret_name, type }` The authentication configuration of a vault credential, excluding secrets. - `McpOauth object { expires_at, mcp_server_url, refresh, type }` Public metadata for an OAuth credential; tokens and client secrets are never returned. - `expires_at: string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `refresh: object { client_id, resource, scope, 2 more } or null` Public refresh metadata without refresh tokens or OAuth client secrets. - `client_id: string` The OAuth client ID used when requesting a new access token. - `resource: string or null` The resource URI sent to the OAuth token endpoint during refresh, if configured. - `scope: string or null` Space-separated OAuth scopes requested during refresh, if configured. - `token_endpoint: string` The HTTPS OAuth token endpoint used for refresh. - `token_endpoint_auth: McpOauthTokenEndpointAuth` How the OAuth client authenticates to the token endpoint, excluding its client secret. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { type }` Sends the client ID and secret using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { type }` Sends the client ID and secret in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `StaticBearer object { mcp_server_url, type }` Metadata for a bearer-token credential, without automatic OAuth refresh. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, type }` Metadata for an HTTP credential used only in OpenAI-hosted environments. Sandbox code receives a placeholder. The proxy substitutes the secret for allowed HTTPS destinations on ports 443 and 8443. The real secret is not available to sandbox code for local computation and is never returned in this resource. - `networking: CredentialNetworking` The destinations where the proxy can substitute the secret, subject to the environment network policy. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder in the sandbox. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` ### Credential Auth Create Param - `CredentialAuthCreateParam = McpOauth { access_token, mcp_server_url, type, 2 more } or StaticBearer { token, mcp_server_url, type } or EnvironmentVariable { networking, secret_name, secret_value, type }` Authentication credentials for an MCP server or an OpenAI-hosted environment. - `McpOauth object { access_token, mcp_server_url, type, 2 more }` An OAuth credential for an HTTPS MCP destination. - `access_token: string` A write-only OAuth access token; never returned by credential resources. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `expires_at: optional string or null` When the OAuth access token expires, as an RFC 3339 timestamp, if known. - `refresh: optional object { client_id, refresh_token, token_endpoint, 3 more } or null` Optional refresh configuration for an HTTPS OAuth token endpoint. - `client_id: string` The OAuth client ID used when requesting a new access token. - `refresh_token: string` The refresh token to store. This secret is never returned in credential resources. - `token_endpoint: string` The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token. - `token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam` How the OAuth client authenticates to the token endpoint. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { client_secret, type }` Sends the client ID and secret using HTTP Basic authentication. - `client_secret: string` The OAuth client secret to store. Never returned in credential resources. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { client_secret, type }` Sends the client ID and secret in the token request body. - `client_secret: string` The OAuth client secret to store. Never returned in credential resources. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `resource: optional string or null` The resource URI to send to the OAuth token endpoint during refresh, if required. - `scope: optional string or null` Space-separated OAuth scopes to request during refresh, if required. - `StaticBearer object { token, mcp_server_url, type }` A bearer token for an MCP server, without automatic OAuth refresh. - `token: string` The bearer token to store. This secret is never returned in credential resources. - `mcp_server_url: string` The HTTPS MCP server URL authorized by this credential. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { networking, secret_name, secret_value, type }` An HTTP credential for OpenAI-hosted environments only. The sandbox receives an environment variable containing a placeholder, not the secret. Use the placeholder unchanged in outgoing requests. The egress proxy replaces the placeholder with the secret for allowed HTTPS destinations on ports 443 and 8443. Sandbox code cannot read the real secret or use it for local computation, such as signing a request. - `networking: CredentialNetworkingParam` The destinations where the proxy can substitute this secret. The environment network policy must also allow them. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` - `secret_name: string` The environment variable name that receives the placeholder, such as `SERVICE_API_KEY`. Use ASCII letters, digits, and underscores, starting with a letter or underscore. Names starting with `CODEX_` and managed proxy or certificate variable names are reserved. - `secret_value: string` The write-only secret to store. Never returned in credential resources or supplied directly to sandbox code. Must be nonempty and must not contain carriage returns, newlines, or NUL bytes. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` ### Credential Auth Rotate Param - `CredentialAuthRotateParam = McpOauth { type, access_token, expires_at, refresh } or StaticBearer { token, type } or EnvironmentVariable { secret_value, type }` Updates to a vault credential without changing its authentication method or destination configuration. - `McpOauth object { type, access_token, expires_at, refresh }` Rotate an OAuth credential for an HTTPS MCP destination. - `type: "mcp_oauth"` The type of the object. Always `mcp_oauth`. - `"mcp_oauth"` - `access_token: optional string or null` A write-only replacement OAuth access token. - `expires_at: optional string or null` The replacement expiry as an RFC 3339 timestamp, or `null` to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared. - `refresh: optional object { refresh_token, scope, token_endpoint_auth } or null` Optional write-only refresh-token and client-secret updates. - `refresh_token: optional string or null` The replacement refresh token. Omit or pass `null` to keep the stored token. This secret is never returned in resources. - `scope: optional string or null` Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass `null` to stop sending a scope parameter. - `token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null` Client-secret updates for the existing token endpoint authentication method. - `ClientSecretBasic object { type, client_secret }` Updates credentials sent using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `client_secret: optional string or null` The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. - `ClientSecretPost object { type, client_secret }` Updates credentials sent in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `client_secret: optional string or null` The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. - `StaticBearer object { token, type }` Replace the bearer token for the credential's MCP server. - `token: string` The replacement bearer token. This secret is never returned in credential resources. - `type: "static_bearer"` The type of the object. Always `static_bearer`. - `"static_bearer"` - `EnvironmentVariable object { secret_value, type }` Replace the secret for an OpenAI-hosted environment credential. The environment variable name and networking configuration remain unchanged. - `secret_value: string` The write-only replacement secret. Never returned in credential resources or supplied directly to sandbox code. Must be nonempty and must not contain carriage returns, newlines, or NUL bytes. - `type: "environment_variable"` The type of the object. Always `environment_variable`. - `"environment_variable"` ### Credential Deleted - `CredentialDeleted object { id, deleted, object }` Confirmation that a vault credential was deleted. - `id: string` The ID of the deleted credential. - `deleted: boolean` Whether the resource was deleted. Always `true`. - `object: "vault.credential.deleted"` The object type. Always `vault.credential.deleted`. - `"vault.credential.deleted"` ### Credential Networking - `CredentialNetworking = Unrestricted { type } or Limited { allowed_hosts, type }` Destination permissions for an environment-variable credential. These do not grant network access to the environment. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` ### Credential Networking Param - `CredentialNetworkingParam = Unrestricted { type } or Limited { allowed_hosts, type }` Destination permissions for an environment-variable credential. These do not grant network access to the environment. - `Unrestricted object { type }` Allows substitution for destinations permitted by the environment network policy. Requires `environment.network.access` to be `restricted`, with explicit `allowed_domains`. - `type: "unrestricted"` The type of the object. Always `unrestricted`. - `"unrestricted"` - `Limited object { allowed_hosts, type }` Allows substitution only for the listed hosts. The environment network policy must also allow these hosts. - `allowed_hosts: array of string` The 1 to 16 distinct allowed hostnames or IPv4 addresses, normalized to lowercase. Entries contain no scheme, path, port, or wildcard. IPv6 addresses are not supported. - `type: "limited"` The type of the object. Always `limited`. - `"limited"` ### Mcp OAuth Token Endpoint Auth - `McpOauthTokenEndpointAuth = None { type } or ClientSecretBasic { type } or ClientSecretPost { type }` The client authentication method used for OAuth token refresh. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { type }` Sends the client ID and secret using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { type }` Sends the client ID and secret in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` ### Mcp OAuth Token Endpoint Auth Create Param - `McpOauthTokenEndpointAuthCreateParam = None { type } or ClientSecretBasic { client_secret, type } or ClientSecretPost { client_secret, type }` Client authentication credentials for OAuth token refresh. - `None object { type }` Sends the client ID without a client secret. - `type: "none"` The type of the object. Always `none`. - `"none"` - `ClientSecretBasic object { client_secret, type }` Sends the client ID and secret using HTTP Basic authentication. - `client_secret: string` The OAuth client secret to store. Never returned in credential resources. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `ClientSecretPost object { client_secret, type }` Sends the client ID and secret in the token request body. - `client_secret: string` The OAuth client secret to store. Never returned in credential resources. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` ### Mcp OAuth Token Endpoint Auth Rotate Param - `McpOauthTokenEndpointAuthRotateParam = ClientSecretBasic { type, client_secret } or ClientSecretPost { type, client_secret }` Client-secret updates that preserve the credential's OAuth authentication method. - `ClientSecretBasic object { type, client_secret }` Updates credentials sent using HTTP Basic authentication. - `type: "client_secret_basic"` The type of the object. Always `client_secret_basic`. - `"client_secret_basic"` - `client_secret: optional string or null` The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. - `ClientSecretPost object { type, client_secret }` Updates credentials sent in the token request body. - `type: "client_secret_post"` The type of the object. Always `client_secret_post`. - `"client_secret_post"` - `client_secret: optional string or null` The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources.