List sessions

Replaces get_sessions

list_sessions is the recommended replacement for the deprecated get_sessions function. It returns the same fields, runs faster (backed by pre-aggregated session tables), adds a has_recording filter, and supports built-in pagination via row_limit / row_offset.

Overview

The list_sessions function lets you query and analyze conversation sessions from your AI agents. Use this endpoint to:

Monitor conversation quality and AI agent performance
Filter sessions by various criteria (date range, ratings, sentiment, tags, CSAT scores)
Identify sessions that need review or improvement
Page through large result sets using row_limit / row_offset
Export session data for reporting and analytics

Quick start

Here's a simple example to get sessions from the last week for a specific AI agent:

query ListSessions(
  $accountId: uuid!
  $brainIds: _uuid
  $startDate: timestamp
  $endDate: timestamp
  $rowLimit: Int
  $rowOffset: Int
) {
  list_sessions(
    args: {
      account_id: $accountId
      brain_parent_ids: $brainIds
      start_time: $startDate
      end_time: $endDate
      row_limit: $rowLimit
      row_offset: $rowOffset
    }
  ) {
    session_id
    start_time
    end_time
    channel
    rating
    total_user_messages
  }
}

Variables:

{
  "accountId": "b3de1234-5678-90ab-cdef-1234567890ab",
  "brainIds": "{a2wv9283-9b53-4d7b-b77d-2650f3a1a99c}",
  "startDate": "2024-01-15",
  "endDate": "2024-01-22",
  "rowLimit": 100,
  "rowOffset": 0
}

Try it

Use the interactive playground below to test the query. Replace the variables with your own account and AI agent IDs.

Loading GraphQL Playground...

Parameters

Filtering parameters

Parameter	Type	Description
Date range
`startDate`	`timestamp`	Start date (format: `yyyy-mm-dd`). Defaults to 1 month ago
`endDate`	`timestamp`	End date (format: `yyyy-mm-dd`). Defaults to now
Entity filters
`deskIds`	`_uuid`	Filter by desk IDs
`brainIds`	`_uuid`	Filter by AI Agent IDs
`integrationIds`	`_uuid`	Filter by integration IDs
`languageModelIds`	`_text`	Filter by language model IDs
Session filters
`channels`	`_text`	Filter by channels (web, facebook, viber, etc.)
`tags`	`_text`	Filter by session tags
`ratings`	`_int4`	Filter by ratings (1-5)
User identification
`sessionId`	`String`	Get specific session by ID
`userId`	`String`	Filter by user ID
`userName`	`String`	Filter by user name
`userEmail`	`String`	Filter by user email
`channelUserId`	`String`	Filter by channel user ID
`externalUserId`	`String`	Filter by external user ID
Quality metrics
`minNumUserMessages`	`Int`	Minimum user messages in session
`minNumThumbsUp`	`Int`	Minimum thumbs up count
`minNumThumbsDown`	`Int`	Minimum thumbs down count
`csatBrain`	`_int4`	Customer satisfaction score for AI agent
`csatHumanAgent`	`_int4`	Customer satisfaction score for human agent
`userSentiment`	`_int4`	Filter by user sentiment
`goalAchieved`	`_int4`	Filter by goal achievement status
Session properties
`isContained`	`Boolean`	Contained sessions
`isCovered`	`Boolean`	Covered sessions
`isTest`	`Boolean`	Exclude test sessions
`isMeaningful`	`Boolean`	Filter meaningful conversations
`hasCollection`	`Boolean`	Sessions with collection matches
`hasRecording`	`Boolean`	Sessions that have a call recording attached
`insightFilters`	`jsonb`	Filter by session insights
Pagination
`rowLimit`	`Int`	Maximum number of rows to return. Pair with `list_sessions_count` for totals
`rowOffset`	`Int`	Number of rows to skip. Defaults to `0`

Response fields

Session information

Field	Type	Description
`session_id`	`String`	Unique session identifier
`start_time`	`timestamp`	Session start time
`end_time`	`timestamp`	Session end time
`channel`	`String`	Communication channel
`account_id`	`uuid`	Account identifier
`desk_id`	`uuid`	Associated desk ID
`integration_id`	`uuid`	Integration ID

User information

