List Sessions

List agent sessions with filtering by agent, status, and pagination

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. Tenant-scoped via X-Tenant-ID.

Query Parameters

agent_id · string

Filter sessions by the owning agent’s MAIP identifier (e.g., maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH).

status · string

Filter by session status. One of: "active", "expired", "terminated", "handed_off".

limit · integer

Maximum number of sessions to return per page. Range: 1-200. Default: 50.

offset · integer

Number of records to skip for pagination. Default: 0.

Response

sessions · 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.

total · integer

Total count of sessions matching the filter criteria, across all pages.

Example

curl -G https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: tl_live_..." \
  -d "agent_id=maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH" \
  -d "status=active" \
  -d "limit=25" \
  -d "offset=0"

---

Session Status Reference

Status	Description
active	Session is valid and accepting requests
expired	Session TTL has elapsed; no longer valid
terminated	Session was explicitly terminated via API
handed_off	Session was transferred to another agent via handoff