Meter Configuration

Configure meters to transform events into billable usage metrics

Meters define how FlexPrice aggregates raw events into measurable usage. Each meter specifies which events to track, how to aggregate them, and what filters to apply.

Meter Structure

A meter consists of these core components:

Field	Type	Required	Description
id	string	Yes	Unique meter identifier (e.g., mtr_api_calls)
name	string	Yes	Display name
event_name	string	Yes	Event type to track (must match event_name in events)
aggregation	object	Yes	How to aggregate events
filters	array	No	Event property filters
reset_usage	string	No	When to reset accumulated usage

Example Meter Configuration

API Call Counter

{
  "id": "mtr_api_calls",
  "name": "API Calls",
  "event_name": "api_request",
  "aggregation": {
    "type": "COUNT"
  },
  "filters": [],
  "reset_usage": "BILLING_PERIOD"
}

Aggregation Configuration

The aggregation object defines how events are transformed into usage metrics.

Aggregation Fields

Field	Type	Required	Description
type	string	Yes	Aggregation method (see Aggregations)
field	string	Conditional	Property name to aggregate (required for SUM, MAX, AVG, LATEST)
expression	string	No	CEL expression for complex calculations
multiplier	decimal	Conditional	Multiplier for SUM_WITH_MULTIPLIER type
bucket_size	string	No	Time window for bucketed MAX or SUM aggregations
group_by	string	No	Property to group by (MAX with bucket_size only)

Common Aggregation Patterns

Count Events

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

Filters

Filters allow you to create multiple meters from the same event type by matching specific property values.

Filter Structure

{
  "filters": [
    {
      "key": "property_name",
      "values": ["value1", "value2"]
    }
  ]
}

• key: Property name from event.properties
• values: Array of acceptable values (OR logic)
• Multiple filters use AND logic

Filter Examples

Single Filter

{
  "filters": [
    {
      "key": "region",
      "values": ["us-west-2"]
    }
  ]
}

Reset Usage Behavior

The reset_usage field controls when accumulated usage resets:

Value	Behavior	Use Case
BILLING_PERIOD	Reset at start of each billing period	API calls, data transfer
NEVER	Never reset (continuous accumulation)	Storage, peak usage

Examples

Resetting Usage (API Calls):

{
  "reset_usage": "BILLING_PERIOD"
}

• Customer starts billing period with 0 usage
• Usage accumulates throughout the period
• Resets to 0 at start of next period

Non-Resetting Usage (Storage):

{
  "reset_usage": "NEVER"
}

• Usage represents current state (e.g., GB currently stored)
• Latest value is used for billing
• Historical values are preserved

Advanced Configurations

Bucketed Aggregations

For MAX or SUM aggregations, use bucket_size to calculate over time windows:

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

How it works:

1. Events are grouped into hourly buckets
2. MAX is calculated within each bucket
3. Buckets are summed for billing period total

Valid bucket sizes: HOUR, DAY, WEEK, MONTH

Grouped Aggregations

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

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

How it works:

1. Events are grouped by bucket (day) and organization_id
2. MAX is calculated per organization per day
3. Results are summed across all organizations and days

group_by is only supported for MAX aggregation with bucket_size configured.

CEL Expressions

Use Common Expression Language (CEL) for complex calculations:

{
  "aggregation": {
    "type": "SUM",
    "expression": "tokens * duration * pixel_count / 1000000"
  }
}

Expression context:

• Access event properties directly by name (e.g., tokens, duration)
• Standard math operators: +, -, *, /, %
• Comparison: ==, !=, <, <=, >, >=
• Logical: &&, ||, !

Examples:

Compute Units

tokens * duration * pixel_count

Creating Meters via API

Meters are typically created through the FlexPrice dashboard, but can also be managed via API:

curl -X POST https://us.api.flexprice.io/v1/meters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "event_name": "api_request",
    "aggregation": {
      "type": "COUNT"
    },
    "reset_usage": "BILLING_PERIOD"
  }'

See Meters API Reference for full documentation.

Validation Rules

FlexPrice validates meter configurations:

1. Required Fields

   id, name, event_name, and aggregation.type must be provided.

2. Aggregation Type

   Must be a valid aggregation type (COUNT, SUM, MAX, etc.).

3. Field Requirements

   SUM, MAX, AVG, LATEST require field or expression.

4. Multiplier Validation

   SUM_WITH_MULTIPLIER requires multiplier > 0.

5. Bucket Size

   Only valid for MAX or SUM aggregations.

6. Group By

   Only valid for MAX with bucket_size.

7. Filter Keys

   Filter keys must be non-empty with at least one value.

Use Case Examples

API Metering by Endpoint

Track different API endpoints separately:

Read Operations

{
  "id": "mtr_api_reads",
  "name": "API Read Calls",
  "event_name": "api_request",
  "aggregation": {"type": "COUNT"},
  "filters": [
    {"key": "method", "values": ["GET"]}
  ]
}

Storage by Tier

Measure storage across different tiers:

Standard Storage

{
  "id": "mtr_storage_standard",
  "name": "Standard Storage (GB)",
  "event_name": "storage_snapshot",
  "aggregation": {
    "type": "MAX",
    "field": "bytes",
    "multiplier": "0.000000001"
  },
  "filters": [
    {"key": "tier", "values": ["standard"]}
  ],
  "reset_usage": "NEVER"
}

AI/ML Token Usage

Track token consumption by model:

GPT-4 Tokens

{
  "id": "mtr_tokens_gpt4",
  "name": "GPT-4 Tokens",
  "event_name": "ai_request",
  "aggregation": {
    "type": "SUM",
    "field": "total_tokens"
  },
  "filters": [
    {"key": "model", "values": ["gpt-4"]}
  ]
}

Peak Concurrent Usage

Measure maximum concurrent connections:

{
  "id": "mtr_peak_connections",
  "name": "Peak Concurrent Connections",
  "event_name": "connection_count",
  "aggregation": {
    "type": "MAX",
    "field": "count",
    "bucket_size": "HOUR"
  },
  "reset_usage": "BILLING_PERIOD"
}

Best Practices

1. One Meter per Billable Metric

   Create separate meters for each distinct usage metric you want to bill.

2. Use Descriptive Names

   Name meters clearly (e.g., “API Calls - Premium Tier” not “meter_1”).

3. Leverage Filters for Segmentation

   Use filters to create granular meters from the same event type.

4. Choose Appropriate Aggregation

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

5. Test with Real Events

   Send test events and verify meters calculate usage correctly before production use.

6. Document Custom Expressions

   If using CEL expressions, document the calculation logic for your team.

Next Steps

Aggregation Methods

Learn about available aggregation types

Send Events

Start sending events to your meters

Query Usage

Retrieve aggregated usage data

Connect to Pricing

Link meters to prices for billing