Meter Usage Data

A billing meter usage event represents an aggregated view of a customer’s billing meter events within a specified timeframe.

Endpoints

GET/v1/billing/analytics/meter_usage

The Meter usage datum object

Attributes

objectstring
String representing the object’s type. Objects of the same type share the same value.

dataarray of objects
The aggregated meter usage data for the specified customer and time range.

data_refreshed_attimestamp
Timestamp indicating how fresh the data is. Measured in seconds since the Unix epoch.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

The Meter usage datum object

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

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.

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

Server-side language

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