Skip to content
Agents
Sessions

List Sessions

GET
/v1/sessions
curl --request GET \
--url 'https://agents.lumalabs.ai/v1/sessions?limit=25' \
--header 'Authorization: Bearer <token>'

Keyset-paginated list of the caller's sessions, newest first.

Scoped to the token's (client_id, client_user_id) pair — the same boundary get_session_or_404 enforces, so the list returns exactly the sessions this token could already read one by one. Widening it to the whole client would hand one end-user's JWT the session ids and tags of every sibling end-user, which is the cross-user leak the pair-check exists to close.

?metadata.<key>=<value> may repeat; the filters AND together and are matched by JSONB containment, so a session carrying extra tags still matches.

scope_id
Any of:
string

Restrict to one scope.

state
Any of:
SessionState
string
Allowed values: active closing suspended error completed expired

Restrict to one lifecycle state.

limit
Limit
integer
default: 25 >= 1 <= 100
cursor
Any of:
string

Opaque token from a previous page's next_cursor.

Successful Response

Media typeapplication/json
ListSessionsResponse

Keyset-paginated session list (GET /v1/sessions). See ListScopesResponse.

object
data
required
Data
Array<object>
SessionListItem

One row of GET /v1/sessions — the cheap fields only.

Deliberately not a SessionSnapshotResponse: a list must not pay for the per-row message peek turn_running needs, and a partner scanning pages does not want every plan artifact inlined. Fetch GET /v1/sessions/{id} for the live view of one session.

object
created_at
required
Created At
string format: date-time
expires_at
Any of:
string format: date-time
metadata
Metadata
object
key
additional properties
string
scope_id
required
Scope Id
string
session_id
required
Session Id
string
state
required
SessionState
string
Allowed values: active closing suspended error completed expired
updated_at
required
Updated At
string format: date-time
has_more
required
Has More
boolean
next_cursor
Any of:
string
Example
{
"data": [
{
"state": "active"
}
]
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}