id: string

The ID of the session.

minLength0
agent: Agent { id, instructions, model, 8 more }

The agent running in the session.

id: string

The ID of the agent.

minLength0
instructions: string | null

Custom instructions appended to the agent’s default base instructions.

minLength0
model: string

The model used by the agent.

minLength0
multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

Configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled. Defaults to false.

max_concurrent_subagents: number | null

Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.

formatint64
minimum1
maximum4294967295
name: string | 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.

minLength0
reasoning: AgentReasoning { effort, summary }

The agent’s reasoning configuration.

effort: "none" | "minimal" | "low" | 4 more | null

The requested reasoning effort, or null when the model selects its own default.

One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: "concise" | "detailed" | "auto" | null

The requested reasoning summary format, or null when summaries are disabled.

One of the following:
"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" | "default" | "flex" | 3 more

The effective service-tier policy for model requests. Defaults to auto.

One of the following:
"auto"
"default"
"flex"
"priority"
"fast"
"ultrafast"
text: AgentText { format, verbosity }

Configuration for text generated by the agent.

format: TextFormat

The effective output format. Defaults to ordinary text.

One of the following:
TextFormatResourceText { type }

Generates ordinary text without a structured-output constraint.

type: "text"

The type of the object. Always text.

TextFormatResourceJSONSchema { schema, type }

Constrains generated text to a JSON Schema.

schema: Record<string, unknown>

The JSON Schema that generated text must match.

type: "json_schema"

The type of the object. Always json_schema.

verbosity: "low" | "medium" | "high"

The amount of text produced by the agent. Defaults to medium.

One of the following:
"low"
"medium"
"high"
tools: Array<AgentTool>

Tools available to the agent.

