v52

latestOpenAPI 3.0.1AGPL-3.0raw.githubusercontent.com2026-08-01255473862.7 KB

Events

Get usage by meter

Use when showing usage for a specific meter (e.g. dashboard or overage check). Supports time range, filters, and grouping by customer or subscription.

post/events/usage/meter

Request body

billing_anchorstring date-time

BillingAnchor enables custom monthly billing periods for meter usage aggregation.

Usage guidelines:

Only effective when WindowSize = "MONTH"
For other window sizes (DAY, HOUR, WEEK), this field is ignored
When nil, uses standard calendar months (1st to 1st)
When provided, creates custom monthly periods (e.g., 5th to 5th)

Common use cases:

Subscription billing periods that don't align with calendar months
Customer-specific billing cycles (e.g., signed up on 15th)
Multi-tenant systems with different billing anchor dates

Example: If BillingAnchor = "2024-03-05T14:30:45Z" and WindowSize = "MONTH":

March period: 2024-03-05 14:30:45 to 2024-04-05 14:30:45
April period: 2024-04-05 14:30:45 to 2024-05-05 14:30:45

customer_idstring

end_timestring date-time

external_customer_idstring

filtersobject

meter_idstring required

start_timestring date-time

timezonestring

Example request

{
  "billing_anchor": "2024-03-05T14:30:45Z",
  "customer_id": "customer456",
  "end_time": "2024-12-09T00:00:00Z",
  "external_customer_id": "user_5",
  "meter_id": "123",
  "start_time": "2024-11-09T00:00:00Z"
}

Response

event_namestring

valuenumber