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

beta.agents.sessions.list(SessionListParams**kwargs) -> SyncCursorPage[AgentSession]
GET/agents/sessions

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

ParametersExpand Collapse
after: Optional[str]

Return resources after this resource ID in the selected order.

minLength0
maxLength1048576
agent_id: Optional[str]

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

minLength0
maxLength1048576
limit: Optional[int]

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

formatint64
minimum1
maximum100
order: Optional[Literal["asc", "desc"]]

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

ReturnsExpand Collapse
class AgentSession: …

A Managed Agents session.

id: str

The ID of the session.

minLength0
agent: Agent

The agent running in the session.

created_at: int

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

formatint64
environment: Environment

The execution environment for the session.

error: Optional[str]

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

minLength0
last_active_at: int

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

formatint64
metadata: Dict[str, str]

Custom string key-value pairs attached to the session.

object: Literal["agent.session"]

The object type. Always agent.session.

required_actions: List[RequiredAction]

Actions that must be completed before the session can continue.

status: Literal["idle", "in_progress", "requires_action", "failed"]

The current status of the session.

usage: Optional[TokenUsage]

Best-effort token usage for the session, or null if unknown. Recorded usage may change.

vault_ids: List[str]

The IDs of vaults made available to the session.

spend_control: Optional[SpendControl]

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

List agent sessions

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.beta.agents.sessions.list()
page = page.data[0]
print(page.id)
{
  "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"
}