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

# Meter Features

> Track quantitative usage with meter features — set limits, reset periods, and aggregation types.

Meter features are the most powerful feature type in Fluxrate. They combine **usage tracking** with **entitlement enforcement**, letting you both bill for usage and gate access when limits are hit.

## How Meter Features Work

When you create a meter feature, Fluxrate automatically creates:

1. A **Feature** (the entitlement definition)
2. A corresponding **Meter** (the usage tracking engine)

The meter has a unique `meter_token` that your backend uses to send usage events.

## Creating a Meter Feature

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Features** in the sidebar
    2. Click **Add Feature**
    3. Select **Meter** as the type
    4. Configure the meter settings and click **Create**
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://api.fluxrate.co/api/v1/features \
      -H "Content-Type: application/json" \
      -H "Cookie: access_token=<token>" \
      -d '{
        "name": "API Calls",
        "lookup_key": "api_calls",
        "description": "Number of API requests made",
        "type": "meter",
        "meter_name": "api_calls",
        "property_name": "call_count",
        "aggregation_type": "SUM",
        "unit": "calls"
      }'
    ```
  </Tab>
</Tabs>

### Request Fields

| Field              | Required | Description                                            |
| ------------------ | -------- | ------------------------------------------------------ |
| `name`             | ✅        | Display name for the feature                           |
| `lookup_key`       | ✅        | Unique identifier (slug) for this feature              |
| `meter_name`       | ✅        | Internal meter identifier (must be unique per org)     |
| `property_name`    | ✅        | The event payload property to read for aggregation     |
| `aggregation_type` | ✅        | How to aggregate: `SUM`, `MAX`, `UNIQUE_COUNT`, `LAST` |
| `unit`             |          | Display unit (e.g., "calls", "GB", "tokens")           |
| `description`      |          | Human-readable description                             |

## Aggregation Types

### SUM

Adds up all values received in the billing period.

**Best for**: API calls, data transferred, messages sent, compute minutes.

```json theme={null}
// Events
{ "property_name": "1" }  // call 1
{ "property_name": "1" }  // call 2
{ "property_name": "5" }  // bulk operation

// Result: SUM = 7
```

### MAX

Takes the highest single value observed during the period.

**Best for**: Peak concurrent connections, high-water mark measurements.

```json theme={null}
// Events
{ "property_name": "10" }  // 10 concurrent connections
{ "property_name": "25" }  // peak: 25
{ "property_name": "15" }

// Result: MAX = 25
```

### UNIQUE\_COUNT

Counts the number of distinct values of a property.

**Best for**: Monthly active users, unique devices, distinct API consumers.

```json theme={null}
// Events (counting unique user_ids)
{ "user_id": "user_a" }
{ "user_id": "user_b" }
{ "user_id": "user_a" }  // duplicate - not counted again

// Result: UNIQUE_COUNT = 2
```

<Note>
  For `UNIQUE_COUNT` meters, send the value to count as the `metadata.user_id` field. The SDK endpoint handles this mapping automatically.
</Note>

### LAST

Takes the most recent value received.

**Best for**: Current storage usage, current seat count (snapshot billing).

```json theme={null}
// Events received over time
{ "property_name": "50" }  // at 10:00
{ "property_name": "75" }  // at 14:00
{ "property_name": "60" }  // at 18:00

// Result: LAST = 60
```

## Usage Filters

Meter features support **filters** to segment events. For example, track API calls only from specific regions or versions:

```bash theme={null}
curl -X POST https://api.fluxrate.co/api/v1/features \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "name": "Premium API Calls",
    "lookup_key": "premium_api_calls",
    "type": "meter",
    "meter_name": "premium_api_calls",
    "property_name": "call_count",
    "aggregation_type": "SUM",
    "filters": [
      {
        "key": "tier",
        "values": ["premium", "enterprise"]
      }
    ]
  }'
```

### Filter Rules

* Maximum **5 filters** per meter
* Each filter supports up to **15 values**
* Values are matched exactly (strings)
* Filter **keys cannot be added or removed** after creation — only values can be updated

## Setting Entitlement Limits

When attaching a meter feature to a plan, configure the usage limit:

```bash theme={null}
# Unlimited usage
{
  "feature_id": "<feature_id>",
  "is_enabled": true,
  "is_unlimited": true
}

# Limited usage
{
  "feature_id": "<feature_id>",
  "is_enabled": true,
  "usage_limit": 10000,
  "usage_reset_period": "month",
  "is_soft_limit": false
}
```

| Option               | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| `is_unlimited: true` | No usage cap — just track and bill                           |
| `usage_limit`        | Maximum units allowed in `usage_reset_period`                |
| `usage_reset_period` | When the counter resets: `day`, `week`, `month`, `year`      |
| `is_soft_limit`      | `true` = warn but don't block; `false` = hard block at limit |

<Tip>
  Use **soft limits** in SaaS products where you want to upsell users who exceed their plan, rather than hard-blocking them.
</Tip>