Querying Metrics

Query Basics

The Query API returns aggregated metrics based on how you group the data. Every query requires:

Parameter	Description
`groupBy`	How to aggregate data (TOPIC, SESSION, GAP, etc.)
`instanceId`	Which instance to query
`dateRange.start`	Start of time range (ISO 8601)
`dateRange.end`	End of time range (ISO 8601)
`timeGranularity`	Time bucketing (ALL, HOUR, DAY, WEEK, MONTH)
`fields`	Which metrics to return

Group By Options

Value	Returns	Use Case
`TOPIC`	One row per topic	What are users talking about?
`SESSION`	One row per conversation	Drill into specific conversations
`END_USER`	One row per user	User-level engagement
`GAP`	One row per gap	What’s my AI missing?
`CSAT_DSAT`	One row per signal type	How do users feel?
`REPEATED_REQUEST`	One row per repeated request	Where do users struggle?

Time Granularity

Value	Behavior
`ALL`	Single aggregation across entire date range
`HOUR`	One row per hour per group
`DAY`	One row per day per group
`WEEK`	One row per week per group
`MONTH`	One row per month per group

Use ALL for totals, other values for trend analysis.

Sorting

Sort results by any numeric field:

sort.field=sessions&sort.order=DESC

Available sort orders: ASC, DESC

Filtering

By Entity IDs

Filter results by related entities:

# Sessions or end users about specific topics
topicIds=topic-uuid-1,topic-uuid-2

# Sessions with specific signals
signalIds=signal-uuid

# Sessions with specific gaps
gapIds=gap-uuid

# Sessions with specific repeated requests
repeatedRequestIds=rr-uuid

topicIds works with both groupBy=SESSION and groupBy=END_USER. Other entity filters only work with groupBy=SESSION.

By Gap Type

When querying gaps, filter by type:

gapType=KNOWLEDGE  # or TOOL

By Language

When querying sessions, filter by detected language:

language=en  # or es, fr, de, etc.

Common Query Patterns

Topic Trends Over Time

GET /v1/query?
  groupBy=TOPIC&
  instanceId=...&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=DAY&
  fields=sessions,messages

Worst Performing Sessions

GET /v1/query?
  groupBy=SESSION&
  instanceId=...&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=ALL&
  fields=messages,sat,dsat,repeatedRequests&
  dimensionFields=title,summary&
  sort.field=dsat&
  sort.order=DESC&
  limit=20

Knowledge Gaps by Frequency

GET /v1/query?
  groupBy=GAP&
  instanceId=...&
  gapType=KNOWLEDGE&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=ALL&
  fields=sessions,messages&
  sort.field=messages&
  sort.order=DESC

Sessions About a Specific Gap

GET /v1/query?
  groupBy=SESSION&
  instanceId=...&
  gapIds=gap-uuid&
  dateRange.start=2024-01-01T00:00:00Z&
  dateRange.end=2024-01-31T23:59:59Z&
  timeGranularity=ALL&
  fields=messages,sat,dsat&
  dimensionFields=title,summary,topics

Field Reference

Available by Group By

Group By	Available Fields
TOPIC	sessions, users, messages, avgMessagesPerSession, sat, dsat, netSat
SESSION	messages, duration, lastActiveAt, sat, dsat, netSat, repeatedRequests
END_USER	sessions, messages, sat, dsat, netSat, repeatedRequests
GAP	sessions, users, messages
CSAT_DSAT	sessions, users, messages
REPEATED_REQUEST	sessions, users, messages

Dimension Fields

Extra metadata available for some group by options:

Group By	Dimension Fields
SESSION	title, summary, topics, language
END_USER	externalId, topTopics, createdAt, lastActiveAt

Getting Started

Fundamentals

Features

Guides

Security

Querying Metrics

Query Basics

Group By Options

Time Granularity

Sorting

Filtering

By Entity IDs

By Gap Type

By Language

Common Query Patterns

Top Topics This Month

Topic Trends Over Time

Worst Performing Sessions

Knowledge Gaps by Frequency

Sessions About a Specific Gap

Field Reference

Available by Group By

Dimension Fields

​Query Basics

​Group By Options

​Time Granularity

​Sorting

​Filtering

​By Entity IDs

​By Gap Type

​By Language

​Common Query Patterns

​Top Topics This Month

​Topic Trends Over Time

​Worst Performing Sessions

​Knowledge Gaps by Frequency

​Sessions About a Specific Gap

​Field Reference

​Available by Group By

​Dimension Fields

Query Basics

Group By Options

Time Granularity

Sorting

Filtering

By Entity IDs

By Gap Type

By Language

Common Query Patterns

Top Topics This Month

Topic Trends Over Time

Worst Performing Sessions

Knowledge Gaps by Frequency

Sessions About a Specific Gap

Field Reference

Available by Group By

Dimension Fields