Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
events

Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property.

post/v1/events.aggregate

Headers

x-api-versionstring required

Request body

customer_idstring

Customer ID to aggregate events for

entity_idstring

Entity ID to filter aggregated events for (e.g., per-seat or per-resource limits)

group_bystring

Property to group events by (e.g. "properties.region"), or "$customer_id" / "$entity_id" / "$plan_id" to group by those columns

range'24h' | '7d' | '30d' | '90d' | 'last_cycle' | '1bc' | '3bc'

Time range to aggregate events for. Either range or custom_range must be provided

bin_size'day' | 'hour' | 'week' | 'month'

Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day

filter_byobject

Filter events by property values, e.g. {"model": "gpt-4", "region": "us"}. Maximum 5 filters.

max_groupsinteger

Maximum number of distinct group values to return per time bin when using group_by. Remaining values are bundled into an 'Other' bucket. Defaults to 9

Example request

{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "range": "30d",
  "bin_size": "day"
}

Response

OK

totalobject required

Total aggregations per feature. Keys are feature IDs, values contain count and sum.

Example response

{
  "list": [
    {
      "period": 1762905600000,
      "values": {
        "messages": 10,
        "sessions": 3
      }
    },
    {
      "period": 1762992000000,
      "values": {
        "messages": 3,
        "sessions": 12
      }
    }
  ],
  "total": {
    "messages": {
      "count": 2,
      "sum": 13
    },
    "sessions": {
      "count": 2,
      "sum": 15
    }
  }
}