Skip to main content
POST
/
v1
/
events.aggregate
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.events.aggregate({
  customerId: "cus_123",
  featureId: "api_calls",
  range: "30d",
});
{
  "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
    }
  }
}
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: 
// 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: 
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.
// 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: 
{
  "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: 
{
  "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 }
  }
}
The grouped_values field is only present when group_by is provided in the request.

​
Body Parameters

​
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
    }
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.3.0
required

Body

application/json
​
feature_id
required

Feature ID(s) to aggregate events for

Minimum string length: 1
​
customer_id
string

Customer ID to aggregate events for

Minimum string length: 1
​
entity_id
string

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

Minimum string length: 1
​
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
enum<string>

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

Available options:
24h,
7d,
30d,
90d,
last_cycle,
1bc,
3bc
​
bin_size
enum<string>
default:day

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

Available options:
day,
hour,
month
​
custom_range
object

Custom time range to aggregate events for. If provided, range must not be provided

​
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

Required range: 1 <= x <= 250

Response

200 - application/json

OK

​
list
object[]
required

Array of time periods with aggregated values

​
total
object
required

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