> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluxrate.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Metering Overview

> Understand how Fluxrate tracks, aggregates, and bills for usage events.

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

```mermaid theme={null}
sequenceDiagram
    participant App as Your Backend
    participant API as Fluxrate API
    participant DB as Event Store
    participant Worker as Invoice Worker

    App->>API: POST /sdk/track (usage event)
    API->>DB: Store UsageEvent
    API-->>App: 201 Created

    Note over Worker: End of billing period
    Worker->>DB: Query events for period
    DB-->>Worker: Aggregated usage
    Worker->>DB: Create Invoice with line items
```

## 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:

```json theme={null}
{
  "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:

```bash theme={null}
GET /api/v1/meters/<meter_id>/usage?start_date=2025-01-01&end_date=2025-01-31&group_by=day
```

Response:

```json theme={null}
{
  "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`:

```bash theme={null}
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

<Note>
  See the [Infrastructure Cost Guide](/developers/self-hosting) for scaling recommendations.
</Note>