Filter and group reporting queries

filters narrows a reporting query to matching threads, and groupBy splits the result into one series or value per label, tier, company, or other dimension. All three reporting queries accept filters. The time series and single value queries also accept groupBy.

Filter fields

filters takes a ThreadMetricFilters object with these fields:

Field	Matches threads where
`labelTypeIds`	The thread has any of these labels
`companyIdentifiers`	The customer’s company is any of these, by `companyId` or `companyDomainName`
`tenantIdentifiers`	The thread’s tenant is any of these, by `tenantId` or `externalId`
`tierIdentifiers`	The thread’s tier is any of these, by `tierId` or `externalId`
`customerGroupIdentifiers`	The customer is in any of these groups, by `customerGroupId`, `customerGroupKey`, or `externalId`
`assignedToUser`	Any of these users is the thread’s current primary or additional assignee. See Filter by user
`priorities`	The thread’s priority is any of these: `0` Urgent, `1` High, `2` Normal, `3` Low
`messageSource`	The thread’s first inbound message came from any of these channels: `EMAIL`, `SLACK`, `CHAT`, `API`, `MS_TEAMS`, `DISCORD`, `INTERNAL`
`threadFields`	Every entry matches a thread field, by `key` and `stringValue`, `stringValues`, or `booleanValue`
`tenantFields`	Every entry matches a field on the thread’s tenant, by `externalFieldId` and `stringValue` or `stringValues`
`surveyResponse`	For CSAT metrics only: `rating` is required, and `surveyId` limits results to one survey
`userIds`	For `agent_` metrics only: any of these users gets the credit for the measured action. See Filter by user

A company, tenant, tier, or customer group identifier that matches nothing fails the query with thread_metric_filter_no_match.

Filter by user

assignedToUser and userIds both take user IDs, but they answer different questions:

assignedToUser: who the thread is assigned to right now. It works on every metric and matches the current primary or additional assignee, not whoever was assigned when the measured event happened
userIds: who gets the credit for the measured action. It only works on agent_ metrics, and what credit means depends on the metric

For userIds, each agent_ metric credits either the user who did the action or every user ever assigned to the thread. The user who did the action, such as sending the reply or changing the status. For assignment transitions, that’s the user who was assigned:

agent_threads_first_response_time
agent_threads_time_between_follow_up_responses
agent_messages_sent_count
agent_threads_status_transitions_count__todo, __snoozed, and __done
agent_threads_assignment_transitions_count

Every other agent_ metric credits every user ever assigned to the thread, even if the thread has since been reassigned. A thread that passed through 3 users counts toward all 3. userIds is only allowed at the top level of filters, not inside and, or, or not. On a metric without the agent_ prefix, it returns input_validation. Naming anyone other than yourself in either filter needs the metricsAgent:read permission.

Filters match current values

Filters match the values a thread has now, not the values it had when the measured event happened. Remove a label from a thread and it drops out of every past bucket for that label. The same applies to assignee, tier, priority, company, tenant, customer group, and fields.

Combine filters with AND, OR, and NOT

Fields in the same object combine with AND, and the values in one field combine with OR. For other combinations, nest filter objects:

and: a list of filter objects that must all match
or: a list of filter objects where at least one must match
not: one filter object that must not match

This filter matches threads with the Bug label on the Free or Pro tier:

{
  "labelTypeIds": ["lt_01HB81HYXZ2B8QGYCH5YG1AGM8"],
  "or": [
    { "tierIdentifiers": [{ "externalId": "free" }] },
    { "tierIdentifiers": [{ "externalId": "pro" }] }
  ]
}

To require 2 labels at once, put each in its own object under and:

{
  "and": [
    { "labelTypeIds": ["lt_01HB81HYXZ2B8QGYCH5YG1AGM8"] },
    { "labelTypeIds": ["lt_01HB8BTN5S8NAJGSNC3NJZ7FV4"] }
  ]
}

Filters can nest and and or up to 2 levels deep, so (A AND B) OR (C AND D) works and a third level returns input_validation. not doesn’t add a level. userIds is only allowed at the top level.

Group results by a dimension

groupBy takes a list with one ThreadMetricGroupByInput. These dimensions are supported:

Dimension	Groups by
`ASSIGNEE`	The thread’s current primary or additional assignees. On `agent_` metrics, the user who gets the credit. Needs `metricsAgent:read`
`COMPANY`	The customer’s company
`CUSTOMER_GROUP`	The customer’s groups
`LABEL_TYPE`	The thread’s labels
`MESSAGE_SOURCE`	The channel of the thread’s first inbound message
`PRIORITY`	The thread’s priority
`TENANT`	The thread’s tenant
`TIER`	The thread’s tier
`THREAD_FIELD`	A thread field’s value. Set `subKey` to the field’s key
`TENANT_FIELD`	A tenant field’s value. Set `subKey` to the field’s external ID

Each group’s group.value is a string: an ID such as a tier ID, a priority from "0" to "3", or a field value. group.label holds the display name, such as the tier name. It’s null for MESSAGE_SOURCE, THREAD_FIELD, and TENANT_FIELD, whose value is already readable, and for a deleted entity. Grouped results follow two rules:

A thread with several values counts in each group. A thread with 2 labels counts under both, and the same applies to customer groups, tenants, and assignees.
A thread with no value is left out. Grouping by tier drops threads with no tier, so the groups don’t add up to the ungrouped total.

If you filter and group by the same dimension, only the filtered values become groups.

Limit the number of groups with topN

topN returns the largest groups, from 1 to 50, and pools the rest into one group whose value is __OTHER__. Without topN, the query returns every group. On a large workspace, grouping by a dimension with thousands of values can time out with thread_metric_query_timed_out. __OTHER__ follows these rules:

Groups are ranked by the metric’s value over the whole range. On a duration metric, the top 5 groups are the 5 slowest, not the 5 busiest.
__OTHER__ isn’t a real entity. You can’t filter by it or get its thread IDs.
On a duration time series, __OTHER__ is the percentile of the remaining groups’ values in each bucket, not the percentile of their threads pooled together. Single value queries pool the remaining groups’ threads and take the percentile of those.

This groupBy returns the 10 slowest tiers by first response time and pools the rest:

{
  "groupBy": [{ "dimension": "TIER", "topN": 10 }]
}

GraphQL API

Building Agents

Agent integrations

Webhooks

Channels

Customer Cards

UI Components

Security

Changelog

Filter and group reporting queries

Filter fields

Filter by user

Filters match current values

Combine filters with AND, OR, and NOT

Group results by a dimension

Limit the number of groups with topN

​Filter fields

​Filter by user

​Filters match current values

​Combine filters with AND, OR, and NOT

​Group results by a dimension

​Limit the number of groups with topN

Filter fields

Filter by user

Filters match current values

Combine filters with AND, OR, and NOT

Group results by a dimension

Limit the number of groups with topN