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

> Query, visualize, and analyze usage data across customers, meters, and time periods.

Fluxrate provides rich usage analytics to help you understand consumption patterns, identify top customers, and forecast revenue.

## Meter-level Analytics

Get aggregated usage statistics for any meter:

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

### Query Parameters

| Parameter     | Description                                 | Default       |
| ------------- | ------------------------------------------- | ------------- |
| `start_date`  | Start of the analysis window                | 30 days ago   |
| `end_date`    | End of the analysis window                  | Now           |
| `group_by`    | Granularity: `hour`, `day`, `week`, `month` | `day`         |
| `customer_id` | Filter to a specific customer               | All customers |

### Response

```json theme={null}
{
  "meter_id": "550e8400-...",
  "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
    }
  ]
}
```

## Meter Stats

Quick statistics snapshot for a meter:

```bash theme={null}
GET /api/v1/meters/<meter_id>/stats
```

```json theme={null}
{
  "meter_id": "...",
  "total_events": 1250000,
  "unique_customers": 342,
  "first_event_date": "2024-06-01T00:00:00Z",
  "last_event_date": "2025-01-31T23:59:00Z",
  "today_usage": 4200,
  "this_week_usage": 28100,
  "this_month_usage": 82450
}
```

## Customer-level Usage

View usage for a specific customer:

```bash theme={null}
GET /api/v1/customers/<customer_id>/usage
```

## Event-level Logs

Paginate through raw usage events for a meter:

```bash theme={null}
GET /api/v1/meters/<meter_id>/events?page=1&page_size=50
```

```json theme={null}
{
  "data": [
    {
      "id": "...",
      "customer_id": "...",
      "meter_id": "...",
      "quantity": "100",
      "ingested_at": "2025-01-15T10:30:00Z",
      "idempotency_key": "req_123",
      "meta_data": { "region": "us-east-1" }
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 50,
    "total": 12300,
    "total_pages": 246
  }
}
```

## Dashboard

The Fluxrate dashboard provides visual analytics:

* **Usage trends** — Line charts of usage over time
* **Top customers** — Ranked by usage volume
* **Revenue at risk** — Subscriptions with unpaid invoices
* **MRR tracking** — Monthly recurring revenue over time

Navigate to **Dashboard** in the sidebar to explore.

## Usage Logs Page

The **Usage Logs** section in the dashboard lets you browse and filter all raw usage events. Filter by:

* Meter
* Customer
* Date range
* Minimum quantity