Aggregate Events

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",
});

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.events.aggregate(
    feature_id="api_calls",
    customer_id="cus_123",
    range="30d",
    bin_size="day",
)

curl --request POST \
  --url https://api.useautumn.com/v1/events.aggregate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "range": "30d",
  "bin_size": "day"
}
'

{
  "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
    }
  }
}

POST

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",
});

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.events.aggregate(
    feature_id="api_calls",
    customer_id="cus_123",
    range="30d",
    bin_size="day",
)

curl --request POST \
  --url https://api.useautumn.com/v1/events.aggregate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "range": "30d",
  "bin_size": "day"
}
'

{
  "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,

week,

month

custom_range

object

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

Show child attributes

filter_by

object

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

Show child attributes

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

list

object[]

required

Array of time periods with aggregated values

Show child attributes

total

object

required

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

Show child attributes

List Events Get Entity

⌘I

Billing

Balances

Customers

Authorization

Events

Entities

Plans

Features

Rewards & Referrals

Webhook Events

Platform (Beta)

Aggregate Events

Working with Properties

Special Group By Operators

Response Format

Without `group_by` (Flat Response)

With `group_by` (Grouped Response)

Body Parameters

Response

Authorizations

Headers

Body

Response

​Working with Properties

​Special Group By Operators

​Response Format

​Without group_by (Flat Response)

​With group_by (Grouped Response)

​Body Parameters

​Response

Authorizations

Headers

Body

Response

Working with Properties

Special Group By Operators

Response Format

Without `group_by` (Flat Response)

With `group_by` (Grouped Response)

Body Parameters

Response