> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```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"}' ``` ## OpenAPI ````yaml post /v1/agents/sessions/list openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/agents/sessions/list: post: tags: - Agent Sessions summary: List Sessions description: |- 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"}' ``` operationId: list_sessions_v1_agents_sessions_list_post parameters: - name: limit in: query required: false schema: anyOf: - maximum: 1000 minimum: 1 type: integer - type: 'null' title: Limit - name: page_size in: query required: false schema: anyOf: - maximum: 1000 minimum: 1 type: integer - type: 'null' title: Page Size - name: offset in: query required: false schema: anyOf: - type: integer maximum: 10000 minimum: 0 - type: 'null' title: Offset - name: page in: query required: false schema: anyOf: - type: integer minimum: 1 - type: 'null' title: Page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor - name: include_total in: query required: false schema: type: boolean default: false title: Include Total requestBody: content: application/json: schema: $ref: '#/components/schemas/ListSessionsRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListSessionsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ListSessionsRequest: properties: status: anyOf: - $ref: '#/components/schemas/SessionStatus' - type: 'null' description: Filter by session status filters: anyOf: - additionalProperties: true type: object - type: 'null' title: Filters description: Additional filters sort: anyOf: - additionalProperties: true type: object - type: 'null' title: Sort description: Sort configuration type: object title: ListSessionsRequest description: |- 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"} ) ``` ListSessionsResponse: properties: results: items: $ref: '#/components/schemas/GetSessionResponse' type: array title: Results description: Session list total: type: integer title: Total description: Total matching sessions pagination: additionalProperties: true type: object title: Pagination description: Pagination information type: object required: - results - total - pagination title: ListSessionsResponse description: |- 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={...} ) ``` ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SessionStatus: type: string enum: - active - idle - archived - terminated title: SessionStatus description: |- 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 GetSessionResponse: properties: session_id: type: string title: Session Id description: Session identifier namespace_id: type: string title: Namespace Id description: Namespace identifier internal_id: type: string title: Internal Id description: Organization internal ID user_id: anyOf: - type: string - type: 'null' title: User Id description: User identifier session_name: anyOf: - type: string - type: 'null' title: Session Name description: Auto-generated session name based on first conversation agent_config: $ref: '#/components/schemas/AgentConfig' description: Agent configuration user_memory: additionalProperties: true type: object title: User Memory description: User memory/preferences status: $ref: '#/components/schemas/SessionStatus' description: Session status message_count: type: integer title: Message Count description: Total messages in session stats: $ref: '#/components/schemas/SessionStats' description: Session statistics created_at: type: string format: date-time title: Created At description: Creation timestamp updated_at: type: string format: date-time title: Updated At description: Last update timestamp last_activity_at: type: string format: date-time title: Last Activity At description: Last activity timestamp expires_at: type: string format: date-time title: Expires At description: Expiration timestamp type: object required: - session_id - namespace_id - internal_id - agent_config - status - message_count - stats - created_at - updated_at - last_activity_at - expires_at title: GetSessionResponse description: |- Response for retrieving session metadata. Attributes: session_id: Session identifier namespace_id: Namespace identifier internal_id: Organization internal ID user_id: Optional user identifier session_name: Auto-generated session name (null until first message) agent_config: Agent configuration user_memory: User memory/preferences status: Session status message_count: Total messages in session stats: Session statistics created_at: Creation timestamp updated_at: Last update timestamp last_activity_at: Last activity timestamp expires_at: Expiration timestamp Example: ```python response = GetSessionResponse( session_id="ses_abc123", namespace_id="ns_xyz789", internal_id="int_abc123", session_name="Video search for ML tutorials", agent_config=AgentConfig(...), status="active", message_count=10, stats=SessionStats(...) ) ``` ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError AgentConfig: properties: model: type: string title: Model description: >- LLM model identifier. Options: 'gemini-2.5-flash-lite' (fastest, cheapest), 'gemini-2.5-pro' (better quality), 'gpt-4o-mini', 'gpt-4o' default: gemini-2.5-flash-lite temperature: type: number maximum: 2 minimum: 0 title: Temperature description: >- 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. default: 0.7 max_tokens: type: integer maximum: 100000 minimum: 1 title: Max Tokens description: Maximum tokens per response default: 4096 system_prompt: type: string title: System Prompt description: System prompt that defines agent behavior and persona default: >- You are a helpful AI assistant with access to Mixpeek's data infrastructure. available_tools: items: type: string type: array title: Available Tools description: >- 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. type: object title: AgentConfig description: >- 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" ] ) ``` examples: - available_tools: - list_retrievers - get_retriever - execute_retriever - list_collections - get_collection max_tokens: 4096 model: claude-sonnet-4-5-20250929 system_prompt: >- You are a video analysis assistant that helps users find and analyze video content. temperature: 0.7 - available_tools: - list_retrievers - execute_retriever max_tokens: 2048 model: claude-3-haiku-20240307 system_prompt: You are a quick search assistant. Be concise. temperature: 0.3 SessionStats: properties: total_messages: type: integer minimum: 0 title: Total Messages description: Total messages sent in session default: 0 total_tokens: type: integer minimum: 0 title: Total Tokens description: Cumulative tokens used (for cost tracking) default: 0 total_tool_calls: type: integer minimum: 0 title: Total Tool Calls description: Total tool invocations default: 0 avg_latency_ms: type: number minimum: 0 title: Avg Latency Ms description: Average message latency in milliseconds default: 0 type: object title: SessionStats description: |- 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") ``` ````