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, confidence scores, ratings, tags)
• 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 SessionsPreviewV2(
  $brainIds: _uuid
  $startDate: timestamp
  $endDate: timestamp
  $limit: Int
) {
  rows: logs_sessions_preview_v2(
    limit: $limit
    args: {
      brain_parent_ids: $brainIds
      start_time: $startDate
      end_time: $endDate
    }
  ) {
    session_id
    start_time
    end_time
    channel
    avg_confidence
    rating
    total_user_messages
  }
}

Variables:

{
  "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
agentIds	_text	Filter by human agent IDs
Session filters
channels	_text	Filter by channels (web, facebook, viber, etc.)
brainVersions	_int4	Filter by AI Agent versions
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
channelUserId	String	Filter by channel user ID
externalUserId	String	Filter by external user ID
Quality metrics
minNumUserMessages	Int	Minimum user messages in session
maxConfidence	float8	Maximum confidence threshold
minHumanResponseTime	float8	Minimum human response time
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
hasCollectionSources	Boolean	Sessions with collection sources
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
expired_time	timestamp	Session expiration time
channel	String	Communication channel

AI Agent details

Field	Type	Description
brain_id	uuid	AI Agent instance ID
brain_parent_id	uuid	Parent AI Agent ID
brain_version	int4	AI Agent version number
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
min_confidence	float8	Lowest confidence score
avg_confidence	float8	Average confidence score
rating	Int	User rating (1-5, null if unrated)
feedback	String	User feedback text
avg_response_time	float8	Average bot response time
avg_human_response_time	float8	Average human response time
human_first_response_time	float8	Time to first human response

Session properties

Field	Type	Description
is_contained	Boolean	Session handled entirely by AI
is_covered	Boolean	Session topics within AI scope
is_test	Boolean	Test/preview session
tags	_text	Associated tags
rule_ids	_uuid	Triggered rule IDs
participated_agents	_text	Human agents involved
participated_brains	_text	AI Agents involved
participated_collections	_text	Knowledge base used

Common use cases

Basic query

Get sessions for a specific desk within a date range:

{
  "deskIds": "{d2be0283-9b53-4d7b-b77d-2650f3a1a99c}",
  "startDate": "2024-01-08",
  "endDate": "2024-01-17"
}

Low confidence sessions

Find sessions where the AI had low confidence:

{
  "brainIds": "{a2wv9283-9b53-4d7b-b77d-2650f3a1a99c}",
  "maxConfidence": 0.7,
  "startDate": "2024-01-08",
  "endDate": "2024-01-17"
}

Poor ratings

Get sessions with ratings of 1-3:

{
  "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):

{
  "brainIds": "{a2wv9283-9b53-4d7b-b77d-2650f3a1a99c}",
  "isContained": false,
  "startDate": "2024-01-08",
  "endDate": "2024-01-17"
}

Multi-channel

Query across multiple channels:

{
  "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:

{
  "userId": "mApUE81oSmzUWTA_w2ZbL",
  "channelUserId": "ePlhV5VeCXg"
}

Example response

{
  "data": {
    "rows": [
      {
        "session_id": "1234a3ba-33fd-4add-be5e-f73030242bee",
        "start_time": "2024-01-07T11:40:28.772",
        "end_time": "2024-01-07T11:48:41.092",
        "channel": "web",
        "user_name": "Visitor 438",
        "total_user_messages": 2,
        "avg_confidence": 0.9334274,
        "min_confidence": 0.8668548,
        "rating": 5,
        "is_contained": false,
        "is_covered": true,
        "is_test": true,
        "participated_agents": [
          {
            "agent_id": "4v57b8ba-c1de-42ac-94ad-564e0c6858c9",
            "agent_name": "George Johnson"
          }
        ]
      },
      {
        "session_id": "58be4fe7-96af-409b-8ae2-cf6b1c4b44cc",
        "start_time": "2024-01-06T15:09:43.491",
        "end_time": "2024-01-06T15:12:07.31",
        "channel": "web",
        "user_name": "Visitor 435",
        "total_user_messages": 4,
        "avg_confidence": 0.8721187,
        "min_confidence": 0.74423736,
        "rating": 2,
        "is_contained": true,
        "is_covered": true,
        "is_test": false,
        "tags": ["moveo_start"]
      }
    ]
  }
}

Full query reference

View complete GraphQL query with all available fields

query SessionsPreviewV2(
  $accountId: uuid
  $deskIds: _uuid
  $brainIds: _uuid
  $integrationIds: _uuid
  $brainVersions: _int4
  $channels: _text
  $startDate: timestamp
  $endDate: timestamp
  $minNumUserMessages: Int
  $maxConfidence: float8
  $minHumanResponseTime: float8
  $ratings: _int4
  $tags: _text
  $rule_ids: _uuid
  $sessionId: String
  $userId: String
  $userName: String
  $userEmail: String
  $channelUserId: String
  $externalUserId: String
  $isContained: Boolean
  $isCovered: Boolean
  $isTest: Boolean
  $hasCollection: Boolean
  $hasCollectionSources: Boolean
  $agentIds: _text
  $isMeaningful: Boolean
  $limit: Int
) {
  rows: logs_sessions_preview_v2(
    limit: $limit
    args: {
      start_time: $startDate
      end_time: $endDate
      account_id: $accountId
      brain_parent_ids: $brainIds
      desk_ids: $deskIds
      integration_ids: $integrationIds
      brain_versions: $brainVersions
      channels: $channels
      min_num_user_messages: $minNumUserMessages
      max_confidence: $maxConfidence
      min_human_response_time: $minHumanResponseTime
      ratings: $ratings
      tags: $tags
      rule_ids: $rule_ids
      session_id: $sessionId
      user_id: $userId
      user_name: $userName
      user_email: $userEmail
      channel_user_id: $channelUserId
      external_user_id: $externalUserId
      is_contained: $isContained
      is_covered: $isCovered
      is_test: $isTest
      has_collection: $hasCollection
      has_collection_sources: $hasCollectionSources
      agent_ids: $agentIds
      is_meaningful: $isMeaningful
    }
  ) {
    avg_confidence
    brain_id
    brain_parent_id
    brain_version
    channel
    channel_user_id
    user_id
    user_name
    user_email
    desk_id
    start_time
    end_time
    expired_time
    external_user_id
    integration_id
    is_contained
    is_covered
    is_test
    min_confidence
    participated_brains
    participated_collections
    participated_agents
    rating
    feedback
    session_id
    tags
    rule_ids
    total_user_messages
    avg_human_response_time
    avg_response_time
    human_first_response_time
  }
}