Metrics and aggregations
Define what you count, how events add up for a billing period with sum or gauge, and which properties your usage events may carry.
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
| 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.
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.
Aggregations
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
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.
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.
Which one to pick
- Use
sumwhen each event is something that was used up: you would add the numbers together to bill. - Use
gaugewhen 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
sumof 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
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. 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.
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
See Create a metric.
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:
{
"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 (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 answers up to 500 metrics, with no paging. To change a metric, send its whole definition with Create or replace a 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
Give the metric a price with a rate plan, then put it on a customer with an entitlement.
Send usage
Send usage events from your server to the Comecero usage meter in batches, read the answer for each event, and resend safely without counting twice.
Entitlements
What each customer gets on an agreement. Metered usage on a pinned price version, an included allowance, an overage policy, and prepaid credit balances.