# 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.

## Request

```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"
      }
    }
  ]
}
```

## 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`](https://docs.stripe.com/api/billing/analytics/meter-usage/retrieves.md?query=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.

- `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`