---
title: "List agent sessions"
method: GET
path: "/v2/agents/{agent_key}/sessions"
tags: ["Agent Sessions"]
---

# List agent sessions

`GET /v2/agents/{agent_key}/sessions`

Lists all sessions for the specified agent. Returns high-level information about each session, with optional filtering and pagination. Use this operation to browse existing sessions or to locate a specific session key for further inspection or updates.

## Path parameters

- `agent_key` string, required — A unique key that identifies an agent.

## Query parameters

- `filter` string
- `metadata_filter` string
- `limit` integer
- `page_key` string

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

List of available agent sessions.

- ListAgentSessionsResponse — Response containing a list of agent sessions.
  - `sessions` AgentSession[], required — List of agent sessions.
    - `key` string, required — A unique key that identifies an agent session.
    - `agent_key` string, required — A unique key that identifies an agent.
    - `name` string, required — Human-readable name for the session.
    - `description` string — A short description of the session's purpose. If omitted at creation, the platform generates one after the agent produces events. An empty string indicates auto-generation is disabled for this session.
    - `metadata` object — Arbitrary metadata associated with the session.
    - `current_step_name` string, nullable — The step name the session will resume at on the next user message. If null, the session starts at the agent's first_step.
    - `enabled` boolean, required — Whether the session is currently active and can accept new messages.
    - `status` 'unstarted' | 'running' | 'stopped' — Lifecycle status of the session. `unstarted` before the session receives any event, `running` while the agent is producing events, and `stopped` when the session is idle with no event in flight. `stopped` implies no terminating action — the session returns to `running` on the next request.
    - `created_by_agent_key` string — A unique key that identifies an agent.
    - `created_by_session_key` string — A unique key that identifies an agent session.
    - `tti_minutes` integer — Time-to-idle in minutes for the session. If no events occur in the session for this duration, the session is deleted automatically. If not specified, the session does not expire.
    - `created_at` string, date-time, required — Timestamp when the session was created.
    - `session_context_usage` SessionContextUsage — Token usage of the session's most recent agent call, reflecting current context window consumption. Not a running total across calls.
      - `input_tokens` InputTokens — Input token usage details.
        - `count` integer — Number of input tokens consumed by the most recent agent call, including cached tokens.
        - `cached_tokens` integer — Subset of count served from the prompt cache. Omitted when no input tokens were served from the cache.
      - `output_tokens` OutputTokens — Output token usage details.
        - `count` integer — Number of output tokens generated by the most recent agent call.
        - `reasoning_tokens` integer — Number of tokens used for reasoning/thinking.
      - `total_tokens` integer — Input plus output tokens of the most recent agent call. Can be used with model_context_window to calculate context utilization percentage.
      - `model_context_window` integer — Maximum context window size in tokens for the model used by this session. Can be used with total_tokens to calculate context utilization percentage.
    - `effective_compaction` CompactionConfig — Configuration for automatic context compaction.
      - `enabled` boolean — Enable automatic context compaction.
      - `threshold_percent` integer — Context usage % (50-95) at which compaction is applied.
      - `keep_recent_inputs` integer — Number of recent turns to keep verbatim (not compacted).
      - `compaction_message` string — Custom additional instructions for the compaction summarization prompt.
      - `tool_event_policy` 'exclude' | 'include_outputs' | 'include_all' — How tool events are included in the compaction input.
    - `alias_key` string, nullable — If this session was created through an alias (`POST /v2/agent_aliases/{alias_key}/sessions`), the alias key the caller used. The `agent_key` field above is the resolved agent the alias's policy picked. Null when the session was created directly under an agent (`POST /v2/agents/{agent_key}/sessions`).
    - `secrets` object — Session-scoped secrets, with values masked as `"****"`. Plaintext is never returned on read; tools resolve the real value via `argument_override` with `{"$ref": "session.secrets.<name>"}`. Set or rotate via the session create or update request.
  - `metadata` ListMetadata, required — The standard metadata in the response of a list operation.
    - `page_key` string — The page key for the next page of results. Pass it as a query parameter to request the next page.

## Other responses

- `403` — Permissions do not allow listing agent sessions.
- `404` — Agent not found.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/e85040b266cc/schema)