---
title: "Create session via alias"
method: POST
path: "/v2/agent_aliases/{alias_key}/sessions"
tags: ["Agent Aliases"]
---

# Create session via alias

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

Creates a session by routing through an alias. The alias's policy selects the underlying agent that owns the session. Subsequent operations on the session can use this alias or the direct path `/v2/agents/{resolved_agent_key}/sessions/{session_key}`.

## 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.

## Headers

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

## Request body

- CreateAgentSessionRequest — Request object for creating a new agent session.
  - `key` string — A unique key that identifies an agent session.
  - `name` string — Human-readable name for the session.
  - `description` string — A short description of the session's purpose. If omitted, the platform generates one after the session produces events. Pass an empty string to suppress auto-generation.
  - `metadata` object — Arbitrary metadata associated with the session.
  - `enabled` boolean — Whether the session should be enabled upon creation.
  - `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 set to 0, the session does not expire.
  - `secrets` object — Session-scoped secrets to store on the new session. Map of secret name to plaintext value. Encrypted at rest with the owning agent's encryption key. Referenced from tool `argument_override` via `{"$ref": "session.secrets.<name>"}`. Returned masked (`****`) on reads.
  - `from_session` object — Create a new session by forking an existing one. By default, copies all visible events and artifacts from the source session without compaction. Optionally specify exactly one of include_up_to_event_id or compact_up_to_event_id to control which events are included and whether they are compacted. These two fields are mutually exclusive.
    - `agent_key` string — Agent key of the source session (defaults to current agent).
    - `session_key` string, required — Session key of the source session.
    - `include_up_to_event_id` string, nullable — Only include events up to and including this event ID from the source session, copying them verbatim. Events after this ID are excluded. If null (the default), all visible events are included. Mutually exclusive with compact_up_to_event_id.
    - `compact_up_to_event_id` string, nullable — Compact all source events up to this event ID into a summary instead of copying them verbatim. If null (the default), events are copied verbatim. Mutually exclusive with include_up_to_event_id.

## Response `201`

The newly created session, owned by the agent the alias's policy resolved to.

- AgentSession — A session for interacting with an agent. The session holds the agent's context.
  - `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.

## Other responses

- `400` — The request is malformed, or the alias's policy cannot resolve against the session context.
- `403` — Permissions do not allow creating sessions via this alias.
- `404` — Alias not found or not currently active.

---

[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/fca567a46b3a/schema)