Statistics

The API uses a standardized format for retrieving statistics that supports flexible grouping of results based on your reporting needs. This guide explains the generic structure, available options, and how grouping works across all statistics endpoints.

For endpoint-specific details, including supported groups and returned data fields, refer to the OpenAPI documentation.

Groups

Groups allow you to organize the dataset into the structure required for your reports. Groups can be combined freely, and there are no restrictions on valid combinations. This means you may use any set of groups needed to define the desired report dimensions (see Group Item Examples).

Each group included in the request produces a corresponding group item in the response for each entry. Every group item has a unique group id, enabling you to re-group or further process the detailed results in your implementation.

The list of available groups is specific to each endpoint and is documented in the OpenAPI docs.

Usage

To apply grouping, specify the desired groups in the request body using the groups field (an array of strings).

Groups in request body:

{
	"groups": ["QUEUE", "USER"]
}

Group Item Examples

Groups	Description	Group Items
MONTH, YEAR	Statistics for each month within each year.	Nov 2021, Dec 2021, Jan 2022, Feb 2022, …
HOUR	Statistics for each hour of the day (combined).	00, 01, 02, …, 20, 21, 22, 23
QUEUE	Statistics per queue.	Queue 1, Queue 2, Queue 3, …
QUEUE, USER	Statistics per user within each queue.	Queue 1 - User 1, Queue 1 - User 2, Queue 2 - User 1, …

Statistic Levels

Some statistics are reported at different levels depending on how the data is grouped. For example, call statistics can vary between corporation, queue, and agent (user) levels:

• Corporation level
  Counts unique calls across the entire organization. Each call is only counted once, regardless of how many queues or agents it passes through.

• Queue level
  Counts incoming calls to a queue.
  A single call may be counted multiple times if it:

  • Overflows into other queues (each queue registers it as an incoming call), or
  • Is transferred from an agent back into another queue.

• Agent (User) level
  Counts each call attempt delivered to an agent as a separate incoming call.
  For example, if the same queue call is offered to an agent five times without being answered, this will be recorded as five incoming calls for that agent.

The statistic level is determined dynamically based on the selected grouping.
For example, grouping by USER will return statistics at the agent level.

When applicable, the response will include the statistic level used for the reported data.

Response object

All endpoints in the Statistics section of the API return data using the same response structure. The contents of the groupItems list vary depending on the groups specified in the request (see Group Usage), while the structure and fields of the data object vary by endpoint according to the statistics being returned.

Schema

{
	groups: [/* ... */],		// List of groups defined in the request
	items:				// One entry per grouped result item/row
	[{
		groupItems:		// One object per group applied to this item/row
		[{
			group: "...",	// The group key (e.g., "QUEUE", "USER")
			id: "...",	// ID of the group for this item.
					// Can be null when no applicable value exists
					// (e.g., no user).
			label: "...",	// Display label of the group (e.g., a name)
			object:		// Optional. Extended group data available for some groups
			{
				/* ... */
			}
		}],
		data:			// Endpoint-specific statistics payload
		{
			/* ... */
		}
	}],
	statLevel: "..."		// Indicates which statistical level is used
					// based on the provided groups.
					// Example: call statistics may change between
					// CORPORATION, QUEUE, and USER.
					// For endpoints with a single level, this is always null.
}

Example value

The following example shows a response using the group combination QUEUE and USER.

{
	"groups": ["QUEUE", "USER"], 
	"items": [
		{
			"groupItems": [
				{
					"group": "QUEUE", 
					"id": "1", 
					"label": "Queue 1"
				},
				{
					"group": "USER",
					"id": null,
					"label": "No user"
				}
			],
			"data": {
				/* Endpoint-specific data */
			}
		},
		{
			"groupItems": [
				{
					"group": "QUEUE",
					"id": "2",
					"label": "Queue 2"
				},
				{
					"group": "USER",
					"id": "1",
					"label": "User 1",
					"object": {
						/* … */
					}
				}
			],
			"data": {
				/* Endpoint-specific data */
			}
		}
	],
	"statLevel": "USER"
}

Implementation strategies

Live retrievals

The Statistics APIs are optimized for direct retrieval, allowing efficient queries of large datasets within configured time-interval limits.
Rate limits still apply. Smaller time intervals can be queried more frequently and return results faster than large-range requests.
Implementing a caching layer is recommended.

Syncing statistics

If you store data locally for advanced processing and reporting, group statistics at the highest detail level required for your use cases.

Example use case

You need data for:

• Closed cases per Category
• Closed cases per Main Category
• Closed cases per Queue

❌ Don't

Make separate requests:

• Request 1 → CATEGORY
• Request 2 → ROOT_CATEGORY
• Request 3 → QUEUE

✅ Do

Make one request with groups CATEGORY, ROOT_CATEGORY, QUEUE

Store this detailed dataset locally and aggregate it as needed to generate each report.

Note: Some statistics use different statistic levels. Data from different levels cannot always be combined. See the Statistic Levels section for details.

Syncing statistics that changes over time

Some data may change after initial sync, causing stored statistics to become inaccurate.

Example with sync each day:

• Day 1: A case is solved as a one-touch case.
• Day 2: The case is reopened and updated, so it no longer qualifies as one-touch.
  A daily sync would still reflect the outdated Day 1 state.

Solutions:

• Periodically re-sync historical data (e.g., daily sync plus a full weekly re-sync at week’s end).
• Periodically sync over a larger time range — this enables efficient processing on smaller, localized datasets while caching the primary bulk retrieval for reuse.
• Sync statistics grouped by individual cases and update existing records as changes occur.

Example: Sync statistics grouped by individual cases

Request: Grouped by ACTIVITY (highest detail level. Case = Activity)