Usage Metering Overview

Usage metering is the foundation of any consumption-based billing system. Fluxrate provides a simple, reliable event ingestion system that handles deduplication, aggregation, and billing calculations automatically.

The Metering Flow

Meters

A Meter defines:

What to measure (property name in event payload)
How to aggregate (SUM, MAX, UNIQUE_COUNT, LAST)
Unit for display (calls, bytes, users, etc.)

Every meter has a unique meter_token — a UUID used to identify it when sending events.

Usage Events

Each usage event contains:

{
  "meter_token": "550e8400-e29b-41d4-a716-446655440000",
  "customer_external_id": "your-customer-id",
  "quantity": 1,
  "timestamp": "2025-01-15T10:30:00Z",      // optional, defaults to now
  "idempotency_key": "req_abc123",           // optional, prevents duplicates
  "metadata": {                              // optional extra data
    "region": "us-east-1",
    "endpoint": "/api/inference"
  }
}

Querying Usage

View aggregated usage for a meter:

GET /api/v1/meters/<meter_id>/usage?start_date=2025-01-01&end_date=2025-01-31&group_by=day

Response:

{
  "meter_id": "...",
  "total_usage": 82450,
  "event_count": 12300,
  "unique_customers": 47,
  "period_start": "2025-01-01T00:00:00Z",
  "period_end": "2025-01-31T23:59:59Z",
  "grouped_data": [
    { "period": "2025-01-01", "usage": 2800, "event_count": 420 },
    { "period": "2025-01-02", "usage": 3100, "event_count": 465 },
    ...
  ]
}

Grouping Options

`group_by`	Description
`hour`	Hourly breakdown
`day`	Daily breakdown (default)
`week`	Weekly breakdown
`month`	Monthly breakdown

Idempotency

To prevent double-counting when retrying failed requests, always pass an idempotency_key:

POST /api/v1/sdk/track
{
  "meter_token": "...",
  "customer_external_id": "customer_123",
  "quantity": 1,
  "idempotency_key": "order_456_api_call_1"
}

If the same idempotency_key is sent again, the duplicate event is silently ignored.

High-Volume Ingestion

For high-volume scenarios (millions of events/day), consider:

Batching events — Aggregate at your backend before sending (e.g., send message count every minute, not per message)
Async sending — Use a message queue to send events asynchronously
Pre-aggregation — Use your own counters and periodically sync totals

See the Infrastructure Cost Guide for scaling recommendations.

Get Started

Product Guide

Developer Guides

Usage Metering Overview

The Metering Flow

Meters

Usage Events

Querying Usage

Grouping Options

Idempotency

High-Volume Ingestion

​The Metering Flow

​Meters

​Usage Events

​Querying Usage

​Grouping Options

​Idempotency

​High-Volume Ingestion

The Metering Flow

Meters

Usage Events

Querying Usage

Grouping Options

Idempotency

High-Volume Ingestion