minItems0
maxItems2000
One of the following:
AgentToolResourceFunction { defer_loading, description, name, 3 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.

minLength0
name: string

The name of the function.

minLength0
parameters: Record<string, unknown>

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always function.

async?: boolean

Whether the agent continues without waiting for the function result.

AgentToolResourceProgrammaticToolCalling { 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.

AgentToolResourceMcp { allowed_tools, connection_origin, credential_id, 5 more }

Tools provided by a remote MCP server.

allowed_tools: Array<string> | null

The MCP tools the agent may call.

minItems0
maxItems2000
connection_origin: "service" | "environment"

Where outbound MCP HTTP connections originate.

One of the following:
"service"
"environment"
credential_id: string | null

The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL.

minLength0
request_metadata: Record<string, 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.

minLength0
transport: McpTransport

The transport used to connect to the MCP server.

One of the following:
McpTransportResourceHTTP { server_url, type }

Connects to an MCP server over HTTP.

server_url: string

The URL of the MCP server.

minLength0
type: "http"

The type of the object. Always http.

McpTransportResourceStdio { args, command, cwd, 2 more }

Starts an MCP server as a local process.

args: Array<string>

Arguments passed to the MCP server command.

minItems0
maxItems2000
command: string

The command used to start the MCP server.

minLength0
cwd: string

The working directory used to start the MCP server.

minLength0
env_vars: Array<string>

Environment variable names inherited from the execution environment.

minItems0
maxItems2000
type: "stdio"

The type of the object. Always stdio.

type: "mcp"

The type of the object. Always mcp.

AgentToolResourceWebSearch { allowed_domains, context_size, location, 2 more }

Web search.

allowed_domains: Array<string> | null

Allowed search domains, or null when the search is unrestricted.

minItems0
maxItems2000
context_size: "low" | "medium" | "high"

The amount of search context made available to the model. Defaults to medium.

One of the following:
"low"
"medium"
"high"
location: Location | null

Approximate location used to localize search results, if provided.

city: string | null

The city name.

minLength0
country: string | null

The two-letter ISO country code, such as US.

minLength0
region: string | null

The region or state name.

minLength0
timezone: string | null

The IANA timezone, such as America/Los_Angeles.

minLength0
mode: "disabled" | "cached" | "live"

The source used for web search results.

One of the following:
"disabled"
"cached"
"live"
type: "web_search"

The type of the object. Always web_search.

AgentToolResourceComputerUse { 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.

AgentToolResourceAutomations { type }

Lets the agent manage its own scheduled wakeups.

type: "automations"

The type of the object. Always automations.

compaction?: Compaction { async }

The effective context compaction settings.

async: boolean

Whether context is compacted in the background. Defaults to true.

experimental?: Experimental { time_awareness }

The effective experimental settings for the agent.

time_awareness: boolean

Whether the model receives periodic current-time reminders.

created_at: number

The Unix timestamp, in seconds, when the session was created.

formatint64
environment: Environment

The execution environment for the session.

One of the following:
EnvironmentResourceNone { type }

The session talks to CCA without selecting or provisioning an execution environment.

type: "none"

The type of the object. Always none.

EnvironmentResourceOpenAIHosted { id, capability_directories, files, 7 more }

An environment hosted by OpenAI.

id: string

The public ID of the environment.

minLength0
capability_directories: Array<string>

Directories that contain capabilities exposed to the agent.

minItems0
maxItems2000
files: Array<HostedEnvironmentFile>

Files available in the environment, excluding their contents.

minItems0
maxItems50
One of the following:
HostedEnvironmentFileID { 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.

minLength0
file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "file_id"

The type of the object. Always file_id.

HostedEnvironmentFileResourceInline { 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.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

network: Network { access, allowed_domains }

The effective network access policy for the environment.

access: "enabled" | "disabled" | "restricted"

The environment’s network access mode.

One of the following:
"enabled"

Allows unrestricted network access.

"disabled"

Disables network access.

"restricted"

Applies the configured domain restrictions.

allowed_domains: Array<string>

Domains the environment may access when network access is restricted.

minItems0
maxItems2000
packages: Packages { npm, python, system }

Packages installed in the environment.

npm: Array<string>

npm packages installed globally in the environment.

minItems0
maxItems16384
python: Array<string>

Python packages installed in the environment.

minItems0
maxItems16384
system: Array<string>

System packages installed in the environment.

minItems0
maxItems16384
plugins: Array<HostedPlugin { description, name, type } >

Plugins installed in the environment, excluding their archive contents.

minItems0
maxItems2000
description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

skills: Array<HostedSkill>

Skills installed in the environment, excluding their archive contents.

minItems0
maxItems2000
One of the following:
HostedSkillReference { description, name, skill_id, 2 more }

A skill installed from the Skills API.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string

The concrete skill version installed for this session.

minLength0
HostedSkillResourceInline { description, name, type }

A skill installed from an inline ZIP archive.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
type: "inline"

The type of the object. Always inline.

type: "openai_hosted"

The type of the object. Always openai_hosted.

container_size?: "small" | "medium" | "large" | null

The effective CPU and memory tier, or null when unknown or outside the public tiers.

One of the following:
"small"
"medium"
"large"
desktop?: Desktop { enabled }

The effective desktop configuration.

enabled: boolean

Whether the environment provisions a desktop and browser proxy.

EnvironmentResourceSelfHosted { id, capability_directories, remote_url, 2 more }

An environment hosted by the application.

id: string

The public ID of the environment.

minLength0
capability_directories: Array<string>

Directories that contain capabilities exposed to the agent.

minItems0
maxItems2000
remote_url: string

Pass this URL unchanged to codex exec-server --remote when connecting this environment.

minLength0
type: "self_hosted"

The type of the object. Always self_hosted.

workspace_directory: string

The absolute project directory inside the environment. Defaults to /workspace.

minLength0
error: string | null

The error that caused the session to fail, if any.

minLength0
last_active_at: number

The Unix timestamp, in seconds, when the session was last active.

formatint64
metadata: Record<string, string>

Custom string key-value pairs attached to the session.

object: "agent.session"

The object type. Always agent.session.

required_actions: Array<SessionRequiredActionResourceComputerUseApprovalRequest { request, request_id, turn_id, type } | SessionRequiredActionResourceFunctionCall { arguments, call_id, name, 2 more } | SessionRequiredActionResourceEnvironmentConnection { environment_id, type } >

Actions that must be completed before the session can continue.

minItems0
maxItems2000
One of the following:
SessionRequiredActionResourceComputerUseApprovalRequest { request, request_id, turn_id, type }

Respond to a computer-use request.

request: ComputerUseApprovalRequestKindResourceBrowserAuthentication { credential_origin, fields, options, 2 more } | ComputerUseApprovalRequestKindResourceBrowserOriginAccess { origin, reason, type }

The information needed to render the request.

One of the following:
ComputerUseApprovalRequestKindResourceBrowserAuthentication { credential_origin, fields, options, 2 more }

A registered form awaiting the application’s response.

credential_origin: string | null

The registered form or frame origin where values will be entered.

minLength0
fields: Array<Field>

Controls to render. All submitted values are sensitive.

minItems0
maxItems2000
id: string

The field ID to submit as field_id in a fields entry.

minLength0
label: string

The label to display beside the control.

minLength0
required: boolean

Whether this control requires a nonempty value.

type: string

The rendering type, such as email, password, or text.

minLength0
options: Array<Option>

Sign-in methods. Empty for a plain form.

minItems0
maxItems2000
id: string

The option ID to submit as selected_option.

minLength0
field_ids: Array<string>

IDs from the registered fields that this method accepts.

minItems0
maxItems2000
label: string

The method label to display.

minLength0
reason: string | null

Why the agent needs the user to sign in.

minLength0
type: "browser_authentication"

The type of the object. Always browser_authentication.

ComputerUseApprovalRequestKindResourceBrowserOriginAccess { origin, reason, type }

A browser origin awaiting the application’s approval decision.

origin: string

The origin the browser needs permission to access.

minLength0
reason: string | null

The browser’s explanation for this request, or null when unavailable.

minLength0
type: "browser_origin_access"

The type of the object. Always browser_origin_access.

request_id: string

The registered request ID to echo when responding.

minLength0
turn_id: string

The turn that requested approval.

minLength0
type: "computer_use_approval_request"

The type of the object. Always computer_use_approval_request.

SessionRequiredActionResourceFunctionCall { 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.

minLength0
name: string

The function name.

minLength0
turn_id: string

The ID of the turn that requested the function call.

minLength0
type: "function_call"

The type of the object. Always function_call.

SessionRequiredActionResourceEnvironmentConnection { environment_id, type }

Reconnect a session environment.

environment_id: string

The ID of the environment to reconnect.

minLength0
type: "environment_connection"

The type of the object. Always environment_connection.

status: "idle" | "in_progress" | "requires_action" | "failed"

The current status of the session.

One of the following:
"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 { input_tokens, input_tokens_details, output_tokens, 2 more } | 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.

formatint64
input_tokens_details: InputTokensDetails { cached_tokens }

A breakdown of the agent’s input token usage.

cached_tokens: number

The number of input tokens retrieved from the prompt cache.

formatint64
output_tokens: number

The number of output tokens generated by the agent.

formatint64
output_tokens_details: OutputTokensDetails { reasoning_tokens }

A breakdown of the agent’s output token usage.

reasoning_tokens: number

The number of output tokens used for reasoning.

formatint64
total_tokens: number

The total number of input and output tokens used by the agent.

formatint64
vault_ids: Array<string>

The IDs of vaults made available to the session.

minItems0
maxItems2000
prompt_cache_options?: PromptCacheOptions | null

Default prompt cache lifetime for turns in this session, when configured.

ttl: "30m" | "12h"
One of the following:
"30m"
"12h"
review?: "none" | "auto_review"

Review applied to eligible actions in this session. Omitted when review is none and automatic review is not enabled. Omission means none.

One of the following:
"none"
"auto_review"
spend_control?: SpendControl { consumed, limit }

Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object.

consumed: number | null

Best-effort recorded spend floored to whole USD cents, or null when unavailable.

minimum0
limit: number

The configured positive limit in USD cents.

formatint64
minimum1
maximum4503599627370495