Skip to main content
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_byDescription
hourHourly breakdown
dayDaily breakdown (default)
weekWeekly breakdown
monthMonthly 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:
  1. Batching events — Aggregate at your backend before sending (e.g., send message count every minute, not per message)
  2. Async sending — Use a message queue to send events asynchronously
  3. Pre-aggregation — Use your own counters and periodically sync totals
See the Infrastructure Cost Guide for scaling recommendations.