Get batched usage data

Retrieve aggregated usage data across multiple customers and billable metrics in a single query. This batch endpoint enables you to fetch usage patterns at scale, broken down by time windows, making it ideal for building analytics dashboards, generating reports, and monitoring platform-wide usage trends.

Use this endpoint to:

• Generate platform-wide usage reports for internal teams
• Monitor aggregate usage trends across your entire customer base
• Create comparative usage analyses between customers or time periods
• Support capacity planning with historical usage patterns

Key response fields:

An array of UsageBatchAggregate objects containing:

• customer_id: The customer this usage belongs to
• billable_metric_id and billable_metric_name: What was measured
• start_timestamp and end_timestamp: Time window for this data point
• value: Aggregated usage amount for the period
• groups (optional): Usage broken down by group keys with values
• next_page: Pagination cursor for large result sets

Usage guidelines:

• Time windows: Set window_size to hour, day, or none (entire period)
• Required parameters: Must specify starting_on, ending_before, and window_size
• Filtering options:
  • customer_ids: Limit to specific customers (omit for all customers)
  • billable_metrics: Limit to specific metrics (omit for all metrics)
• Pagination: Use next_page cursor to retrieve large datasets
• Null values: Group values may be null when no usage matches that group