Field	Type	Description
`user_id`	`String`	User identifier
`user_name`	`String`	User display name
`user_email`	`String`	User email address
`channel_user_id`	`String`	Channel-specific user ID
`external_user_id`	`String`	External system user ID

Metrics and quality

Field	Type	Description
`total_user_messages`	`Int`	Number of user messages
`rating`	`Int`	User rating (1-5, null if unrated)
`thumbs_up`	`Int`	Number of thumbs up received
`thumbs_down`	`Int`	Number of thumbs down received
`csat_brain`	`Int`	Customer satisfaction for AI agent
`csat_human_agent`	`Int`	Customer satisfaction for human agent
`user_sentiment`	`Int`	User sentiment score
`goal_achieved`	`Int`	Goal achievement status
`error_count`	`Int`	Number of errors in session

Session properties

Field	Type	Description
`is_contained`	`Boolean`	Session handled entirely by AI
`is_covered`	`Boolean`	Session topics within AI scope
`is_meaningful`	`Boolean`	Meaningful conversation
`is_test`	`Boolean`	Test/preview session
`has_recording`	`Boolean`	Session has an attached call recording
`tags`	`_text`	Associated tags
`insights`	`jsonb`	Session insights data
`participated_agents`	`Array`	Human agents involved (empty array if none)
`participated_brains`	`Array`	AI Agents involved with details (brain_id, brain_version, brain_parent_id)
`participated_collections`	`Array`	Knowledge base collection IDs used
`participated_language_models`	`Array`	Language models used with details (model_id, brain_parent_id, language_model_id)

Pagination

list_sessions accepts row_limit and row_offset so you can page through results without re-issuing increasingly large queries. To show a total row count alongside the current page (for example in a paginated UI), combine it with list_sessions_count, which accepts the same filtering arguments and returns just the total.

query ListSessionsPaginated(
  $accountId: uuid!
  $startDate: timestamp
  $endDate: timestamp
  $rowLimit: Int
  $rowOffset: Int
) {
  rows: list_sessions(
    args: {
      account_id: $accountId
      start_time: $startDate
      end_time: $endDate
      row_limit: $rowLimit
      row_offset: $rowOffset
    }
  ) {
    session_id
    start_time
    end_time
    channel
    rating
  }
  total: list_sessions_count(
    args: {
      account_id: $accountId
      start_time: $startDate
      end_time: $endDate
    }
  ) {
    total_count
  }
}

Use the same filter arguments on both functions so the total matches the filtered result set.

Common use cases

Basic query
Poor ratings
Escalated sessions
With recordings
Specific user

Get sessions for a specific desk within a date range:

{
  "accountId": "b3de1234-5678-90ab-cdef-1234567890ab",
  "deskIds": "{d2be0283-9b53-4d7b-b77d-2650f3a1a99c}",
  "startDate": "2024-01-08",
  "endDate": "2024-01-17"
}

Get sessions with ratings of 1-3:

{
  "accountId": "b3de1234-5678-90ab-cdef-1234567890ab",
  "deskIds": "{d2be0283-9b53-4d7b-b77d-2650f3a1a99c}",
  "ratings": "{1,2,3}",
  "startDate": "2024-01-08",
  "endDate": "2024-01-17"
}

Find non-contained sessions (escalated to human):

{
  "accountId": "b3de1234-5678-90ab-cdef-1234567890ab",
  "brainIds": "{a2wv9283-9b53-4d7b-b77d-2650f3a1a99c}",
  "isContained": false,
  "startDate": "2024-01-08",
  "endDate": "2024-01-17"
}

Only sessions that have a call recording attached:

{
  "accountId": "b3de1234-5678-90ab-cdef-1234567890ab",
  "hasRecording": true,
  "startDate": "2024-01-08",
  "endDate": "2024-01-17"
}

Find sessions for a specific user:

{
  "accountId": "b3de1234-5678-90ab-cdef-1234567890ab",
  "userId": "mApUE81oSmzUWTA_w2ZbL",
  "channelUserId": "ePlhV5VeCXg"
}

Example response

