Usage Metering Quick Start

Usage metering bills customers for what they consume — API calls, storage, compute hours, tokens, seats — instead of, or on top of, a fixed fee. In Alguna it takes four things: a billable metric that aggregates your events, a metered product priced on that metric, a plan (or subscription) that includes the product, and the usage events your application sends. This guide sets each up, in the dashboard and with the API. How metrics, prices and invoices fit together is described in How Alguna works.

How usage billing works

Usage occurs — the customer uses your product
Events recorded — your application sends events to POST /events, tagged with the customer and an event_name
Usage aggregated — at invoice time, Alguna evaluates each metric over the billing period
Invoice generated — the aggregated quantity is priced by the product’s pricing model
Payment collected — with the customer’s stored payment method, or by invoice

Step 1: Create a billable metric

A metric names the event_name to read, optional filters on event properties, and the aggregation.

Method	Result	Example
`count`	Number of events	API requests
`sum`	Sum of a property	GB transferred
`count_unique`	Distinct values of a property	Active users
`average`	Mean of a property	Response time
`min`	Smallest value	Lowest latency
`max`	Largest value	Peak concurrent connections

Dashboard: open Billable Metrics, click Create Metric, and set the name, event name and aggregation. 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",
    "event_name": "api_request",
    "aggregation": { "method": "count" }
  }'

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.alguna.io/metrics",
    headers=HEADERS,
    json={
        "name": "API Requests",
        "event_name": "api_request",
        "aggregation": {"method": "count"},
    },
    timeout=10,
)
response.raise_for_status()
metric_id = response.json()["id"]

const metric = await alguna.metrics.create({
  name: "API Requests",
  event_name: "api_request",
  aggregation: { method: "count" },
});

The response includes the metric id (mtr_…). Reference: Create a billable metric; all options in Create metrics and the metrics reference.

Step 2: Create a usage-based product

Dashboard: open Products, click New Product, set Fee type to Metered, choose the metric, and pick a pricing model. API: create the product with Create a product (fee_type: "metered"), then price it when you add it to a plan or subscription — a metered price carries metric_ids: ["mtr_…"] and a pricing model. Examples in Creating a subscription.

Pricing models for usage

Model	Description	Example
Unit	Fixed price per unit	$0.001 per API call
Graduated tiered	Each tier priced at its own rate	First 1,000 free, then $0.01 each
Volume (tiered)	All units at the rate of the tier the total lands in	0–1,000: $0.01 each; 1,001+:$ 0.008 each
Package	Price per block of units	$10 per 1,000 calls

See Pricing models and the API’s pricing model reference.

Step 3: Add it to a plan

Dashboard: open Plans, select or create a plan, click Add Product, choose the metered product, and save. API: include the product in the plan’s items with Create a plan, or put the metered price directly on a subscription with Create a subscription. See Plans.

Step 4: Send usage events

Every event needs:

Field	Description
`event_name`	The metric’s event name, e.g. `api_request`
`account`	The customer’s Alguna ID (`cust_…`) or one of their aliases
`unique_id`	An idempotency key per event, max 72 characters; a resend with the same value is dropped
`timestamp`	When the usage occurred (RFC 3339); optional, defaults to now
`properties`	Up to 50 key/value pairs for filters and `sum`/`max`/… aggregations

curl -X POST https://api.alguna.io/events \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "unique_id": "req_9f1c2e7a",
        "event_name": "api_request",
        "account": "cust_abc123",
        "timestamp": "2026-04-01T10:30:00Z",
        "properties": { "endpoint": "/v1/analyze" }
      }
    ]
  }'

import uuid
from datetime import datetime, timezone

response = requests.post(
    "https://api.alguna.io/events",
    headers=HEADERS,
    json={
        "events": [
            {
                "unique_id": str(uuid.uuid4()),
                "event_name": "api_request",
                "account": "cust_abc123",
                "timestamp": datetime.now(timezone.utc).isoformat(),
                "properties": {"endpoint": "/v1/analyze"},
            }
        ]
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()
if result["failed"]:
    print("rejected:", result["failed"])

const result = await alguna.events.ingest({
  events: [
    {
      unique_id: crypto.randomUUID(),
      event_name: "api_request",
      account: "cust_abc123",
      timestamp: new Date().toISOString(),
      properties: { endpoint: "/v1/analyze" },
    },
  ],
});

Up to 100 events per request; the response lists ingested and failed IDs. For batching, buffering, CSV import and warehouse connectors, see Send usage events. Reference: Ingest billable events.

Usage can also arrive without code — pull it nightly from BigQuery or ClickHouse, or upload a CSV.

Viewing customer usage

Current period

Open Customers and select the customer
Open the Usage tab to see usage by metric, estimated charges and trends

Historical usage and revenue

Open Revenue Insights to filter by customer, metric or date range; see Revenue Insights. The same figures are available through the Insights endpoints.

Common use cases

Use case	Metric	Aggregation	Pricing
API billing	API requests	`count`	Graduated tiered (free tier + overage)
Storage billing	Storage (GB)	`max`	Unit, per GB per month
Compute billing	Compute hours	`sum`	Unit
Active-user billing	Active users	`count_unique`	Unit, per user per month
Token billing	Tokens	`sum` of a `tokens` property	Unit or package

Troubleshooting

No usage showing

Check the failed list in the POST /events response — a 200 does not mean every event was accepted
Confirm event_name matches the metric exactly
Confirm account resolves to the customer on the subscription (ID or alias)
Check timestamps fall within the billing period

Incorrect charges

Review the metric’s aggregation method and field
Check the pricing model on the product
Verify the billing period dates on the subscription

Best practices

Set unique_id on every event

Retries are then safe; the same event is never counted twice.

Use event time

Send the time the usage happened, not the time you sent it.

Test in sandbox

Send known event sets and check the metric before going live.

Filter at the metric

Exclude internal or failed requests with metric filters, not in pricing.

Next steps

Create metrics

Filters, aggregations and API examples.

Pricing models

Unit, tiered, volume and package pricing.

Credits quick start

Sell prepaid credits against the same metrics.

Developer quick start

Auth, SDK, webhooks and sandbox.

​How usage billing works

​Step 1: Create a billable metric

​Step 2: Create a usage-based product

​Pricing models for usage

​Step 3: Add it to a plan

​Step 4: Send usage events

​Viewing customer usage

​Current period

​Historical usage and revenue

​Common use cases

​Troubleshooting

​No usage showing

​Incorrect charges

​Best practices