Sign in

v3

latestOpenAPI 3.0.02026-08-081996601.2 MB
Agent Sessions

Get agent session

Returns the full details of a specific agent session, identified by its unique session key. The response includes the session's configuration, metadata, timestamps, and other stored properties. Use this endpoint to inspect the current state of a session or to verify its configuration.

get/v2/agents/{agent_key}/sessions/{session_key}

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique identifier of the agent.

session_keystring required

A unique key that identifies an agent session.

Example:customer_support_chat

The unique key of the session to retrieve.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Response

The requested agent session details.

keystring required

A unique key that identifies an agent session.

agent_keystring required

A unique key that identifies an agent.

namestring required

Human-readable name for the session.

descriptionstring

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.

metadataobject

Arbitrary metadata associated with the session.

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

enabledboolean 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_keystring

A unique key that identifies an agent.

created_by_session_keystring

A unique key that identifies an agent session.

tti_minutesinteger

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_atstring date-time required

Timestamp when the session was created.

alias_keystring 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).

secretsobject

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.

Example response

{
  "key": "customer_support_chat",
  "agent_key": "customer_support",
  "name": "Customer Support Session",
  "description": "Helping customer troubleshoot widget installation issues",
  "metadata": {
    "customer_id": "12345",
    "priority": "high",
    "channel": "web_chat"
  },
  "current_step_name": "billing",
  "enabled": true,
  "status": "stopped",
  "created_by_agent_key": "customer_support",
  "created_by_session_key": "customer_support_chat",
  "tti_minutes": 60,
  "created_at": "2024-01-15T10:30:00Z",
  "session_context_usage": {
    "input_tokens": {
      "count": 120,
      "cached_tokens": 100
    },
    "output_tokens": {
      "count": 30
    },
    "total_tokens": 150,
    "model_context_window": 200000
  },
  "effective_compaction": {
    "enabled": true,
    "threshold_percent": 80,
    "keep_recent_inputs": 1
  },
  "alias_key": "support",
  "secrets": {
    "slack_user_token": "****"
  }
}