Get usage data with paginated groupings
Retrieve granular usage data for a specific customer and billable metric, with the ability to break down usage by custom grouping dimensions. This endpoint enables deep usage analytics by segmenting data across attributes like region, user, model type, or any custom dimension defined in your billable metrics.
Use this endpoint to:
- Analyze usage patterns broken down by specific attributes (region, user, department, etc.)
- Build detailed usage dashboards with dimensional filtering
- Identify high-usage segments for optimization opportunities
Request parameters
Use group_key and group_filters to group by one or more dimensions. This is required for compound group keys and recommended for all new integrations:
{
"group_key": ["region", "team"],
"group_filters": {
"region": ["US-East", "US-West"]
}
}
Important: For compound group keys, you must pass the complete set of keys that make up the compound key. Partial key combinations are not supported. For example, if your billable metric has a compound group key [region, team, environment], you must pass all three keys in group_key—you cannot pass just [region] or [region, team].
Key response fields:
An array of PagedUsageAggregate objects containing:
starting_onandending_before: Time window boundariesgroup: Object mapping group keys to their values- For simple groups, this will be a map with a single key-value pair (e.g.,
{"region": "US-East"}) - For compound groups, this will be a map with multiple key-value pairs (e.g.,
{"region": "US-East", "team": "engineering"})
- For simple groups, this will be a map with a single key-value pair (e.g.,
value: Aggregated usage for this group and time windownext_page: Pagination cursor for large datasets
Usage guidelines:
- Required parameters: Must specify
customer_id,billable_metric_id, andwindow_size - Time windows: Set
window_sizeto hour, day, or none for different granularities - Group filtering: Use
group_keyandgroup_filtersto specify groups and group filters - Limits: When using compound group keys (2+ keys in
group_key), the default and max limit is 100 - Pagination: Use limit and
next_pagefor large result sets - Null handling: Group values may be null for events missing the group key property
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Max number of results that should be returned
1 <= x <= 100Cursor that indicates where the next page of results should start.
Body
The usage query to run
A window_size of "day" or "hour" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of "none" will return a single usage aggregate for the entirety of the specified period.
hour, day, none, HOUR, DAY, NONE, Hour, Day, None Use group_key and group_filters instead. Use a single group key to group by. Compound group keys are not supported.
Group key to group usage by. Supports both simple (single key) and compound (multiple keys) group keys.
For simple group keys, provide a single key e.g. ["region"].
For compound group keys, provide multiple keys e.g. ["region", "team"].
For streaming metrics, the keys must be defined as a simple or compound group key on the billable metric. For compound group keys, all keys must match an exact compound group key definition — partial matches are not allowed.
Cannot be used together with group_by.
11Object mapping group keys to arrays of values to filter on. Only usage matching these filter values will be returned. Keys must be present in group_key. Omit a key or use an empty array to include all values for that dimension.
If true, will return the usage for the current billing period. Will return an error if the customer is currently uncontracted or starting_on and ending_before are specified when this is true.