Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Retrieves aggregated meter usage data 

Billing
Meter Usage Data
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.

Parameters

  • customerstringRequired

    The customer id to fetch meter usage data for.

  • end_timetimestampRequired

    The timestamp from when to stop aggregating meter events (exclusive). Must be aligned with minute boundaries.

  • start_timetimestampRequired

    The timestamp from when to start aggregating meter events (inclusive). Must be aligned with minute boundaries.

  • metersarray of objects

    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_idstringRequired

      Meter id to query usage for.

    • meters.dimension_filtersobject

      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_keysarray of strings

      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_filtersobject

      Key-value pairs used to filter usage events by high cardinality tenant dimension values. If specified, usage will be filtered for matching usage events.

  • timezonestring

    The timezone to use for the start and end times. Defaults to UTC if not specified.

  • value_grouping_windowenum

    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

Returns

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

GET /v1/billing/analytics/meter_usage
curl -G https://api.stripe.com/v1/billing/analytics/meter_usage \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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
{
  "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"
      }
    }
  ]
}