Usage Aggregation Methods

Aggregation methods determine how raw events are calculated into measurable usage metrics. FlexPrice supports multiple aggregation types to handle different pricing models.

Available Aggregation Types

Type	Description	Use Case
`COUNT`	Count number of events	Per-request billing, transaction counts
`SUM`	Sum values from event property	Data transfer, token consumption
`MAX`	Maximum value in period	Peak usage, concurrent capacity
`LATEST`	Most recent value	Current state metrics
`AVG`	Average value	Average response time, utilization
`COUNT_UNIQUE`	Count distinct values	Active users, unique IPs
`SUM_WITH_MULTIPLIER`	Sum with unit conversion	Time-based billing with rates
`WEIGHTED_SUM`	Weighted sum calculation	Complex multi-factor pricing

COUNT

Counts the number of events that match the meter configuration.

Configuration

{
  "aggregation": {
    "type": "COUNT"
  }
}

Use Cases

{
  "name": "API Calls",
  "event_name": "api_request",
  "aggregation": {"type": "COUNT"}
}

Example

Events:

{"event_name": "api_request", "timestamp": "2024-03-20T10:00:00Z"}
{"event_name": "api_request", "timestamp": "2024-03-20T10:05:00Z"}
{"event_name": "api_request", "timestamp": "2024-03-20T10:10:00Z"}

Result: 3

SUM

Sums numeric values from a specified event property.

Configuration

{
  "aggregation": {
    "type": "SUM",
    "field": "property_name"
  }
}

Use Cases

{
  "name": "Bytes Transferred",
  "event_name": "data_transfer",
  "aggregation": {
    "type": "SUM",
    "field": "bytes"
  }
}

Example

Events:

{"event_name": "data_transfer", "properties": {"bytes": 1024}}
{"event_name": "data_transfer", "properties": {"bytes": 2048}}
{"event_name": "data_transfer", "properties": {"bytes": 512}}

Result: 3584 (1024 + 2048 + 512)

MAX

Returns the maximum value from a specified event property within the billing period.

Configuration

{
  "aggregation": {
    "type": "MAX",
    "field": "property_name"
  }
}

Bucketed MAX

For windowed aggregations, use bucket_size:

{
  "aggregation": {
    "type": "MAX",
    "field": "property_name",
    "bucket_size": "HOUR"
  }
}

How it works:

Events are grouped into time buckets (HOUR, DAY, WEEK, MONTH)
MAX is calculated within each bucket
Bucket maxes are summed for the total

Use Cases

{
  "name": "Peak Storage Used",
  "event_name": "storage_snapshot",
  "aggregation": {
    "type": "MAX",
    "field": "bytes"
  }
}

Example (Simple MAX)

Events:

{"event_name": "storage_snapshot", "properties": {"bytes": 1000000}}
{"event_name": "storage_snapshot", "properties": {"bytes": 2000000}}
{"event_name": "storage_snapshot", "properties": {"bytes": 1500000}}

Result: 2000000

Example (Bucketed MAX)

Events (2 hours):

// Hour 1
{"timestamp": "2024-03-20T10:00:00Z", "properties": {"connections": 100}}
{"timestamp": "2024-03-20T10:30:00Z", "properties": {"connections": 150}}

// Hour 2
{"timestamp": "2024-03-20T11:00:00Z", "properties": {"connections": 80}}
{"timestamp": "2024-03-20T11:30:00Z", "properties": {"connections": 120}}

Calculation:

Hour 1 max: 150
Hour 2 max: 120
Total: 270 (150 + 120)

Grouped MAX

For bucketed MAX, use group_by to aggregate per property value:

{
  "aggregation": {
    "type": "MAX",
    "field": "active_seats",
    "bucket_size": "DAY",
    "group_by": "organization_id"
  }
}

How it works:

Events grouped by bucket and group_by property
MAX calculated per group per bucket
All group maxes summed across all buckets

Example:

// Day 1, Org A: max 10 seats
// Day 1, Org B: max 5 seats
// Day 2, Org A: max 12 seats
// Day 2, Org B: max 6 seats
// Total: 33 (10 + 5 + 12 + 6)

LATEST

Returns the most recent value from a specified event property.

Configuration

{
  "aggregation": {
    "type": "LATEST",
    "field": "property_name"
  }
}

Use Cases

{
  "name": "Current Storage",
  "event_name": "storage_snapshot",
  "aggregation": {
    "type": "LATEST",
    "field": "bytes"
  }
}

Example

Events:

{"timestamp": "2024-03-20T10:00:00Z", "properties": {"bytes": 1000}}
{"timestamp": "2024-03-20T11:00:00Z", "properties": {"bytes": 2000}}
{"timestamp": "2024-03-20T12:00:00Z", "properties": {"bytes": 1500}}

Result: 1500 (latest value)

AVG

Calculates the average value from a specified event property.

Configuration

{
  "aggregation": {
    "type": "AVG",
    "field": "property_name"
  }
}

Use Cases

{
  "name": "Avg Response Time",
  "event_name": "api_request",
  "aggregation": {
    "type": "AVG",
    "field": "response_time_ms"
  }
}

Example

Events:

{"properties": {"response_time_ms": 100}}
{"properties": {"response_time_ms": 200}}
{"properties": {"response_time_ms": 150}}

Result: 150 ((100 + 200 + 150) / 3)

COUNT_UNIQUE

Counts the number of distinct values for a specified event property.

Configuration

