---
title: "List Sessions"
method: POST
path: "/v1/agents/sessions/list"
tags: ["Agent Sessions"]
---

# List Sessions

`POST /v1/agents/sessions/list`

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:
    ```bash
    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"}'
    ```

## Query parameters

- `limit` integer, nullable
- `page_size` integer, nullable
- `offset` integer, nullable
- `page` integer, nullable
- `cursor` string, nullable
- `next_cursor` string, nullable
- `after` string, nullable
- `include_total` boolean

## Request body

- ListSessionsRequest — 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` 'active' | 'idle' | 'archived' | 'terminated' — Session lifecycle states. Attributes: ACTIVE: Session is actively processing messages IDLE: Session exists but no recent activity ARCHIVED: Session archived (read-only) TERMINATED: Session permanently closed
  - `filters` object, nullable — Additional filters
  - `sort` object, nullable — Sort configuration

## Response `200`

Successful Response

- ListSessionsResponse — 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[], required — Session list
    - `session_id` string, required — Session identifier
    - `namespace_id` string, required — Namespace identifier
    - `internal_id` string, required — Organization internal ID
    - `user_id` string, nullable — User identifier
    - `session_name` string, nullable — Auto-generated session name based on first conversation
    - `agent_config` AgentConfig, required — Agent configuration for session. This config is immutable after session creation (similar to RetrieverConfig). To change agent config, create a new session. Attributes: model: LLM model identifier. Supported models: - gemini-2.5-flash (fastest, cheapest) - gemini-2.5-pro (better quality) - gpt-4o-mini, gpt-4o temperature: Sampling temperature for LLM responses (0.0-2.0) - 0.0-0.3: More deterministic, focused responses - 0.5-0.7: Balanced creativity and coherence - 0.8-2.0: More creative, varied responses max_tokens: Maximum tokens per response (1-100000) system_prompt: System prompt that defines agent behavior and persona available_tools: List of tools the agent can call (see AvailableTool enum) Example: ```python config = AgentConfig( model="gemini-2.5-flash-lite", temperature=0.7, max_tokens=4096, system_prompt="You are a helpful video search assistant.", available_tools=[ "smart_search", "execute_retriever", "list_collections" ] ) ```
      - `model` string — LLM model identifier. Options: 'gemini-2.5-flash-lite' (fastest, cheapest), 'gemini-2.5-pro' (better quality), 'gpt-4o-mini', 'gpt-4o'
      - `temperature` number — Sampling temperature for LLM responses (0.0-2.0). Lower values (0.0-0.3) are more deterministic. Higher values (0.8-2.0) are more creative.
      - `max_tokens` integer — Maximum tokens per response
      - `system_prompt` string — System prompt that defines agent behavior and persona
      - `available_tools` string[] — List of API operations the agent is allowed to call. See AvailableTool enum for full list. When provided, the agent's meta-tools will restrict API calls to only these operations. When empty (default), the agent can call any API operation. Key operations: smart_search, execute_retriever, execute_adhoc_retriever, list_collections, list_retrievers, list_buckets, create_upload, analyze_sample_with_pipeline, export_manifest, generate_manifest, detect_intent.
    - `user_memory` object — User memory/preferences
    - `status` 'active' | 'idle' | 'archived' | 'terminated', required — Session lifecycle states. Attributes: ACTIVE: Session is actively processing messages IDLE: Session exists but no recent activity ARCHIVED: Session archived (read-only) TERMINATED: Session permanently closed
    - `message_count` integer, required — Total messages in session
    - `stats` SessionStats, required — Session usage statistics. Tracked in MongoDB session document, updated on each message. Use this to display usage metrics in your UI. Attributes: total_messages: Total messages sent in session total_tokens: Cumulative tokens used (for cost tracking) total_tool_calls: Total tool invocations avg_latency_ms: Average message latency in milliseconds Example: ```python # Display in UI stats = session_response.stats print(f"Messages: {stats.total_messages}") print(f"Tokens used: {stats.total_tokens}") print(f"Tool calls: {stats.total_tool_calls}") print(f"Avg latency: {stats.avg_latency_ms:.0f}ms") ```
      - `total_messages` integer — Total messages sent in session
      - `total_tokens` integer — Cumulative tokens used (for cost tracking)
      - `total_tool_calls` integer — Total tool invocations
      - `avg_latency_ms` number — Average message latency in milliseconds
    - `created_at` string, date-time, required — Creation timestamp
    - `updated_at` string, date-time, required — Last update timestamp
    - `last_activity_at` string, date-time, required — Last activity timestamp
    - `expires_at` string, date-time, required — Expiration timestamp
  - `total` integer, required — Total matching sessions
  - `pagination` object, required — Pagination information

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/f507f74ec843/schema)