Meter Event Summary

A billing meter event summary represents an aggregated view of a customer’s billing meter events within a specified timeframe. It indicates how much usage was accrued by a customer for that period.

Note: Meters events are aggregated asynchronously so the meter event summaries provide an eventually consistent view of the reported usage.

Endpoints

GET/v1/billing/meters/:id/event_summaries

The Meter Event Summary object

Attributes

idstring
Unique identifier for the object.

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

aggregated_valuefloat
Aggregated value of all the events within start_time (inclusive) and end_time (inclusive). The aggregation strategy is defined on meter via default_aggregation.

end_timetimestamp
End timestamp for this event summary (exclusive). Must be aligned with minute boundaries.

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

meterstring
The meter associated with this event summary.

start_timetimestamp
Start timestamp for this event summary (inclusive). Must be aligned with minute boundaries.

The Meter Event Summary object

{
  "id": "mtrusg_test_6041CMAXJrFdZ56U76ce6L35Hz7xA3Tn58z5sY7bq6gM3XN5bx5Y459D4Xt2E17ko6M86kt7kV3bl5PM7LV59l4sY50b6oU5QD7bY3HP58z5sY7bq6gM3Y57LF2Dr7od3Hb8927gh4Tt4Lo4xO4ge60T81C6Y53gl4QS2D33ft3HC3Xi3Cy3Cy3Cy",
  "object": "billing.meter_event_summary",
  "aggregated_value": 10,
  "end_time": 1711659600,
  "livemode": false,
  "meter": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA",
  "start_time": 1711656000
}

List billing meter event summaries

Retrieve a list of billing meter event summaries.

Parameters

customerstringRequired
The customer for which to fetch event summaries.

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

idstringRequired
Unique identifier for the object.

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

value_grouping_windowenum
Specifies what granularity to use when generating event summaries. If not specified, a single event summary would be returned for the specified time range. For hourly granularity, start and end times must align with hour boundaries (e.g., 00:00, 01:00, …, 23:00). For daily granularity, start and end times must align with UTC day boundaries (00:00 UTC).
Possible enum values
day
Generate event summaries per day.
hour
Generate event summaries per hour.

More parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

Returns a list of billing meter event summaries.

GET /v1/billing/meters/:id/event_summaries

Server-side language

curl -G https://api.stripe.com/v1/billing/meters/mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA/event_summaries \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d customer=cus_Pp40waj64hdRxb \
  -d start_time=1711584000 \
  -d end_time=1711666800 \
  -d value_grouping_window=hour

Response

{
  "object": "list",
  "data": [
    {
      "id": "mtrusg_test_6041CMAXJrFdZ56U76ce6L35Hz7xA3Tn58z5sY7bq6gM3XN5bx5Y459D4Xt2E17ko6M86kt7kV3bl5PM7LV59l4sY50b6oU5QD7bY3HP58z5sY7bq6gM3Y57LF2Dr7od3Hb8927gh4Tt4Lo4xO4ge60T81C6Y53gl4QS2D33ft3HC3Xl3bk3Cy3Cy",
      "object": "billing.meter_event_summary",
      "aggregated_value": 15,
      "end_time": 1711663200,
      "livemode": false,
      "meter": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA",
      "start_time": 1711659600
    },
    {
      "id": "mtrusg_test_6041CMAXJrFdZ56U76ce6L35Hz7xA3Tn58z5sY7bq6gM3XN5bx5Y459D4Xt2E17ko6M86kt7kV3bl5PM7LV59l4sY50b6oU5QD7bY3HP58z5sY7bq6gM3Y57LF2Dr7od3Hb8927gh4Tt4Lo4xO4ge60T81C6Y53gl4QS2D33ft3HC3Xi3Cy3Cy3Cy",
      "object": "billing.meter_event_summary",
      "aggregated_value": 10,
      "end_time": 1711659600,
      "livemode": false,
      "meter": "mtr_test_61Q8nQMqIFK9fRQmr41CMAXJrFdZ5MnA",
      "start_time": 1711656000
    }
  ],
  "has_more": false,
  "url": "/v1/billing/meters/:id/event_summaries"
}