Sign in

v12

latestOpenAPI 3.0.1AGPL-3.0raw.githubusercontent.com2026-07-0971442569.2 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
bucket_size'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH'
customer_idstring
end_timestring date-time
external_customer_idstring
filtersobject
meter_idstring required
start_timestring date-time
timezonestring
window_size'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH'

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

OK

event_namestring
type'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM'
valuenumber