Skip to content
Meterry Docs | Meter every Run, Value every Result

How Meterry Works

Meterry is a usage metering + realtime billing infrastructure. It turns raw usage events in any JSON format into auditable, rateable, balance-deductible metrics.

Whether you’re building an LLM API gateway, an agent platform, or any product that needs usage-based billing, Meterry handles the “how much” and “how much it costs” layer — you focus on your product.

How It Works

Section titled “How It Works”

Meterry system architecture diagram

Meterry is organized into two core domains, each with clear responsibilities:

Meter

Ingests raw events, extracts dimensions and measurable metrics via rules, and applies pricing. Key components: Events, Rules, Metrics.

Billing

Manages accounts and wallets, performs balance deduction, and generates invoices. Key components: Subject, Account, Wallet, Invoice.

The system is auditable, idempotent, and realtime — every usage record is traceable to its raw event, and every deduction is accounted for.

The Journey of a Usage Event

Section titled “The Journey of a Usage Event”

Let’s walk through a token usage event from an LLM gateway to see how data flows through Meterry:

1. Ingest a raw event Your product or gateway sends a JSON payload to Meterry’s Ingest API. The structure is entirely up to you — it can be OpenAI format, Anthropic format, or your own schema.

{
  "provider": "openai",
  "model": "gpt-4.1",
  "usage": { "prompt_tokens": 1200, "output_tokens": 300 },
  "user_id": "u_01"
}

2. Rule-based extraction The extractor rule ID is specified in the ingestion request URL path. Meterry applies the published rule to extract dimensions and metrics from the raw JSON. Rules determine what the subject is (who used it), what the dimensions are (attribute labels), and what the metrics are (what’s being measured, and how much).

3. Rating Each metric is matched with a price and becomes rated. Pricing can be defined directly in the rule (recommended), or via separate pricing rule sets for complex scenarios. Metrics without a matching price stay unrated and can still be used for usage analytics.

4. Subject → Account mapping Through a Subject Route, each usage subject is bound to a account. Each subject belongs to exactly one account; one account can have many subjects — for example, a team account where all team members’ usage rolls up to the same wallet.

5. Balance deduction & billing The account’s Wallet is deducted in realtime or per billing cycle. Low-balance webhooks fire when thresholds are crossed, and invoices are generated each billing period.

Key Distinctions

Section titled “Key Distinctions”

Before diving deeper, clarify these concept pairs — they come up throughout the docs:

Meter vs Billing

Section titled “Meter vs Billing”
  • Meter is about “how much was used” — events, metrics, dimensions, aggregation
  • Billing is about “how much it costs” — accounts, wallets, balances, invoices

Metering feeds billing. You can use metering alone for usage analytics without connecting billing.

Subject vs Account

Section titled “Subject vs Account”
  • Subject is the usage producer (a user, project, device, or agent instance)
  • Account is the payer, holding the Wallet and balance

They have a 1:n relationship: one account can cover many subjects. Subject Route maps usage producers to paying accounts.

Rated vs Unrated

Section titled “Rated vs Unrated”
  • Rated: a metric has a matched unit price and a known monetary amount
  • Unrated: a metric has quantity but no price yet — still usable for stats and analytics

Consumed vs Unconsumed

Section titled “Consumed vs Unconsumed”
  • Consumed: the event was successfully extracted into measurable metrics
  • Unconsumed: the event was recorded but could not be extracted — still visible for debugging and replay

Next Steps

Section titled “Next Steps”