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 |
ALL for totals, other values for trend analysis.
Sorting
Sort results by any numeric field:
sort.field=sessions&sort.order=DESC
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
Top Topics This Month
GET /v1/query?
groupBy=TOPIC&
instanceId=...&
dateRange.start=2024-01-01T00:00:00Z&
dateRange.end=2024-01-31T23:59:59Z&
timeGranularity=ALL&
fields=sessions,users,messages&
sort.field=sessions&
sort.order=DESC&
limit=10
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
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 |
