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

SessionListPage beta().agents().sessions().list(SessionListParamsparams = SessionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
GET/agents/sessions

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

ParametersExpand Collapse
SessionListParams params
Optional<String> after

Return resources after this resource ID in the selected order.

minLength0
maxLength1048576
Optional<String> agentId

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

minLength0
maxLength1048576
Optional<Long> limit

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

formatint64
minimum1
maximum100
Optional<Order> order

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

ReturnsExpand Collapse
class AgentSession:

A Managed Agents session.

String id

The ID of the session.

minLength0
Agent agent

The agent running in the session.

long createdAt

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

formatint64
Environment environment

The execution environment for the session.

Optional<String> error

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

minLength0
long lastActiveAt

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

formatint64
Metadata metadata

Custom string key-value pairs attached to the session.

JsonValue; object_ "agent.session"constant"agent.session"constant

The object type. Always agent.session.

List<RequiredAction> requiredActions

Actions that must be completed before the session can continue.

Status status

The current status of the session.

Optional<TokenUsage> usage

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

List<String> vaultIds

The IDs of vaults made available to the session.

Optional<SpendControl> spendControl

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

List agent sessions

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionListPage;
import com.openai.models.beta.agents.sessions.SessionListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionListPage page = client.beta().agents().sessions().list();
    }
}
{
  "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"
}