Aggregate Events

Overview

The Aggregate Events endpoint provides powerful analytics capabilities for usage events. It returns time-series data showing how usage evolves over time, with support for multiple features and custom grouping.

Use Cases

Usage analytics: Visualize usage trends over time
Billing calculations: Calculate usage-based charges for specific periods
Capacity planning: Identify usage patterns and predict future needs
Feature adoption: Track how different features are being used
Segmentation analysis: Break down usage by custom properties (e.g., API model, region)

Key Concepts

Time Periods (Bins)

Events are aggregated into time periods called “bins”. Each bin represents a specific time window:

hour: Hourly aggregation
day: Daily aggregation (default)
month: Monthly aggregation

Range Options

Predefined time ranges make it easy to query common periods:

24h: Last 24 hours
7d: Last 7 days
30d: Last 30 days
90d: Last 90 days
last_cycle: Previous billing cycle
1bc: Current billing cycle (default)
3bc: Last 3 billing cycles

Alternatively, use custom_range with start and end timestamps (epoch milliseconds).

Basic Aggregation

Single Feature, Daily Bins

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

Response:

{
  "list": [
    {
      "period": 1762905600000,
      "values": {
        "api_calls": 150
      }
    },
    {
      "period": 1762992000000,
      "values": {
        "api_calls": 203
      }
    }
  ],
  "total": {
    "api_calls": {
      "count": 2,
      "sum": 353
    }
  }
}

Multiple Features

Aggregate multiple features in a single request:

{
  "customer_id": "cus_123",
  "feature_id": ["api_calls", "messages", "storage"],
  "range": "7d",
  "bin_size": "day"
}

Response:

{
  "list": [
    {
      "period": 1762905600000,
      "values": {
        "api_calls": 150,
        "messages": 45,
        "storage": 1024
      }
    },
    {
      "period": 1762992000000,
      "values": {
        "api_calls": 203,
        "messages": 67,
        "storage": 2048
      }
    }
  ],
  "total": {
    "api_calls": {
      "count": 2,
      "sum": 353
    },
    "messages": {
      "count": 2,
      "sum": 112
    },
    "storage": {
      "count": 2,
      "sum": 3072
    }
  }
}

Advanced: Grouped Aggregation

Group events by custom properties to analyze usage across different dimensions.

Group by Property

Use the group_by parameter to break down usage by event properties:

{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "range": "7d",
  "bin_size": "day",
  "group_by": "properties.model"
}

Response:

{
  "list": [
    {
      "period": 1762905600000,
      "values": {
        "api_calls": 150
      },
      "grouped_values": {
        "api_calls": {
          "gpt-4": 100,
          "gpt-3.5-turbo": 50
        }
      }
    },
    {
      "period": 1762992000000,
      "values": {
        "api_calls": 203
      },
      "grouped_values": {
        "api_calls": {
          "gpt-4": 150,
          "gpt-3.5-turbo": 53
        }
      }
    }
  ],
  "total": {
    "api_calls": {
      "count": 2,
      "sum": 353
    }
  }
}

Multiple Features with Grouping

{
  "customer_id": "cus_123",
  "feature_id": ["api_calls", "messages"],
  "range": "7d",
  "group_by": "properties.region"
}

Response:

{
  "list": [
    {
      "period": 1762905600000,
      "values": {
        "api_calls": 150,
        "messages": 45
      },
      "grouped_values": {
        "api_calls": {
          "us-east-1": 90,
          "eu-west-1": 60
        },
        "messages": {
          "us-east-1": 30,
          "eu-west-1": 15
        }
      }
    }
  ],
  "total": {
    "api_calls": {
      "count": 1,
      "sum": 150
    },
    "messages": {
      "count": 1,
      "sum": 45
    }
  }
}

Bin Size Selection

Choose the appropriate bin size based on your time range:

Range	Recommended Bin Size	Example Use Case
24h	`hour`	Real-time monitoring
7d	`day`	Weekly trends
30d	`day`	Monthly analytics
90d	`day` or `month`	Quarterly reports
1bc	`day`	Current billing period

If not specified, bin_size defaults to hour for 24h range and day for all other ranges.

Custom Time Ranges

For precise control over the aggregation period, use custom_range:

{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "custom_range": {
    "start": 1704067200000,
    "end": 1706745600000
  },
  "bin_size": "day"
}

custom_range and range are mutually exclusive. Use one or the other, not both.

JavaScript Example

// Get usage for the first week of January 2024
const startDate = new Date('2024-01-01T00:00:00Z');
const endDate = new Date('2024-01-08T00:00:00Z');

