# Metrics and aggregations (/docs/usage-billing/metrics-and-aggregations)

A **metric** is one thing you count and bill for, such as AI tokens, API calls, messages sent, GB stored or seats in use. Every usage event names a metric with its `metric_key`, and the metric's **aggregation** says how the events of a billing period become one number to price.

## The parts of a metric [#the-parts-of-a-metric]

| Field | What it is |
| --- | --- |
| `name` | Required, up to 100 characters. Shown on the invoice line, for example "AI tokens". |
| `unit_label` | Required, up to 96 characters. The unit, shown next to the name: "AI tokens (token)". |
| `event_key` | The `metric_key` your app sends with each event. 1 to 64 lowercase letters, digits, `_`, `.` or `-`. Unique in your account and mode, and it never changes. If you leave it out, the `name` is used, which fails for a name with capitals or spaces. |
| `aggregation` | Required: `sum` or `gauge` (see below). It can't change once the metric has been sent to the usage meter. |
| `allowed_properties` | Up to 20 property names an event may carry (1 to 64 letters, digits or `_`), for example `model` or `region`. An event with any other property is rejected. |
| `status` | `active` (the default), or `archived`: the meter then rejects its events with `unknown_metric`. |
| `billing_region` | `us` (default), `uk` or `eu`. |

The usage meter gets a new or changed metric within a few minutes of saving it, often at once. Until it has it, events for that `metric_key` are rejected with `unknown_metric`.

<Callout>
**Set it up in the dashboard:** **Usage Billing**, **Metrics** tab, **Add metric**. **Metric key** is `event_key`, and **Counted as** is the aggregation: **Total (sum)** or **Highest (gauge)**. After a save the metric shows **Updating** until the meter has the change.
</Callout>

## Aggregations [#aggregations]

### `sum`: the total used [#sum-the-total-used]

Adds up the `quantity` of every event in the period. Send what was used each time.

| You bill for | Send |
| --- | --- |
| API calls | `1` per call, or the count of a batch |
| AI tokens | The tokens of each request, for example `"1250"` |
| Messages, emails, SMS | `1` per message |
| Compute time | The minutes or seconds of each job, for example `"12.5"` |
| Storage over time | Measure every hour and send GB-hours, for example `"40"` for 40 GB held for an hour |

Example: a customer sends three events of 1,000, 2,500 and 500 tokens in the period. The period's usage is **4,000 tokens**.

### `gauge`: the highest level reached [#gauge-the-highest-level-reached]

Keeps the highest `quantity` sent in each UTC hour, and bills the **highest hour** of the period. Send a reading of the current level, at least once an hour.

| You bill for | Send |
| --- | --- |
| Peak seats | The number of seats in use right now |
| Peak servers, projects or workspaces | The current count |
| Concurrent connections | The current count |

Example: the hourly readings in a period are 8, 12, 10 and 11 seats. The period's usage is **12 seats**. Give each reading its own `operation_id`, for example `seats_cust_8412_2026-11-01T09`, so readings are not taken as repeats of each other. An `operation_id` is counted once per metric.

<Callout>
Both aggregations work in whole UTC hours: every event counts in the hour of its `timestamp`. The meter keeps a total (for `sum`) or a peak (for `gauge`) for each customer, metric and hour, so billing any period, of any length, reads the same numbers.
</Callout>

### Which one to pick [#which-one-to-pick]

- Use `sum` when each event is something that was **used up**: you would add the numbers together to bill.
- Use `gauge` when each event is a **level** at a point in time: you would bill the most the customer had.
- Something that is held over time, like storage, is a `sum` of hourly readings in unit-hours, so the customer pays for how long they held it, not only the peak.

Quantities are decimals, never negative: up to 12 digits before the point and 6 after. Send them as strings, such as `"0.75"`, so no precision is lost. Late usage only ever adds to a bill. To lower a bill after usage was billed, refund it on the invoice it was billed on.

## Properties [#properties]

`allowed_properties` lists extra values an event may carry, such as `model`, `region` or `plan_tier`. They are kept with each event, so you can see them when you [look at a customer's events](/docs/usage-billing/follow-usage#the-events-behind-a-bill). Values are strings up to 256 characters, numbers or booleans.

Properties must never hold card numbers, card track data, emails or IP addresses: the meter refuses those events. See [no card data or personal data](/docs/usage-billing/send-usage#no-card-data-or-personal-data).

Properties describe an event. They don't change how it is billed: each metric has one price per customer. To bill two models at two prices, make two metrics, for example `ai_tokens_small` and `ai_tokens_large`.

## Create a metric [#create-a-metric]

See [Create a metric](/api/usage-metrics/create-usage-metric).

````bash
curl -X POST https://api.comecero.com/api/v1/usage/metrics \
  -H "Authorization: Bearer $COMECERO_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metric_id": "met_peak_seats",
    "name": "Seats",
    "event_key": "peak_seats",
    "unit_label": "seat",
    "aggregation": "gauge"
  }'
````

The answer is the metric, with `201`:

````json
{
  "object": "metric",
  "metric_id": "met_peak_seats",
  "name": "Seats",
  "event_key": "peak_seats",
  "unit_label": "seat",
  "aggregation": "gauge",
  "allowed_properties": [],
  "status": "active",
  "version": 1,
  "synced_version": 0,
  "aggregation_locked": true,
  "billing_region": "us",
  "test": false,
  "account_id": "AB1234",
  "date_created": "2026-11-01T09:00:00Z",
  "date_modified": "2026-11-01T09:00:00Z"
}
````

`aggregation_locked` is `true` once the metric is being sent to the usage meter, so its aggregation can't change any more. Read it again a few seconds later with [Get a metric](/api/usage-metrics/get-usage-metric) (`GET /api/v1/usage/metrics/met_peak_seats`): when `synced_version` equals `version`, the usage meter has it and takes events for it.

[List metrics](/api/usage-metrics/list-usage-metrics) answers up to 500 metrics, with no paging. To change a metric, send its whole definition with [Create or replace a metric](/api/usage-metrics/replace-usage-metric) (`PUT /api/v1/usage/metrics/{metric_id}`). A field you leave out is reset, and `event_key` can't change. It answers `201` when it creates the metric and `200` when it updates it.

## Next [#next]

Give the metric a price with a [rate plan](/docs/usage-billing/set-up#2-set-a-price), then put it on a customer with an [entitlement](/docs/usage-billing/entitlements).