{
  "aggregation": {
    "type": "COUNT_UNIQUE",
    "field": "property_name"
  }
}

Use Cases

{
  "name": "Monthly Active Users",
  "event_name": "user_activity",
  "aggregation": {
    "type": "COUNT_UNIQUE",
    "field": "user_id"
  }
}

Example

Events:

{"properties": {"user_id": "user_1"}}
{"properties": {"user_id": "user_2"}}
{"properties": {"user_id": "user_1"}}
{"properties": {"user_id": "user_3"}}

Result: 3 (unique users: user_1, user_2, user_3)

SUM_WITH_MULTIPLIER

Sums values and applies a multiplier for unit conversion.

Configuration

{
  "aggregation": {
    "type": "SUM_WITH_MULTIPLIER",
    "field": "property_name",
    "multiplier": "0.001"
  }
}

Use Cases

{
  "name": "Compute Hours",
  "event_name": "compute_usage",
  "aggregation": {
    "type": "SUM_WITH_MULTIPLIER",
    "field": "duration_seconds",
    "multiplier": "0.000277778"
  }
}

Example

Events:

{"properties": {"duration_seconds": 3600}}
{"properties": {"duration_seconds": 7200}}
{"properties": {"duration_seconds": 1800}}

Calculation:

Sum: 12,600 seconds
Multiplier: 0.000277778 (seconds to hours)
Result: 3.5 hours

WEIGHTED_SUM

Calculates a weighted sum for complex multi-factor pricing.

Configuration

{
  "aggregation": {
    "type": "WEIGHTED_SUM",
    "field": "base_value"
  }
}

WEIGHTED_SUM is an advanced aggregation type. Contact FlexPrice support for implementation guidance.

Custom Expressions

For complex calculations, use CEL expressions instead of specifying a field:

{
  "aggregation": {
    "type": "SUM",
    "expression": "cpu_cores * memory_gb * duration_seconds"
  }
}

Expression Examples

cpu_cores * memory_gb * duration_seconds / 3600

Available in expressions:

All event properties
Standard operators: +, -, *, /, %
Comparison: ==, !=, <, <=, >, >=
Ternary: condition ? true_value : false_value

Time Windows

Certain aggregations support time-based bucketing:

Window Size	Duration	Use Case
`HOUR`	60 minutes	Real-time metrics, API rate limits
`DAY`	24 hours	Daily peaks, business day metrics
`WEEK`	7 days	Weekly capacity planning
`MONTH`	Calendar month	Monthly billing periods

Bucket Size Best Practices

Match Billing Granularity

Use bucket sizes that align with your pricing model (e.g., hourly for cloud compute).

Balance Accuracy vs Performance

Smaller buckets are more accurate but require more storage and computation.

Consider Customer Behavior

Choose windows that reflect how customers use your product.

Choosing the Right Aggregation

If you want to…	Use
Count events	`COUNT`
Sum numeric values	`SUM` or `SUM_WITH_MULTIPLIER`
Track peak usage	`MAX` with `bucket_size`
Measure current state	`LATEST`
Calculate averages	`AVG`
Count unique items	`COUNT_UNIQUE`
Complex calculations	`SUM` with `expression`

Best Practices

Validate Event Data

Ensure event properties contain valid numeric values for aggregation.

Test Calculations

Send test events and verify aggregated values match expectations.

Use Appropriate Types

Match aggregation type to your pricing model (COUNT for per-unit, SUM for consumption, MAX for capacity).

Consider Reset Behavior

Pair aggregation type with appropriate reset behavior (BILLING_PERIOD vs NEVER).

Document Custom Logic

If using expressions or multipliers, document the calculation for your team.

Next Steps

Configure Meters

Create meters using these aggregations

Send Events

Start sending events to track

Query Usage

Retrieve aggregated usage data

Connect Pricing

Link aggregated usage to prices

Get Started

Core Concepts

Usage Metering

Pricing & Plans

Credits & Wallets

Billing & Invoicing

Integrations

Self-Hosting

​Available Aggregation Types

​COUNT

​Configuration

​Use Cases

​Example

​SUM

​Configuration

​Use Cases

​Example

​MAX

​Configuration

​Bucketed MAX

​Use Cases

​Example (Simple MAX)

​Example (Bucketed MAX)

​Grouped MAX

​LATEST

​Configuration

​Use Cases

​Example

​AVG

​Configuration

​Use Cases

​Example

​COUNT_UNIQUE

​Configuration

​Use Cases

​Example

​SUM_WITH_MULTIPLIER

​Configuration

​Use Cases

​Example

​WEIGHTED_SUM

​Configuration

​Custom Expressions

​Expression Examples

​Time Windows

​Bucket Size Best Practices

​Choosing the Right Aggregation

​Best Practices

​Next Steps

Configure Meters

Send Events

Query Usage

Connect Pricing

Available Aggregation Types

COUNT

Configuration

Use Cases

Example

SUM

Configuration

Use Cases

Example

MAX

Configuration

Bucketed MAX

Use Cases

Example (Simple MAX)

Example (Bucketed MAX)

Grouped MAX

LATEST

Configuration

Use Cases

Example

AVG

Configuration

Use Cases

Example

COUNT_UNIQUE

Configuration

Use Cases

Example

SUM_WITH_MULTIPLIER

Configuration

Use Cases

Example

WEIGHTED_SUM

Configuration

Custom Expressions

Expression Examples

Time Windows

Bucket Size Best Practices

Choosing the Right Aggregation

Best Practices

Next Steps