const request = {
  customer_id: 'cus_123',
  feature_id: 'api_calls',
  custom_range: {
    start: startDate.getTime(),
    end: endDate.getTime()
  },
  bin_size: 'day'
};

Response Structure

List Items

Each item in the list array represents one time period:

period: Unix timestamp (epoch milliseconds) marking the start of this time bin
values: Object with feature IDs as keys and aggregated totals as values
grouped_values: (Optional) Nested object breaking down values by group when group_by is used

Total Object

The total object provides overall statistics per feature:

count: Number of time periods with data for this feature
sum: Total sum of all values across all periods

Example Queries

Hourly Usage for Last 24 Hours

{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "range": "24h",
  "bin_size": "hour"
}

Current Billing Cycle Usage

{
  "customer_id": "cus_123",
  "feature_id": ["api_calls", "storage"],
  "range": "1bc"
}

Usage by Model Type

{
  "customer_id": "cus_123",
  "feature_id": "ai_requests",
  "range": "30d",
  "group_by": "properties.model"
}

Monthly Aggregation for Quarterly Report

{
  "customer_id": "cus_123",
  "feature_id": ["api_calls", "storage", "bandwidth"],
  "range": "90d",
  "bin_size": "month"
}

Multi-Dimensional Analysis

{
  "customer_id": "cus_123",
  "feature_id": ["api_calls", "messages"],
  "range": "30d",
  "bin_size": "day",
  "group_by": "properties.environment"
}

Visualization Example

// Fetch aggregated data
const response = await fetch('https://api.autumn.com/v1/events.aggregate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'cus_123',
    feature_id: ['api_calls', 'messages'],
    range: '30d',
    bin_size: 'day'
  })
});

const data = await response.json();

// Transform for charting library (e.g., Chart.js)
const chartData = {
  labels: data.list.map(item => new Date(item.period).toLocaleDateString()),
  datasets: [
    {
      label: 'API Calls',
      data: data.list.map(item => item.values.api_calls || 0)
    },
    {
      label: 'Messages',
      data: data.list.map(item => item.values.messages || 0)
    }
  ]
};

Best Practices

Choose Appropriate Bin Size

Match bin size to your analysis needs: hourly for real-time, daily for trends, monthly for long-term patterns.

Use Grouping Strategically

Group by meaningful properties (model, region, plan) to gain actionable insights, but avoid over-segmentation.

Monitor Total Metrics

Use the total object for quick summary statistics before diving into time-series data.

Cache Aggregated Data

For frequently accessed reports, cache aggregation results to reduce API calls and improve performance.

Common Use Cases

Usage-Based Billing

{
  "customer_id": "cus_123",
  "feature_id": "api_calls",
  "range": "1bc"
}

Use the total.sum value to calculate charges for the current billing cycle.

Feature Adoption Tracking

{
  "customer_id": "cus_123",
  "feature_id": ["feature_a", "feature_b", "feature_c"],
  "range": "90d",
  "bin_size": "day"
}

Compare values across features to identify which are growing or declining.

Cost Attribution

{
  "customer_id": "cus_123",
  "feature_id": "compute",
  "range": "30d",
  "group_by": "properties.team_id"
}

Break down costs by team, project, or department using grouped aggregation.

​Overview

​Use Cases

​Key Concepts

​Time Periods (Bins)

​Range Options

​Basic Aggregation

​Single Feature, Daily Bins

​Multiple Features

​Advanced: Grouped Aggregation

​Group by Property

​Multiple Features with Grouping

​Bin Size Selection

​Custom Time Ranges

​JavaScript Example

​Response Structure

​List Items

​Total Object

​Example Queries

​Hourly Usage for Last 24 Hours

​Current Billing Cycle Usage

​Usage by Model Type

​Monthly Aggregation for Quarterly Report

​Multi-Dimensional Analysis

​Visualization Example

​Best Practices

Choose Appropriate Bin Size

Use Grouping Strategically

Monitor Total Metrics

Cache Aggregated Data

​Common Use Cases

​Usage-Based Billing

​Feature Adoption Tracking

​Cost Attribution

Overview

Use Cases

Key Concepts

Time Periods (Bins)

Range Options

Basic Aggregation

Single Feature, Daily Bins

Multiple Features

Advanced: Grouped Aggregation

Group by Property

Multiple Features with Grouping

Bin Size Selection

Custom Time Ranges

JavaScript Example

Response Structure

List Items

Total Object

Example Queries

Hourly Usage for Last 24 Hours

Current Billing Cycle Usage

Usage by Model Type

Monthly Aggregation for Quarterly Report

Multi-Dimensional Analysis

Visualization Example

Best Practices

Common Use Cases

Usage-Based Billing

Feature Adoption Tracking

Cost Attribution