Create Metrics

A billable metric is the rule that turns a stream of usage events into one number per customer per billing period: which event_name to read, which events to keep (filters on event properties), and how to aggregate them (count, sum, max, and so on). Metered prices on your products reference a metric, and Alguna evaluates it when it generates each invoice. Define a metric before you send events for it — the dashboard and the API both work — then send usage events with a matching event_name. Where metrics sit between events, prices and invoices is described in How Alguna works.

What a metric contains

Field	Required	Description
`name`	Yes	Display name, for example “API Requests”
`event_name`	Yes	The `event_name` of the events to aggregate
`aggregation`	Yes	`method` plus, for every method except `count`, the event property `field` to read
`filter_groups`	No	Property filters applied before aggregation; groups are ANDed, filters inside a group use the group’s `and`/`or`
`description`	No	What the metric measures
`tag_ids`	No	Tags for organizing metrics

Aggregation methods

Method	Result
`count`	Number of matching events
`count_unique`	Number of distinct values of `field`
`sum`	Sum of `field` across matching events
`average`	Mean of `field`
`min`	Smallest `field` value
`max`	Largest `field` value

Filter operators

equal, not_equal, contains, not_contains, includes, not_includes (comma-separated list), gt, gte, lt, lte. Filter values are always strings. Full semantics are in the metrics reference.

Create a metric via the API

curl -X POST https://api.alguna.io/metrics \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requests (NA)",
    "description": "API requests served from the NA region",
    "event_name": "api_request",
    "aggregation": { "method": "sum", "field": "value" },
    "filter_groups": [
      {
        "operator": "and",
        "filters": [
          { "field": "region", "operator": "equal", "value": "NA" }
        ]
      }
    ]
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/metrics",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "name": "API Requests (NA)",
        "description": "API requests served from the NA region",
        "event_name": "api_request",
        "aggregation": {"method": "sum", "field": "value"},
        "filter_groups": [
            {
                "operator": "and",
                "filters": [
                    {"field": "region", "operator": "equal", "value": "NA"}
                ],
            }
        ],
    },
    timeout=10,
)
response.raise_for_status()
metric = response.json()
print(metric["id"])  # mtr_...

const metric = await alguna.metrics.create({
  name: "API Requests (NA)",
  description: "API requests served from the NA region",
  event_name: "api_request",
  aggregation: { method: "sum", field: "value" },
  filter_groups: [
    {
      operator: "and",
      filters: [{ field: "region", operator: "equal", value: "NA" }],
    },
  ],
});

The response is the metric with its id (prefixed mtr_), which you reference from a metered price’s metric_ids. Read metrics back with GET /metrics and GET /metrics/{id}; editing an existing metric is done in the dashboard or through the MCP server’s update_billable_metric tool. Reference: Create a billable metric, List billable metrics, Get a billable metric.

Create a metric in the dashboard

Open Billable Metrics and click Create Metric.

Billable metric details

Metric name — a clear name, for example “API Requests”.
Description — what the metric measures, for example “Number of API requests made by the customer”.

Choose the event

Event name — start typing to pick an event name you already send, or enter a new one. Events with this event_name feed the metric.

Filter by property (optional)

Keep only events whose properties match. Each filter is a property name, a condition (equals, contains, does not contain, and so on) and a value — for example region equals NA.

Match all / match any — a group either requires every filter in it (AND) or any one of them (OR).
Filter groups — separate groups are always combined with AND, so add a second group when you need (A OR B) AND C.

Aggregation method

Aggregation type — one of the methods above.
Over property — for every method except count, the event property to aggregate, for example value or duration.

New Metric form: metric name and description, event selection, optional property filters, and the aggregation type and property

Example

A SaaS product prices on seats and on API requests, and charges different rates per region because its API runs in NA, EMEA and APAC. Send two event types:

merchant_seat_changed whenever a user is added or removed, with a total_seats property carrying the current seat count.
api_request for each request, with a region property and a value property carrying the number of requests.

Then create four metrics:

Metric	Event	Filter	Aggregation
Merchant Seats	`merchant_seat_changed`	—	`max` of `total_seats` (or `average`, depending on how you want to charge)
API Requests (NA)	`api_request`	`region` equal `NA`	`sum` of `value`
API Requests (EMEA)	`api_request`	`region` equal `EMEA`	`sum` of `value`
API Requests (APAC)	`api_request`	`region` equal `APAC`	`sum` of `value`

Attach each metric to a metered product with its own price — see Pricing models.

Next steps

Send usage events

The event shape, batching, deduplication and CSV import.

Metrics reference

Every aggregation, filter operator and worked example.

Usage metering quick start

Metric → product → plan → events, end to end.

Credit consumption

Price events against a prepaid balance in real time.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

What a metric contains

Aggregation methods

Filter operators

Create a metric via the API

Create a metric in the dashboard

Example

Next steps

Send usage events

Metrics reference

Usage metering quick start

Credit consumption

​What a metric contains

​Aggregation methods

​Filter operators

​Create a metric via the API

​Create a metric in the dashboard

​Example

​Next steps

Send usage events

Metrics reference

Usage metering quick start

Credit consumption

What a metric contains

Aggregation methods

Filter operators

Create a metric via the API

Create a metric in the dashboard

Example

Next steps