Skip to main content

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

ParameterTypeDescription
Date range
startDatetimestampStart date (format: yyyy-mm-dd)
endDatetimestampEnd date (format: yyyy-mm-dd)
Entity filters
deskIds_uuidFilter by desk IDs
brainIds_uuidFilter by AI Agent IDs
integrationIds_uuidFilter by integration IDs
languageModelIds_textFilter by language model IDs
Session filters
channels_textFilter by channels (web, facebook, viber, etc.)
tags_textFilter by session tags
ratings_int4Filter by ratings (1-5)
User identification
sessionIdStringGet specific session by ID
userIdStringFilter by user ID
userNameStringFilter by user name
userEmailStringFilter by user email
channelUserIdStringFilter by channel user ID
externalUserIdStringFilter by external user ID
Quality metrics
minNumUserMessagesIntMinimum user messages in session
minNumThumbsUpIntMinimum thumbs up count
minNumThumbsDownIntMinimum thumbs down count
csatBrain_int4Customer satisfaction score for AI agent
csatHumanAgent_int4Customer satisfaction score for human agent
userSentiment_int4Filter by user sentiment
goalAchieved_int4Filter by goal achievement status
Session properties
isContainedBooleanContained sessions
isCoveredBooleanCovered sessions
isTestBooleanExclude test sessions
isMeaningfulBooleanFilter meaningful conversations
hasCollectionBooleanSessions with collection matches
insightFiltersjsonbFilter by session insights
Other
limitIntMaximum number of results

Response fields

Session information

FieldTypeDescription
session_idStringUnique session identifier
start_timetimestampSession start time
end_timetimestampSession end time
channelStringCommunication channel
account_iduuidAccount identifier
desk_iduuidAssociated desk ID
integration_iduuidIntegration ID

User information

FieldTypeDescription
user_idStringUser identifier
user_nameStringUser display name
user_emailStringUser email address
channel_user_idStringChannel-specific user ID
external_user_idStringExternal system user ID

Metrics and quality

FieldTypeDescription
total_user_messagesIntNumber of user messages
ratingIntUser rating (1-5, null if unrated)
thumbs_upIntNumber of thumbs up received
thumbs_downIntNumber of thumbs down received
csat_brainIntCustomer satisfaction for AI agent
csat_human_agentIntCustomer satisfaction for human agent
user_sentimentIntUser sentiment score
goal_achievedIntGoal achievement status
error_countIntNumber of errors in session

Session properties

FieldTypeDescription
is_containedBooleanSession handled entirely by AI
is_coveredBooleanSession topics within AI scope
is_meaningfulBooleanMeaningful conversation
is_testBooleanTest/preview session
tags_textAssociated tags
insightsjsonbSession insights data
participated_agentsArrayHuman agents involved (empty array if none)
participated_brainsArrayAI Agents involved with details (brain_id, brain_version, brain_parent_id)
participated_collectionsArrayKnowledge base collection IDs used
participated_language_modelsArrayLanguage models used with details (model_id, brain_parent_id, language_model_id)

Common use cases

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

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