{
  "data": {
    "list_sessions": [
      {
        "account_id": "8fb5d9d4-c3f0-4165-a8e9-41655e0fe624",
        "channel": "web",
        "channel_user_id": null,
        "csat_brain": null,
        "csat_human_agent": null,
        "desk_id": "4168c7cf-1ffc-4f2d-92f9-c5b9d7b2e4ff",
        "start_time": "2025-10-24T09:21:50.446",
        "end_time": "2025-10-24T09:22:22.143",
        "error_count": 0,
        "external_user_id": null,
        "goal_achieved": null,
        "has_recording": false,
        "insights": null,
        "integration_id": "92b8a685-9c06-4728-8f0e-446dbd7832d7",
        "is_contained": true,
        "is_covered": true,
        "is_meaningful": false,
        "is_test": true,
        "participated_agents": [],
        "participated_brains": [
          {
            "brain_id": "4d3f98e0-47da-418c-a487-99b5bdc180c4",
            "brain_version": "8",
            "brain_parent_id": "21f45e59-feab-445b-a133-0bb5bf26912f"
          }
        ],
        "participated_collections": ["427c3ea2-e481-4575-8d86-657c28a6bdfe"],
        "participated_language_models": [
          {
            "model_id": "base",
            "brain_parent_id": "21f45e59-feab-445b-a133-0bb5bf26912f",
            "language_model_id": null
          }
        ],
        "rating": null,
        "session_id": "58c0c8ca-4830-4782-adb8-31f1597bdad9",
        "tags": ["kg"],
        "thumbs_down": 0,
        "thumbs_up": 1,
        "total_user_messages": 3,
        "user_email": "test@test.com",
        "user_id": "YYz6i3khqoyEUrksmI-95",
        "user_name": "Visitor 48",
        "user_sentiment": null
      }
    ]
  }
}

Full query reference

View complete GraphQL query with all available fields

query ListSessions(
  $accountId: uuid!
  $brainIds: _uuid
  $channels: _text
  $channelUserId: String
  $csatBrain: _int4
  $csatHumanAgent: _int4
  $deskIds: _uuid
  $startDate: timestamp
  $endDate: timestamp
  $externalUserId: String
  $goalAchieved: _int4
  $hasCollection: Boolean
  $hasRecording: Boolean
  $insightFilters: jsonb
  $integrationIds: _uuid
  $isContained: Boolean
  $isCovered: Boolean
  $isMeaningful: Boolean
  $isTest: Boolean
  $languageModelIds: _text
  $minNumThumbsDown: Int
  $minNumThumbsUp: Int
  $minNumUserMessages: Int
  $ratings: _int4
  $sessionId: String
  $tags: _text
  $userEmail: String
  $userId: String
  $userName: String
  $userSentiment: _int4
  $rowLimit: Int
  $rowOffset: Int
) {
  list_sessions(
    args: {
      account_id: $accountId
      brain_parent_ids: $brainIds
      channels: $channels
      channel_user_id: $channelUserId
      csat_brain: $csatBrain
      csat_human_agent: $csatHumanAgent
      desk_ids: $deskIds
      start_time: $startDate
      end_time: $endDate
      external_user_id: $externalUserId
      goal_achieved: $goalAchieved
      has_collection: $hasCollection
      has_recording: $hasRecording
      insight_filters: $insightFilters
      integration_ids: $integrationIds
      is_contained: $isContained
      is_covered: $isCovered
      is_meaningful: $isMeaningful
      is_test: $isTest
      language_model_ids: $languageModelIds
      min_num_thumbs_down: $minNumThumbsDown
      min_num_thumbs_up: $minNumThumbsUp
      min_num_user_messages: $minNumUserMessages
      ratings: $ratings
      session_id: $sessionId
      tags: $tags
      user_email: $userEmail
      user_id: $userId
      user_name: $userName
      user_sentiment: $userSentiment
      row_limit: $rowLimit
      row_offset: $rowOffset
    }
  ) {
    account_id
    channel
    channel_user_id
    csat_brain
    csat_human_agent
    desk_id
    start_time
    end_time
    error_count
    external_user_id
    goal_achieved
    has_recording
    insights
    integration_id
    is_contained
    is_covered
    is_meaningful
    is_test
    participated_agents
    participated_brains
    participated_collections
    participated_language_models
    rating
    session_id
    tags
    thumbs_down
    thumbs_up
    total_user_messages
    user_email
    user_id
    user_name
    user_sentiment
  }
}

Overview​

Quick start​

Try it​

Parameters​

Filtering parameters​

Response fields​

Session information​

User information​

Metrics and quality​

Session properties​

Pagination​

Common use cases​

Example response​

Full query reference​