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

List agent sessions

GET/agents/sessions

Lists managed agent sessions using ID-based pagination and the requested sort order. See managing sessions.

Query ParametersExpand Collapse
after: optional string

Return resources after this resource ID in the selected order.

minLength0
maxLength1048576
agent_id: optional string

Only return sessions whose root agent has this ID. Omit to return sessions for all agents.

minLength0
maxLength1048576
limit: optional number

The maximum number of resources to return, between 1 and 100. Defaults to 20.

formatint64
minimum1
maximum100
order: optional "asc" or "desc"

The order in which resources are returned. Defaults to desc.

One of the following:
"asc"

Returns resources in ascending order.

"desc"

Returns resources in descending order.

ReturnsExpand Collapse
data: array of AgentSession { id, agent, created_at, 10 more }

The resources returned in this page, in the requested sort order.

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 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" or "detailed" or "auto" or 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" or "default" or "flex" or 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:
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 location used to localize search results, if provided.

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.

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.

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, desktop, 7 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.

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.

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"

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

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.

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

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

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

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

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

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 of object { id, field_ids, label }

Sign-in methods. Empty for a plain form.

id: string

The option ID to submit as selected_option.

minLength0
field_ids: array of string

IDs from the registered fields that this method accepts.

label: string

The method label to display.

minLength0
reason: string or null

Why the agent needs the user to sign in.

minLength0
type: "browser_authentication"

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

minLength0
reason: string or 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.

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

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

spend_control: optional object { consumed, limit }

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

consumed: number or 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
first_id: string or null

The ID of the first resource in data, or null if the page is empty.

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

minLength0
object: "list"

The object type, which is always list.

List agent sessions

curl https://api.openai.com/v1/agents/sessions \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"
{
  "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"
      ],
      "spend_control": {
        "consumed": 0,
        "limit": 1
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
Returns Examples
{
  "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"
      ],
      "spend_control": {
        "consumed": 0,
        "limit": 1
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}