Analytics API aggregation query grouping by queue and media type

NICE CXone API & Integrations
1

Need some help troubleshooting my Analytics API aggregation query. I’m building a Node.js middleware service to pull real-time stats, but I’m struggling to group the results by both queue ID and media type simultaneously. My current JSON payload for the POST /api/v2/analytics/conversations/queues/summary endpoint only seems to respect the first grouping dimension.

Here is the snippet I’m using:

{
 "groupings": [
 { "name": "queueId" },
 { "name": "mediaType" }
 ]
}

The API returns a 200 OK, but the entities array is flat, ignoring the second grouping. Am I missing a specific syntax for multi-dimensional grouping in CXone?

2

I’d suggest checking out at the view definition. grouping by queue and media type requires the view to be set to by-queue-by-media-type, not just a generic summary.

{
 "view": "by-queue-by-media-type",
 "groupBy": ["queueId", "mediaType"],
 "interval": "PT1H",
 "startDate": "2023-10-01T00:00:00.000Z",
 "endDate": "2023-10-02T00:00:00.000Z"
}

the api ignores extra groupBy fields if the view doesn’t support multi-dimensional aggregation. check the schema docs for supported views.

3

This looks like a solid approach, but in my local Docker compose setup, the mock server often drops the secondary dimension if the view parameter isn’t strictly aligned with the grouping keys. I usually validate this by hitting the endpoint directly via curl to ensure the JSON structure matches the schema exactly.

{
 "view": "by-queue-by-media-type",
 "groupBy": ["queueId", "mediaType"]
}

If you still see missing data, check your interval settings. Sometimes the aggregation fails silently if the time window is too granular for the mock data generator.

4

This happens because the strict coupling between the view parameter and the groupBy array in the Genesys Cloud Analytics API. The API does not allow arbitrary combinations; you must select a predefined view that supports your desired dimensions. If your view does not explicitly include “media-type”, the API silently drops that dimension or returns an empty dataset, which is likely what you are experiencing.

Here is the correct workflow to resolve this:

  1. Verify the available views for your specific endpoint. For queue summaries, by-queue-by-media-type is the standard choice.
  2. Ensure your groupBy array exactly matches the dimensions supported by that view. Do not add extra fields like agentId unless the view supports it.
  3. Use the Node.js SDK to construct the request, ensuring the AnalyticsApi client is authenticated with the analytics:query scope.
const { AnalyticsApi } = require('@genesyscloud/analytics');
const api = new AnalyticsApi();
const body = {
 view: 'by-queue-by-media-type',
 groupBy: ['queueId', 'mediaType'],
 interval: 'PT1H',
 startDate: '2023-10-01T00:00:00.000Z',
 endDate: '2023-10-02T00:00:00.000Z'
};
const result = await api.postAnalyticsConversationsQueuesSummary(body);

This ensures the backend aggregation engine processes both dimensions correctly.

5

You might want to check at the AnalyticsApi in PureCloudPlatformClientV2. The documentation states “view must match groupBy”. Use GetQueuesSummaryAsync with ByQueueByMediaType view.

  • View definition constraints
  • GroupBy array syntax
  • Async/await patterns