Sign in

v12

latestOpenAPI 3.0.1AGPL-3.0raw.githubusercontent.com2026-07-0971442569.2 KB
Events

Get usage statistics

Use when building usage reports or dashboards across events. Supports filters and grouping; defaults to last 7 days if no range provided.

post/events/usage

Request body

aggregation_type'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM' required
billing_anchorstring date-time

BillingAnchor enables custom monthly billing periods for usage aggregation.

When to use:

  • WindowSize = "MONTH" AND you need custom monthly periods (not calendar months)
  • Subscription billing that doesn't align with calendar months
  • Example: Customer signed up on 15th, so billing periods are 15th to 15th

When NOT to use:

  • WindowSize != "MONTH" (ignored for DAY, HOUR, WEEK, etc.)
  • Standard calendar-based billing (1st to 1st of each month)

Example values:

  • "2024-03-05T14:30:45.123456789Z" (5th of each month at 2:30:45 PM)
  • "2024-01-15T00:00:00Z" (15th of each month at midnight)
  • "2024-02-29T12:00:00Z" (29th of each month at noon - handles leap years)
bucket_size'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH'
customer_idstring
end_timestring date-time
event_namestring required
external_customer_idstring
filtersobject
group_bystring[]

GroupBy lists the analytics group_by dimensions.

  • "source" — group by event source column
  • "properties.X" — group by JSON property X
group_by_propertystring

GroupByProperty is the property name in event.properties to group by before aggregating. When set, aggregation is applied per unique value of this property within each bucket, then the per-group results are summed to produce the bucket total.

Deprecated: prefer GroupBy []string{"properties.<X>"} for parity with other analytics endpoints. ToUsageParams translates this field into GroupBy when GroupBy is otherwise empty.

multiplierstring
property_namestring

will be empty/ignored in case of COUNT

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:45.123456789Z",
  "customer_id": "customer456",
  "end_time": "2024-03-20T00:00:00Z",
  "event_name": "api_request",
  "external_customer_id": "customer456",
  "property_name": "request_size",
  "start_time": "2024-03-13T00:00:00Z"
}

Response

OK

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