## List agent sessions

`client.beta.agents.sessions.list(SessionListParamsquery?, RequestOptionsoptions?): CursorPage<AgentSession>`

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

### Parameters

- `query: SessionListParams`

  - `after?: string`

    Return resources after this resource ID in the selected order.

    `minLength: 0`, `maxLength: 1048576`

  - `agent_id?: string`

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

    `minLength: 0`, `maxLength: 1048576`

  - `limit?: number`

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

    `format: int64`, `minimum: 1`, `maximum: 100`

  - `metadata?: Record<string, 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. New sessions and metadata updates may take time to appear in filtered results.

  - `order?: "asc" | "desc"`

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

    - `"asc"`

      Returns resources in ascending order.

    - `"desc"`

      Returns resources in descending order.

### Returns

- `AgentSession`

  A Managed Agents session.

  - `id: string`

    The ID of the session.

    `minLength: 0`

  - `agent: Agent`

    The agent running in the session.

    - `id: string`

      The ID of the agent.

      `minLength: 0`

    - `instructions: string | null`

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

      `minLength: 0`

    - `model: string`

      The model used by the agent.

      `minLength: 0`

    - `multi_agent: MultiAgentConfig`

      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.

        `format: int64`, `minimum: 1`, `maximum: 4294967295`

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

      `minLength: 0`

    - `reasoning: AgentReasoning`

      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.

        - `"none"`

        - `"minimal"`

        - `"low"`

        - `"medium"`

        - `"high"`

        - `"xhigh"`

        - `"max"`

      - `summary: "concise" | "detailed" | "auto" | 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" | "default" | "flex" | 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.

        - `TextFormatResourceText`

          Generates ordinary text without a structured-output constraint.

          - `type: "text"`

            The type of the object. Always `text`.

            - `"text"`

        - `TextFormatResourceJSONSchema`

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

            - `"json_schema"`

      - `verbosity: "low" | "medium" | "high"`

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

        - `"low"`

        - `"medium"`

        - `"high"`

    - `tools: Array<AgentTool>`

      Tools available to the agent.

      `minItems: 0`, `maxItems: 2000`

      - `AgentToolResourceFunction`

        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.

          `minLength: 0`

        - `name: string`

          The name of the function.

          `minLength: 0`

        - `parameters: Record<string, unknown>`

          A JSON Schema object describing the function's arguments.

        - `type: "function"`

          The type of the object. Always `function`.

          - `"function"`

        - `async?: boolean`

          Whether the agent continues without waiting for the function result.

      - `AgentToolResourceProgrammaticToolCalling`

        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"`

      - `AgentToolResourceMcp`

        Tools provided by a remote MCP server.

        - `allowed_tools: Array<string> | null`

          The MCP tools the agent may call.

          `minItems: 0`, `maxItems: 2000`

        - `connection_origin: "service" | "environment"`

          Where outbound MCP HTTP connections originate.

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

          `minLength: 0`

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

          `minLength: 0`

        - `transport: McpTransport`

          The transport used to connect to the MCP server.

          - `McpTransportResourceHTTP`

            Connects to an MCP server over HTTP.

            - `server_url: string`

              The URL of the MCP server.

              `minLength: 0`

            - `type: "http"`

              The type of the object. Always `http`.

              - `"http"`

          - `McpTransportResourceStdio`

            Starts an MCP server as a local process.

            - `args: Array<string>`

              Arguments passed to the MCP server command.

              `minItems: 0`, `maxItems: 2000`

            - `command: string`

              The command used to start the MCP server.

              `minLength: 0`

            - `cwd: string`

              The working directory used to start the MCP server.

              `minLength: 0`

            - `env_vars: Array<string>`

              Environment variable names inherited from the execution environment.

              `minItems: 0`, `maxItems: 2000`

            - `type: "stdio"`

              The type of the object. Always `stdio`.

              - `"stdio"`

        - `type: "mcp"`

          The type of the object. Always `mcp`.

          - `"mcp"`

      - `AgentToolResourceWebSearch`

        Web search.

        - `allowed_domains: Array<string> | null`

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

          `minItems: 0`, `maxItems: 2000`

        - `context_size: "low" | "medium" | "high"`

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

          - `"low"`

          - `"medium"`

          - `"high"`

        - `location: Location | null`

          Approximate location used to localize search results, if provided.

          - `city: string | null`

            The city name.

            `minLength: 0`

          - `country: string | null`

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

            `minLength: 0`

          - `region: string | null`

            The region or state name.

            `minLength: 0`

          - `timezone: string | null`

            The IANA timezone, such as `America/Los_Angeles`.

            `minLength: 0`

        - `mode: "disabled" | "cached" | "live"`

          The source used for web search results.

          - `"disabled"`

          - `"cached"`

          - `"live"`

        - `type: "web_search"`

          The type of the object. Always `web_search`.

          - `"web_search"`

      - `AgentToolResourceComputerUse`

        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"`

      - `AgentToolResourceAutomations`

        Lets the agent manage its own scheduled wakeups.

        - `type: "automations"`

          The type of the object. Always `automations`.

          - `"automations"`

    - `compaction?: Compaction`

      The effective context compaction settings.

      - `async: boolean`

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

    - `experimental?: Experimental`

      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.

    `format: int64`

  - `environment: Environment`

    The execution environment for the session.

    - `EnvironmentResourceNone`

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

      - `type: "none"`

        The type of the object. Always `none`.

        - `"none"`

    - `EnvironmentResourceOpenAIHosted`

      An environment hosted by OpenAI.

      - `id: string`

        The public ID of the environment.

        `minLength: 0`

      - `capability_directories: Array<string>`

        Directories that contain capabilities exposed to the agent.

        `minItems: 0`, `maxItems: 2000`

      - `files: Array<HostedEnvironmentFile>`

        Files available in the environment, excluding their contents.

        `minItems: 0`, `maxItems: 50`

        - `HostedEnvironmentFileID`

          A file copied from the OpenAI Files API.

          - `id: string`

            The session-scoped ID of the file in the execution environment.

            `minLength: 0`

          - `file_id: string`

            The ID of the uploaded file.

            `minLength: 0`

          - `path: string`

            The file's absolute path inside the environment.

            `minLength: 0`

          - `size_bytes: number`

            The decoded file size in bytes.

            `format: int64`, `minimum: 0`

          - `type: "file_id"`

            The type of the object. Always `file_id`.

            - `"file_id"`

        - `HostedEnvironmentFileResourceInline`

          A file supplied inline when the session was created.

          - `id: string`

            The session-scoped ID of the file in the execution environment.

            `minLength: 0`

          - `path: string`

            The file's absolute path inside the environment.

            `minLength: 0`

          - `size_bytes: number`

            The decoded file size in bytes.

            `format: int64`, `minimum: 0`

          - `type: "inline"`

            The type of the object. Always `inline`.

            - `"inline"`

      - `network: Network`

        The effective network access policy for the environment.

        - `access: "enabled" | "disabled" | "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<string>`

          Domains the environment may access when network access is restricted.

          `minItems: 0`, `maxItems: 2000`

      - `packages: Packages`

        Packages installed in the environment.

        - `npm: Array<string>`

          npm packages installed globally in the environment.

          `minItems: 0`, `maxItems: 16384`

        - `python: Array<string>`

          Python packages installed in the environment.

          `minItems: 0`, `maxItems: 16384`

        - `system: Array<string>`

          System packages installed in the environment.

          `minItems: 0`, `maxItems: 16384`

      - `plugins: Array<HostedPlugin>`

        Plugins installed in the environment, excluding their archive contents.

        `minItems: 0`, `maxItems: 2000`

        - `description: string`

          The installed plugin description.

          `minLength: 0`

        - `name: string`

          The installed plugin name.

          `minLength: 0`

        - `type: "inline"`

          The type of the object. Always `inline`.

          - `"inline"`

      - `skills: Array<HostedSkill>`

        Skills installed in the environment, excluding their archive contents.

        `minItems: 0`, `maxItems: 2000`

        - `HostedSkillReference`

          A skill installed from the Skills API.

          - `description: string`

            The installed skill description.

            `minLength: 0`

          - `name: string`

            The installed skill name.

            `minLength: 0`

          - `skill_id: string`

            The referenced skill ID.

            `minLength: 0`

          - `type: "skill_reference"`

            The type of the object. Always `skill_reference`.

            - `"skill_reference"`

          - `version: string`

            The concrete skill version installed for this session.

            `minLength: 0`

        - `HostedSkillResourceInline`

          A skill installed from an inline ZIP archive.

          - `description: string`

            The installed skill description.

            `minLength: 0`

          - `name: string`

            The installed skill name.

            `minLength: 0`

          - `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?: "small" | "medium" | "large" | null`

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

        - `"small"`

        - `"medium"`

        - `"large"`

      - `desktop?: Desktop`

        The effective desktop configuration.

        - `enabled: boolean`

          Whether the environment provisions a desktop and browser proxy.

    - `EnvironmentResourceSelfHosted`

      An environment hosted by the application.

      - `id: string`

        The public ID of the environment.

        `minLength: 0`

      - `capability_directories: Array<string>`

        Directories that contain capabilities exposed to the agent.

        `minItems: 0`, `maxItems: 2000`

      - `remote_url: string`

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

        `minLength: 0`

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

        `minLength: 0`

  - `error: string | null`

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

    `minLength: 0`

  - `last_active_at: number`

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

    `format: int64`

  - `metadata: Record<string, string>`

    Custom string key-value pairs attached to the session.

  - `object: "agent.session"`

    The object type. Always `agent.session`.

    - `"agent.session"`

  - `required_actions: Array<SessionRequiredActionResourceComputerUseApprovalRequest | SessionRequiredActionResourceFunctionCall | SessionRequiredActionResourceEnvironmentConnection>`

    Actions that must be completed before the session can continue.

    `minItems: 0`, `maxItems: 2000`

    - `SessionRequiredActionResourceComputerUseApprovalRequest`

      Respond to a computer-use request.

      - `request: ComputerUseApprovalRequestKindResourceBrowserAuthentication | ComputerUseApprovalRequestKindResourceBrowserOriginAccess`

        The information needed to render the request.

        - `ComputerUseApprovalRequestKindResourceBrowserAuthentication`

          A registered form awaiting the application's response.

          - `credential_origin: string | null`

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

            `minLength: 0`

          - `fields: Array<Field>`

            Controls to render. All submitted values are sensitive.

            `minItems: 0`, `maxItems: 2000`

            - `id: string`

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

              `minLength: 0`

            - `label: string`

              The label to display beside the control.

              `minLength: 0`

            - `required: boolean`

              Whether this control requires a nonempty value.

            - `type: string`

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

              `minLength: 0`

          - `options: Array<Option>`

            Sign-in methods. Empty for a plain form.

            `minItems: 0`, `maxItems: 2000`

            - `id: string`

              The option ID to submit as selected_option.

              `minLength: 0`

            - `field_ids: Array<string>`

              IDs from the registered fields that this method accepts.

              `minItems: 0`, `maxItems: 2000`

            - `label: string`

              The method label to display.

              `minLength: 0`

          - `reason: string | null`

            Why the agent needs the user to sign in.

            `minLength: 0`

          - `type: "browser_authentication"`

            The type of the object. Always `browser_authentication`.

            - `"browser_authentication"`

        - `ComputerUseApprovalRequestKindResourceBrowserOriginAccess`

          A browser origin awaiting the application's approval decision.

          - `origin: string`

            The origin the browser needs permission to access.

            `minLength: 0`

          - `reason: string | null`

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

            `minLength: 0`

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

        `minLength: 0`

      - `turn_id: string`

        The turn that requested approval.

        `minLength: 0`

      - `type: "computer_use_approval_request"`

        The type of the object. Always `computer_use_approval_request`.

        - `"computer_use_approval_request"`

    - `SessionRequiredActionResourceFunctionCall`

      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.

        `minLength: 0`

      - `name: string`

        The function name.

        `minLength: 0`

      - `turn_id: string`

        The ID of the turn that requested the function call.

        `minLength: 0`

      - `type: "function_call"`

        The type of the object. Always `function_call`.

        - `"function_call"`

    - `SessionRequiredActionResourceEnvironmentConnection`

      Reconnect a session environment.

      - `environment_id: string`

        The ID of the environment to reconnect.

        `minLength: 0`

      - `type: "environment_connection"`

        The type of the object. Always `environment_connection`.

        - `"environment_connection"`

  - `status: "idle" | "in_progress" | "requires_action" | "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 | 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.

      `format: int64`

    - `input_tokens_details: InputTokensDetails`

      A breakdown of the agent's input token usage.

      - `cached_tokens: number`

        The number of input tokens retrieved from the prompt cache.

        `format: int64`

    - `output_tokens: number`

      The number of output tokens generated by the agent.

      `format: int64`

    - `output_tokens_details: OutputTokensDetails`

      A breakdown of the agent's output token usage.

      - `reasoning_tokens: number`

        The number of output tokens used for reasoning.

        `format: int64`

    - `total_tokens: number`

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

      `format: int64`

  - `vault_ids: Array<string>`

    The IDs of vaults made available to the session.

    `minItems: 0`, `maxItems: 2000`

  - `prompt_cache_options?: PromptCacheOptions | null`

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

    - `ttl: "30m" | "12h"`

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

    - `"none"`

    - `"auto_review"`

  - `spend_control?: SpendControl`

    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.

      `minimum: 0`

    - `limit: number`

      The configured positive limit in USD cents.

      `format: int64`, `minimum: 1`, `maximum: 4503599627370495`

### Example

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const agentSession of client.beta.agents.sessions.list()) {
  console.log(agentSession.id);
}
```

#### 200 — Example

```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",
            "async": true
          }
        ],
        "compaction": {
          "async": true
        },
        "experimental": {
          "time_awareness": true
        }
      },
      "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"
      ],
      "prompt_cache_options": {
        "ttl": "30m"
      },
      "review": "none",
      "spend_control": {
        "consumed": 0,
        "limit": 1
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
```
