Query analytics
Run an analytics query with selected measures, dimensions, filters, and time windows.
POST
Query analytics
Required access
Body
Dataset to query. For example,
tickets, messages, outbound_messages, marketing_attribution, csat, or workforce_activity.Measures to calculate. For example,
["ticket_count", "open_ticket_count"] for the tickets dataset or ["message_count", "customer_message_count"] for the messages dataset.Optional dimensions to group results. For example,
["channel_kind"], ["priority"], or ["day_of_week", "hour_of_day"].Optional filter object. For example,
{ "channel_ids": ["<channel_id>"], "statuses": ["open"] }. For channel, agent, pilot, team, or workspace IDs, see Resource IDs.Campaign UUIDs, up to 100. Supported by
marketing_attribution and outbound_messages. Resolve names with analytics member lookup. An empty array imposes no restriction.Journey UUIDs, up to 100. Supported by
marketing_attribution and outbound_messages. With campaign IDs, attribution selects either requested entity type; outbound queries require both filters to match each message.For
marketing_attribution, use campaign, journey, or both. Defaults to both. This filter also applies when you specify entity IDs.For
marketing_attribution, use delivery, read, or clicked. Omit to use your workspace attribution setting.Attribution lookback override for
marketing_attribution, from 1 to 8760 hours. Omit to use your workspace setting. This is separate from the reporting period in time.For outbound category queries only:
MARKETING, UTILITY, AUTHENTICATION, or UNKNOWN. Requires a supported template_category grouping. Values are case-sensitive.Timezone used to group time buckets. For example,
Asia/Kolkata or UTC. Explicit offsets in start/end timestamps determine the reporting boundaries; timestamps without an offset are treated as UTC.Timestamp field used for the query window. For example,
created_at, closed_at, message_created_at, sent_at, or order_created_at.Response shape, where supported by the chosen query. Use
summary for aggregate totals or rows for grouped rows. Marketing attribution and template-category queries return rows and reject summary.Optional sort instructions. For example,
[{ "field": "ticket_count", "direction": "desc" }].Maximum number of rows to return, from 1 to 1000. Marketing attribution defaults to 1000 rows per page. Category queries apply a limit without pagination; omit it when you need all matching buckets.
For marketing attribution, use
meta.cursor from the previous response with the same filters, measures, and time settings. Stop when it is null. Template-category queries reject cursors.Notes
- This endpoint uses API client v2 credentials. See API client v2.
- Marketing attribution and template-category queries require a time window and reject reversed ranges, unknown timezones,
business_hours, andaggregation. Marketing attribution also rejects custom sort. - Unsupported or misspelled filters on these datasets return an error. A missing scope or dataset grant returns
403; invalid query combinations return400, and malformed request fields return422.