Sessions preview
Overview
The Sessions Preview API allows you to 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
- 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 GetSessions(
  $accountId: uuid!
  $brainIds: _uuid
  $startDate: timestamp
  $endDate: timestamp
  $limit: Int
) {
  get_sessions(
    limit: $limit
    args: {
      account_id: $accountId
      brain_parent_ids: $brainIds
      start_time: $startDate
      end_time: $endDate
    }
  ) {
    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",
  "limit": 100
}
Parameters
Filtering parameters
| Parameter | Type | Description | 
|---|---|---|
| Date range | ||
| startDate | timestamp | Start date (format: yyyy-mm-dd) | 
| endDate | timestamp | End date (format: yyyy-mm-dd) | 
| 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 | 
| insightFilters | jsonb | Filter by session insights | 
| Other | ||
| limit | Int | Maximum number of results | 
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 | 
| 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) | 
Common use cases
- Basic query
- Poor ratings
- Escalated sessions
- Multi-channel
- 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"
}
Query across multiple channels:
{
  "accountId": "b3de1234-5678-90ab-cdef-1234567890ab",
  "deskIds": "{d2be0283-9b53-4d7b-b77d-2650f3a1a99c}",
  "channels": "{web, facebook, viber}",
  "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": {
    "get_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,
        "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
      },
      {
        "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:20:31.136",
        "end_time": "2025-10-24T09:21:27.646",
        "error_count": 0,
        "external_user_id": null,
        "goal_achieved": null,
        "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": "466fc385-706d-4514-9bf9-7cab74c52c52",
        "tags": [
          "kg"
        ],
        "thumbs_down": 1,
        "thumbs_up": 1,
        "total_user_messages": 4,
        "user_email": "konstantinos@moveo.ai",
        "user_id": "a4ptQv8d-TUEes_L8Ekxs",
        "user_name": "Visitor 47",
        "user_sentiment": null
      }
    ]
  }
}
Full query reference
View complete GraphQL query with all available fields
query GetSessions(
  $accountId: uuid!
  $brainIds: _uuid
  $channels: _text
  $channelUserId: String
  $csatBrain: _int4
  $csatHumanAgent: _int4
  $deskIds: _uuid
  $startDate: timestamp
  $endDate: timestamp
  $externalUserId: String
  $goalAchieved: _int4
  $hasCollection: 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
  $limit: Int
) {
  get_sessions(
    limit: $limit
    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
      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
    }
  ) {
    account_id
    channel
    channel_user_id
    csat_brain
    csat_human_agent
    desk_id
    start_time
    end_time
    error_count
    external_user_id
    goal_achieved
    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
  }
}