Reporting

The Reporting API returns the same metrics as Insights: thread volume, response and resolution times, SLA compliance, CSAT, and per-user activity. Use it to pull metrics into a BI tool, an internal dashboard, or a scheduled report.

​

Queries

The API has three queries, one per chart shape:

• threadTimeSeriesMetric: one value per time bucket, such as threads created per day
• threadSingleValueMetric: one value for the whole period, such as median first response time this month
• threadHeatmapMetric: a 7 x 24 grid of counts by day of week and hour

Each query takes an input with a metricName, a date range, and a mode. All three accept the same filters, and the time series and single value queries accept the same group-by. The metrics reference lists every metric name and which query supports it.

​

Permissions

The Reporting API needs these permissions:

• metrics:read: every metric whose name doesn’t start with agent_
• metricsAgent:read: every metric whose name starts with agent_, which report per user. Also needed to group by ASSIGNEE, or to filter assignedToUser to anyone other than the caller

agent_ metrics also need the Team reporting feature, which is on the Horizon and Frontier plans. Every query is limited to your plan’s reporting history.

​

Return a value or the threads behind it

mode is required and picks what the query returns:

• METRIC: the reporting metric’s values. threadIds is null
• THREAD_IDS: the distinct IDs of every thread behind the value, for the whole date range. The value fields are null

To get the threads behind one bucket, narrow from and to to that bucket. To get the threads behind one group, turn the group into a filter. groupBy is rejected in THREAD_IDS mode.

​

Dates and time zones

from and to are ISO 8601 timestamps in UTC, such as 2026-09-01T00:00:00Z. Timestamps with an offset such as +01:00 are rejected. These rules apply to every query:

• Both ends are inclusive.
• to can’t be in the future. Plain allows up to 5 minutes of clock skew and treats that as now.
• Time series widen the range to whole intervals. from moves back to the start of its interval and to forward to the end of its interval. Weeks start on Monday.

Insights has no time zone setting, so every bucket, day, and heatmap hour is in UTC.

​

Units

Every duration is in minutes. Counts are numbers of threads unless the metric says otherwise. SLA compliance is a fraction from 0 to 1, and CSAT percentage is a number from 0 to 100. null means there was no data for that bucket or group. 0 means a real zero.

​

Data freshness and exclusions

Reporting data is rebuilt every hour, so values lag by up to an hour. Polling more than once an hour returns the same numbers. Every metric leaves out deleted threads, spam, Ignored threads, test threads, and threads from Plain-provisioned demo domains. See Which threads count.

​

Errors and limits

Reporting queries return these errors in extensions.code: An error returns data: null for the whole query, including any other fields in the same request.