List Sessions

List agent sessions in the namespace.

Args: request: FastAPI request with tenant context list_request: Optional filters and sorting pagination: Pagination parameters

Returns: ListSessionsResponse with session list

Example:

curl -X POST http://localhost:8000/v1/agents/sessions/list \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Namespace: {namespace_id}" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

POST /v1/agents/sessions/list

List Sessions

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/agents/sessions/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "filters": {},
  "sort": {}
}
'

200

{
  "results": [
    {
      "session_id": "<string>",
      "namespace_id": "<string>",
      "internal_id": "<string>",
      "agent_config": {
        "model": "gemini-2.5-flash-lite",
        "temperature": 0.7,
        "max_tokens": 4096,
        "system_prompt": "You are a helpful AI assistant with access to Mixpeek's data infrastructure.",
        "available_tools": [
          "<string>"
        ]
      },
      "message_count": 123,
      "stats": {
        "total_messages": 0,
        "total_tokens": 0,
        "total_tool_calls": 0,
        "avg_latency_ms": 0
      },
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "last_activity_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "user_id": "<string>",
      "session_name": "<string>",
      "user_memory": {}
    }
  ],
  "total": 123,
  "pagination": {}
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Query Parameters

limit · integer | null

Required range: 1 <= x <= 1000

page_size · integer | null

Required range: 1 <= x <= 1000

offset · integer | null

Required range: 0 <= x <= 10000

page · integer | null

Required range: x >= 1

cursor · string | null

next_cursor · string | null

after · string | null

include_total · boolean · default: false

Body

application/json

Request payload for listing sessions.

Attributes: status: Optional status filter filters: Optional additional filters sort: Optional sort configuration

Example: python request = ListSessionsRequest( status="active", filters={"user_id": "user_123"} )

status · enum<string> | null

Filter by session status

Available options: active, idle, archived, terminated

filters · Filters · object | null

Additional filters

sort · Sort · object | null

Sort configuration

Response

200

application/json

Successful Response

Response for listing sessions.

Attributes: results: List of session summaries total: Total number of sessions matching query pagination: Pagination information

Example: python response = ListSessionsResponse( results=[...], total=50, pagination={...} )

results · GetSessionResponse · object[] · required

Session list

Show child attributes

total · integer · required

Total matching sessions

pagination · Pagination · object · required

Pagination information