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

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"
}

Poor ratings

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"
}

Escalated sessions

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"
}

Multi-channel

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"
}

Specific user

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
  }
}