List Sessions

GET/v1/sessions

List sessions for your organization, ordered most-recently-created first. Returns a page of Session objects with an opaque cursor for the next page.

Query Parameters

Parameter	Type	Required	Description
agent_id	string	❌	Filter sessions created with this agent ID
agent_version	integer	❌	Filter by agent version. Only applies when agent_id is also set.
statuses	string[]	❌	Filter by status. Repeat to match any of multiple: ?statuses=idle&statuses=running
include_archived	boolean	❌	Include archived sessions. Default false.
created_at_gte	string	❌	Only sessions created at or after this RFC 3339 time.
created_at_lte	string	❌	Only sessions created at or before this RFC 3339 time.
limit	integer	❌	Page size. Default 20, max 100.
page	string	❌	Opaque cursor from a previous response's next_page.

Status Values

• idle — Waiting for input
• running — Agent is actively executing
• rescheduling — Transient error, retrying
• terminated — Session ended

Request Examples

Python

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-sb-YOUR_KEY",
    base_url="https://api.sandbase.ai"
)

page = client.beta.sessions.list(agent_id="agent_01HqR2k7...", limit=20)
for session in page.data:
    print(f"{session.id} — {session.status} — {session.title}")

cURL

curl "https://api.sandbase.ai/v1/sessions?agent_id=agent_01HqR2k7...&statuses=idle&limit=20" \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Response

{
  "data": [
    {
      "id": "sess_01abc...",
      "type": "session",
      "status": "idle",
      "title": "Research task",
      "agent_id": "agent_01HqR2k7...",
      "agent_version": 1,
      "environment_id": "env_01abc...",
      "usage": null,
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-05-29T10:00:00Z",
      "updated_at": "2026-05-29T10:02:00Z"
    }
  ],
  "next_page": "page_eyJjIjoiMjAyNi0wNS0yOVQxMDowMDowMFoiLCJpIjoic2Vzc18wMSJ9"
}

Pagination

Results are ordered by created_at descending (ties broken by id). When more results exist, the response includes a next_page cursor; pass it back as the page parameter. When next_page is absent, you've reached the last page.

Errors

Status	Type	Description
400	invalid_request	Invalid page cursor or query parameters
401	authentication_error	Invalid or missing API key