Skip to main content
GET
List Sessions

List Sessions

GET /v1/agent-sessions Returns a paginated list of agent sessions for the authenticated tenant. Results can be filtered by agent ID and session status. Sessions are returned in reverse chronological order (newest first).

Authentication

Requires X-API-Key header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send X-Tenant-ID.

Response

object[]
Array of session objects. Each contains session_id, agent_id, status, scopes, metadata, expires_at, parent_session_id, handed_off_to, ip_address, user_agent, refreshed_at, terminated_at, created_at, and updated_at. Token hashes are never exposed in list responses.
integer
Total count of sessions matching the filter criteria, across all pages.

Example


Session Status Reference

Authorizations

X-API-Key
string
header
required

API key for machine-to-machine authentication

Query Parameters

agent_id
string<uuid>

Filter sessions by agent

status
enum<string>

Filter by session status

Available options:
active,
terminated,
expired
limit
integer
default:25
Required range: 1 <= x <= 100
offset
integer
default:0
Required range: x >= 0

Response

Paginated list of sessions

items
object[]
total
integer