# Retrieves aggregated meter usage data

Returns aggregated meter usage data for a customer within a specified time interval. The data can be grouped by various dimensions and can include multiple meters if specified.

## Returns

Aggregated meter usage data for a customer in the specified time interval.

## Parameters

- `customer` (string, required)
  The customer id to fetch meter usage data for.

- `end_time` (timestamp, required)
  The timestamp from when to stop aggregating meter events (exclusive). Must be aligned with minute boundaries.

- `start_time` (timestamp, required)
  The timestamp from when to start aggregating meter events (inclusive). Must be aligned with minute boundaries.

- `meters` (array of objects, optional)
  An array of meter parameters to specify which meters to include in the usage data. If not specified, usage across all meters for the customer is included.

  - `meters.meter_id` (string, required)
    Meter id to query usage for.

  - `meters.dimension_filters` (object, optional)
    Key-value pairs used to filter usage events by meter dimension values. If specified, usage will be filtered for matching usage events.

  - `meters.dimension_group_by_keys` (array of strings, optional)
    List of meter dimension keys to group by. If specified, usage events will be grouped by the given meter dimension key’s values.

  - `meters.tenant_filters` (object, optional)
    Key-value pairs used to filter usage events by high cardinality tenant dimension values. If specified, usage will be filtered for matching usage events.

- `timezone` (string, optional)
  The timezone to use for the start and end times. Defaults to UTC if not specified.

- `value_grouping_window` (enum, optional)
  Specifies what granularity to use when aggregating meter usage events. If not specified, a single event would be returned for the specified time range.
Possible enum values:
  - `day`
  - `hour`
  - `month`
  - `week`

```curl
curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "<<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-07-30.basil" \
  -d start_time=1733097600 \
  -d end_time=1735689600 \
  -d customer=cus_123456789 \
  -d "meters[0][meter_id]"=mtr_1234567890abcdef \
  -d "meters[0][dimension_group_by_keys][0]"=model \
  -d "meters[0][dimension_filters][tier]"=premium \
  -d value_grouping_window=day \
  --data-urlencode timezone="America/New_York"
```

### Response

```json
{
  "object": "billing.analytics.meter_usage",
  "data_refreshed_at": 1735689000,
  "livemode": false,
  "data": [
    {
      "object": "billing.analytics.meter_usage_row",
      "bucket_start_time": 1733097600,
      "bucket_end_time": 1733184000,
      "meter_id": "mtr_1234567890abcdef",
      "bucket_value": 1500,
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "object": "billing.analytics.meter_usage_row",
      "bucket_start_time": 1733184000,
      "bucket_end_time": 1733270400,
      "meter_id": "mtr_1234567890abcdef",
      "bucket_value": 2250,
      "dimensions": {
        "model": "gpt-4"
      }
    },
    {
      "object": "billing.analytics.meter_usage_row",
      "bucket_start_time": 1733270400,
      "bucket_end_time": 1733356800,
      "meter_id": "mtr_1234567890abcdef",
      "bucket_value": 1875,
      "dimensions": {
        "model": "gpt-4"
      }
    }
  ]
}
```