Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference
API Reference
Beta
Agents
Sessions

Retrieve an agent session

GET/agents/sessions/{session_id}

Retrieves the current state of a managed agent session. See managing sessions.

Path ParametersExpand Collapse
session_id: string
minLength0
maxLength1048576
ReturnsExpand Collapse
AgentSession object { id, agent, created_at, 9 more }

A Managed Agents session.

id: string

The ID of the session.

minLength0
agent: object { id, instructions, model, 6 more }

The agent running in the session.

id: string

The ID of the agent.

minLength0
instructions: string or 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 or null

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

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

minLength0
reasoning: AgentReasoning { effort, summary }

The agent’s reasoning configuration.

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

The amount of reasoning effort used by an agent.

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

The reasoning summary format requested from an agent.

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" or "default" or "flex" or 2 more

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

One of the following:
"auto"
"default"
"flex"
"priority"
"fast"
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:
Text object { type }

Generates ordinary text without a structured-output constraint.

type: "text"

The type of the object. Always 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.

verbosity: "low" or "medium" or "high"

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

One of the following:
"low"
"medium"
"high"
tools: array of AgentTool

Tools available to the agent.

One of the following:
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.

minLength0
name: string

The name of the function.

minLength0
parameters: map[unknown]

A JSON Schema object describing the function’s arguments.

type: "function"

The type of the object. Always 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.

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.

One of the following:
"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.

minLength0
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.

minLength0
transport: McpTransport

The transport used to connect to the MCP server.

One of the following:
HTTP object { 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.

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.

minLength0
cwd: string

The working directory used to start the MCP server.

minLength0
env_vars: array of string

Environment variable names inherited from the execution environment.

type: "stdio"

The type of the object. Always stdio.

type: "mcp"

The type of the object. Always 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.

One of the following:
"low"
"medium"
"high"
location: object { city, country, region, timezone } or null

Approximate user location used to localize web search results.

city: string or null

The city name.

minLength0
country: string or null

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

minLength0
region: string or null

The region or state name.

minLength0
timezone: string or null

The IANA timezone, such as America/Los_Angeles.

minLength0
mode: "disabled" or "cached" or "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.

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:
None object { type }

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

type: "none"

The type of the object. Always none.

OpenAIHosted object { id, capability_directories, files, 5 more }

An environment hosted by OpenAI.

id: string

The public ID of the environment.

minLength0
capability_directories: array of string

Directories that contain capabilities exposed to the agent.

files: array of HostedEnvironmentFile

Files available in the environment, excluding their contents.

One of the following:
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.

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.

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.

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: object { access, allowed_domains }

The effective network access policy for the environment.

access: "enabled" or "disabled" or "restricted"

The environment’s network access mode.

One of the following:
"enabled"

Allows unrestricted network access.

"disabled"

Disables network access.

"restricted"

Allows access only to configured domains.

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 { description, name, type }

Plugins installed in the environment, excluding their archive contents.

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 of HostedSkill

Skills installed in the environment, excluding their archive contents.

One of the following:
HostedSkillReference object { 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
Inline object { 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.

SelfHosted object { 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 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.

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 or 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: map[string]

Custom string key-value pairs attached to the session.

object: "agent.session"

The object type. Always agent.session.

required_actions: array of object { arguments, call_id, name, 2 more } or object { environment_id, type }

Actions that must be completed before the session can continue.

One of the following:
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.

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.

EnvironmentConnection object { 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" or "in_progress" or "requires_action" or "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 } or null

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.

formatint64
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.

formatint64
output_tokens: number

The number of output tokens generated by the agent.

formatint64
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.

formatint64
total_tokens: number

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

formatint64
vault_ids: array of string

The IDs of vaults made available to the session.

Retrieve an agent session

curl https://api.openai.com/v1/agents/sessions/$SESSION_ID \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"
{
  "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": [
    {
      "arguments": {},
      "call_id": "call_id",
      "name": "name",
      "turn_id": "turn_id",
      "type": "function_call"
    }
  ],
  "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"
  ]
}
Returns Examples
{
  "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": [
    {
      "arguments": {},
      "call_id": "call_id",
      "name": "name",
      "turn_id": "turn_id",
      "type": "function_call"
    }
  ],
  "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"
  ]
}