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

# Billable Metrics

> Define what you measure and how to aggregate it

Billable metrics define what you measure in your product. Every unit of consumption — tokens, compute hours, storage, API calls — starts as a metric.

## Core concepts

A billable metric is a measurable unit. It doesn't have a price — that comes later when you create plans. It can also be used independently of billing, purely for metering and entitlement enforcement.

Each metric belongs to exactly one product and specifies:

* **Name** — What customers see (e.g., "Input Tokens", "GPU Hours")
* **Unit** — How it's measured (e.g., "tokens", "hours", "GB")
* **Aggregation** — How to combine usage values over a period

## How metrics work

Billable metrics track variable consumption through events. Perfect for:

* LLM tokens processed
* Compute hours consumed
* Data transferred
* Queries executed

You report usage via events, and Paygentic aggregates it per billing period or entitlement window.

<Note>
  For fixed charges like platform fees, subscriptions, or setup costs, use [Fees](/platform/pricing/fees) instead of billable metrics.
</Note>

## Aggregation types

Specify how raw event values are combined when calculating usage:

| Aggregation    | Description                                        |
| -------------- | -------------------------------------------------- |
| `sum`          | Total of all values in the period                  |
| `count`        | Number of events, regardless of value              |
| `avg`          | Mean of all values                                 |
| `min`          | Smallest value recorded                            |
| `max`          | Largest value recorded                             |
| `unique_count` | Count of distinct values (e.g., unique user IDs)   |
| `latest`       | Most recent value (useful for gauge-style metrics) |

## Meter configuration

To receive [meter events](/platform/metering/meter-events), a billable metric needs three additional fields that define how it reads from the event stream:

### `eventType`

The `type` value your events carry. Only events with a matching `type` field contribute to this metric.

```
eventType: "ai.inference"
```

### `valueProperty`

A JSONPath expression pointing to the numeric value inside the event `data` payload. Required for all aggregations except `count`.

| Path                  | Extracts                      |
| --------------------- | ----------------------------- |
| `$.tokens`            | Top-level `tokens` field      |
| `$.usage.inputTokens` | Nested field via dot notation |

### `groupBy`

A map of dimension names to JSONPath expressions. Allows slicing usage by properties like model, region, or tier.

```json theme={null}
{
  "model": "$.model",
  "region": "$.region"
}
```

**Full example:** a billable metric for AI inference, aggregating token usage and allowing breakdowns by model:

```json theme={null}
{
  "name": "AI Tokens",
  "unit": "tokens",
  "aggregation": "SUM",
  "eventType": "ai.inference",
  "valueProperty": "$.tokens",
  "groupBy": {
    "model": "$.model"
  }
}
```

<Note>
  Multiple billable metrics can share the same `eventType`. Each extracts a different `valueProperty` from the same events. This lets you track input and output tokens separately while sending a single event per inference.
</Note>

## Real-world examples

**LLM Service**

Separate input and output for different pricing:

* Metric: "Input Tokens" — `eventType: "ai.inference"`, `valueProperty: "$.inputTokens"`, aggregation: `sum`
* Metric: "Output Tokens" — `eventType: "ai.inference"`, `valueProperty: "$.outputTokens"`, aggregation: `sum`
* Metric: "Fine-tuning Hours" — `eventType: "training.job"`, `valueProperty: "$.durationHours"`, aggregation: `sum`

**Data Platform**

Track different resource types:

* Metric: "Storage" — `eventType: "storage.usage"`, `valueProperty: "$.gbHours"`, aggregation: `sum`
* Metric: "Compute" — `eventType: "compute.usage"`, `valueProperty: "$.vcpuHours"`, aggregation: `sum`
* Metric: "Queries" — `eventType: "query.executed"`, aggregation: `count`

**Video Processing**

Measure processing and delivery:

* Metric: "Minutes Processed" — `eventType: "video.transcode"`, `valueProperty: "$.durationMinutes"`, aggregation: `sum`
* Metric: "Bandwidth" — `eventType: "video.delivery"`, `valueProperty: "$.transferGB"`, aggregation: `sum`

## Reporting usage

Once metrics are defined, report usage by sending meter events. See [Meter Events](/platform/metering/meter-events) for the full ingestion guide, including multi-dimensional metering and idempotency.

## Next steps

After defining metrics:

1. [Send meter events](/platform/metering/meter-events) to start recording usage
2. [Create plans](/platform/pricing/plans) to group your offerings
3. [Set prices](/platform/pricing/prices) for each metric