---
title: "List sessions routed via this alias"
method: GET
path: "/v2/agent_aliases/{alias_key}/sessions"
tags: ["Agent Aliases"]
---

# List sessions routed via this alias

`GET /v2/agent_aliases/{alias_key}/sessions`

Lists sessions originally created via this alias (sessions whose `alias_key` matches). Sessions are also reachable under their resolved agent's URL. This endpoint is the alias-scoped view.

## Path parameters

- `alias_key` string, required — The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to `/v2/agent_aliases/{key}/...` target the alias. Calls to `/v2/agents/{key}/...` target the agent.

## Query parameters

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

## Headers

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

## Response `200`

Sessions created via this alias.

- 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 alias-routed sessions.
- `404` — Alias 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/revisions/e85040b266cc/schema)