---
title: "Aggregate Events"
openapi: "openapi POST /v1/events.aggregate"
---

import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";

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

## Working with Properties

When tracking events, you can attach custom properties that can later be used for grouping aggregations:

```typescript
// Track an event with properties
await autumn.track({
  customerId: "cus_123",
  featureId: "api_calls",
  value: 1,
  properties: {
    model: "gpt-4",
    source: "api",
    region: "us-east"
  }
});
```

You can then aggregate events grouped by any property using the `group_by` parameter:

```typescript
const result = await autumn.events.aggregate({
  customerId: "cus_123",
  featureId: "api_calls",
  range: "7d",
  groupBy: "properties.model"  // Group by the "model" property
});
```

### Special Group By Operators

In addition to custom properties, you can group by built-in columns using `$`-prefixed operators:

- `$customer_id` -- Group results by customer ID. Useful when aggregating across all customers (i.e. no `customer_id` specified).
- `$entity_id` -- Group results by entity ID. Useful for seeing usage broken down per entity.

```typescript
// Aggregate across all customers, grouped by customer
const result = await autumn.events.aggregate({
  featureId: "api_calls",
  range: "7d",
  groupBy: "$customer_id"
});

// Aggregate for a customer, grouped by entity
const result = await autumn.events.aggregate({
  customerId: "cus_123",
  featureId: "api_calls",
  range: "7d",
  groupBy: "$entity_id"
});
```

## Response Format

The response structure changes based on whether `group_by` is provided:

### Without `group_by` (Flat Response)

When no grouping is specified, `values` contains the aggregated sum for each feature:

```json
{
  "list": [
    {
      "period": 1762905600000,
      "values": {
        "api_calls": 150,
        "messages": 45
      }
    }
  ],
  "total": {
    "api_calls": { "count": 10, "sum": 150 },
    "messages": { "count": 5, "sum": 45 }
  }
}
```

### With `group_by` (Grouped Response)

When grouping is specified, `values` contains the total sum while `grouped_values` breaks down values by group:

```json
{
  "list": [
    {
      "period": 1762905600000,
      "values": {
        "api_calls": 150
      },
      "grouped_values": {
        "api_calls": {
          "gpt-4": 100,
          "gpt-3.5": 50
        }
      }
    }
  ],
  "total": {
    "api_calls": { "count": 10, "sum": 150 }
  }
}
```

<Note>
  The `grouped_values` field is only present when `group_by` is provided in the request.
</Note>

### Body Parameters

<DynamicParamField body="customer_id" type="string">
  Customer ID to aggregate events for
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  Entity ID to filter aggregated events for (e.g., per-seat or per-resource limits)
</DynamicParamField>

<DynamicParamField body="feature_id" type="string" required>
  Feature ID(s) to aggregate events for
</DynamicParamField>

<DynamicParamField body="group_by" type="string">
  Property to group events by (e.g. "properties.region"), or "$customer_id" / "$entity_id" / "$plan_id" to group by those columns
</DynamicParamField>

<DynamicParamField body="range" type="'24h' | '7d' | '30d' | '90d' | 'last_cycle' | '1bc' | '3bc'">
  Time range to aggregate events for. Either range or custom_range must be provided
</DynamicParamField>

<DynamicParamField body="bin_size" type="'day' | 'hour' | 'month'">
  Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day
</DynamicParamField>

<DynamicParamField body="custom_range" type="object">
  Custom time range to aggregate events for. If provided, range must not be provided
  <Expandable title="properties">
    <DynamicParamField body="start" type="number" required />

    <DynamicParamField body="end" type="number" required />

  </Expandable>
</DynamicParamField>

<DynamicParamField body="filter_by.{key}" type="string">
  Filter events by property values, e.g. \{"model": "gpt-4", "region": "us"\}. Maximum 5 filters.
</DynamicParamField>

<DynamicParamField body="max_groups" type="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
</DynamicParamField>


### Response

<DynamicResponseField name="list" type="object[]">
  Array of time periods with aggregated values
  <Expandable title="properties">
    <DynamicResponseField name="period" type="number">
      Unix timestamp (epoch ms) for this time period
    </DynamicResponseField>

    <DynamicResponseField name="values.{key}" type="number">
      Aggregated values per feature: \{ [featureId]: number \}
    </DynamicResponseField>

    <DynamicResponseField name="grouped_values" type="object">
      Values broken down by group (only present when group_by is used): \{ [featureId]: \{ [groupValue]: number \} \}
      <Expandable title="properties">
        <DynamicResponseField name="{key}.{key}" type="number" />

      </Expandable>
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="total.{key}" type="object">
  Total aggregations per feature. Keys are feature IDs, values contain count and sum.
  <Expandable title="properties">
    <DynamicResponseField name="count" type="number">
      Number of events for this feature
    </DynamicResponseField>

    <DynamicResponseField name="sum" type="number">
      Sum of event values for this feature
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>


<ResponseExample>
```json 200
{
  "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
    }
  }
}
```
</ResponseExample>