Summary
We've improved how the Analytics Aggregates API endpoints (e.g., conversations, transcripts, flows, etc.) handle groupBy queries when a multi-valued dimension is used in both the filter and the groupBy.
When flattenMultivaluedDimensions is set to false, the API now ensures that only groups matching your filter criteria are returned. Previously, extra groups for dimension values outside your filter could appear in the response.
Previous Behavior
Some dimensions — such as divisionId, userId, queueId, and skillId — are multi-valued, meaning a single interaction can be associated with multiple values for that dimension. When you filtered by specific values of a multi-valued dimension and also grouped by that same dimension, the API would:
- Correctly match interactions containing any of your filtered values
- But then expand the grouping to include all values associated with those matched interactions — including values you did not request
Example: You filter for divisionId = A and B, and group by divisionId. An interaction belongs to divisions [A, B, C]. Previously, the response would include groups for divisions A, B, and C, even though C was not in your filter. In some cases, this could result in dramatically more groups than expected (e.g., filtering for 50 users but receiving 2,000+ user groups in the response).
New Behavior
The API now strictly scopes groupBy results to only the dimension values specified in your filter. Using the example above, you would receive groups only for divisions A and B — never C. This applies to:
• GroupBy queries — no more extraneous groups in the response
• TopN/BottomN queries — accurate rankings that only reflect your filtered dimension values
Effective Date
Monday, August 17, 2026
Details
What This Means for You
- More accurate results: Responses now correctly reflect only the dimension values you requested. If you were previously post-processing or filtering the response client-side to remove extra groups, that workaround is no longer needed.
- Smaller response payloads: Eliminating extraneous groups reduces response size, particularly for queries involving high-cardinality multi-valued dimensions.
- Improved performance: Queries are more efficient since the underlying engine no longer expands groups unnecessarily.
- No API contract changes: There are no changes to the request or response schema. Existing queries continue to work as before — they simply return more precise results.
Customer Impact
Who Is Affected
This change applies when all of the following are true:
- You are using an analytics aggregates query endpoint
- flattenMultivaluedDimensions is set to false (or not specified, if false is the default)
- Your query filters on a multi-valued dimension and groups by that same dimension
Opting Out: The disableStrictGrouping Flag
If your application depends on the previous grouping behavior, you can preserve it by setting the new disableStrictGrouping query flag to true in your aggregation request body.
disableStrictGrouping value
false (default) New behavior — groupBy results are strictly filtered to only the dimension values in your filter.
true Legacy behavior — groupBy results may include dimension values beyond what your filter specified, matching the previous behavior.
If you omit disableStrictGrouping from your request, it defaults to false and you will get the new, stricter behavior.
Impacted Resources
/api/analytics//aggregates/
Issue References
[PURE-6988]
Contacts
@Ryan Legner Please reply to this announcement with any questions. This helps the wider developer community benefit from the discussion. We encourage you to use this thread before contacting the designated person directly. Thank you for your understanding.