---
title: "Get Session"
method: GET
path: "/v1/agents/sessions/{session_id}"
tags: ["Agent Sessions"]
---

# Get Session

`GET /v1/agents/sessions/{session_id}`

Get session metadata by ID.

Args:
    request: FastAPI request with tenant context
    session_id: Session identifier

Returns:
    GetSessionResponse with session metadata

Raises:
    NotFoundError: If session not found

Example:
    ```bash
    curl -X GET http://localhost:8000/v1/agents/sessions/ses_abc123 \
      -H "Authorization: Bearer {api_key}" \
      -H "X-Namespace: {namespace_id}"
    ```

## Path parameters

- `session_id` string, required — Session ID

## Response `200`

Successful Response

- GetSessionResponse — 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(...) ) ```
  - `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

## 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/versions/5d4c905106b4/schema)