---
title: "POST /v1/events.aggregate"
method: POST
path: "/v1/events.aggregate"
tags: ["events"]
---

# POST /v1/events.aggregate

`POST /v1/events.aggregate`

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

## Headers

- `x-api-version` string, required

## Request body

- object
  - `customer_id` string — Customer ID to aggregate events for
  - `entity_id` string — Entity ID to filter aggregated events for (e.g., per-seat or per-resource limits)
  - `feature_id` union, required — Feature ID(s) to aggregate events for
    - string
    - string[]
  - `group_by` string — 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
  - `custom_range` object — Custom time range to aggregate events for. If provided, range must not be provided
    - `start` number, required
    - `end` number, required
  - `filter_by` object — Filter events by property values, e.g. {"model": "gpt-4", "region": "us"}. Maximum 5 filters.
  - `max_groups` integer — 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

## Response `200`

OK

- object
  - `list` object[], required — Array of time periods with aggregated values
    - `period` number, required — Unix timestamp (epoch ms) for this time period
    - `values` object, required — Aggregated values per feature: { [featureId]: number }
    - `grouped_values` object — Values broken down by group (only present when group_by is used): { [featureId]: { [groupValue]: number } }
  - `total` object, required — Total aggregations per feature. Keys are feature IDs, values contain count and sum.

---

[API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/revisions/29536933c0dc/schema)