Sign in

v2

OpenAPI 3.0.02026-08-051996591.2 MB
Agent Sessions

List agent 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.

get/v2/agents/{agent_key}/sessions

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique identifier of the agent to list sessions for.

Query parameters

filterstring
Example:support.*

A regular expression against session names and descriptions to filter the results.

metadata_filterstring
Example:user_role = 'premium' AND tier >= 2

A filter expression to narrow the list to sessions whose metadata matches. Field names refer to keys on the session's metadata object. Syntax is similar to a SQL WHERE clause, the same as the metadata_filter used in query requests. See metadata filters documentation for more information.

Examples:

  • user_role = 'premium'
  • tier >= 2 AND region = 'us'
  • user LIKE '%@example.com'
  • tier IN ('premium', 'enterprise')
  • tier IS NULL
  • "profile.country" = 'US' (nested fields use a quoted dotted path)
  • 1 IN user_ids (value present in an array)
limitinteger

The maximum number of sessions to return in the list.

page_keystring

The opaque cursor returned in metadata.page_key of the previous response. Omit it to fetch the first page.

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

List of available agent sessions.

Example response

{
  "sessions": [
    {
      "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": "****"
      }
    }
  ],
  "metadata": {
    "page_key": "eyJvZmZzZXQiOjF9"
  }
}