Sessions preview

Deprecated

get_sessions is deprecated and will be removed in a future release. Use list_sessions instead. It returns the same response fields, runs faster, and supports pagination.

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
}

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

note

Changed in October 2026: with two or more tags, results now include only sessions that have all of them. Pass tags_match: "any" for the previous behavior.

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. Several tags match sessions that have all of them by default
`tags_match`	`String`	`"all"` (default) or `"any"`. With `"all"`, a session must have every tag in `tags`. With `"any"`, one tag is enough
`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`	`user_sentiment_type`	User sentiment score
`goal_achieved`	`goal_achieved_type`	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": "PWxLcHkYCFEyOMhqPfMBP0KZG5DZ1lVMTPIiBAcVmw8",
        "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": "Vb3kQz8LmT1sYp0XcRw7NnHf4GdJ2aEuK9oW6iSyMlA",
        "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
  }
}

Overview​

Quick start​

Try it​

Parameters​

Filtering parameters​

Response fields​

Session information​

User information​

Metrics and quality​

Session properties​

Common use cases​

Example response​

Full query reference​