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

Key response fields:

An array of PagedUsageAggregate objects containing:

• starting_on and ending_before: Time window boundaries
• group_key: The dimension being grouped by (e.g., “region”)
• group_value: The specific value for this group (e.g., “US-East”)
• value: Aggregated usage for this group and time window
• next_page: Pagination cursor for large datasets

Usage guidelines:

• Required parameters: Must specify customer_id, billable_metric_id, and window_size
• Time windows: Set window_size to hour, day, or none for different granularities
• Group filtering: Use group_by to specify:
  • key: The dimension to group by (must be set on the billable metric as a group key)
  • values: Optional array to filter to specific values only
• Pagination: Use limit and next_page for large result sets
• Null handling: group_value may be null for unmatched data