Meter every token. Attribute every cost.

Open-source usage metering for AI gateways and multi-tenant products — customer-level tokens and cost, without a full billing suite.

Run locally with make demo View on GitHub

Discuss your usage reconciliation

Apache 2.0 · HTTP Custody · Python SDK · OpenAPI · Architecture

Usage event POST /ingest

{
  "customerId": "acme",
  "modelId": "gpt-4o-mini",
  "inputTokens": 1200,
  "outputTokens": 400
}

raw event

Customer usage line monthly usage

{
  "customer_id": "acme",
  "bucket": "2026-09",
  "input_tokens": 1200,
  "output_tokens": 400,
  "total_tokens": 1600,
  "cache_read_tokens": 0,
  "reasoning_tokens": 0,
  "event_count": 1,
  "cost_usd": 0.00042
}

customer ledger

Illustrative monthly API response using the real BucketUsage fields and numeric cost. Not a live response; 202 is custody, not settlement. Example cost uses gpt-4o-mini catalog rates from engine config/pricing.json (input $0.15/MTok, output $0.60/MTok). GET /usage/customer/acme/period/2026-09

quick start

bash

git clone \
  https://github.com/10kshuaizhang/fluxmeter.git
cd fluxmeter
make demo

No provider key. Wait for /ready, send a unique event, and poll for 1,600 tokens and $0.00042. Look for PASS.

Full steps, prerequisites and troubleshooting →

Primary wedge

Built for AI gateways and token resellers.

One upstream AI account often serves many downstream customers. Provider totals are not customer-level billable usage.

Upstream provider totals

provider invoice · one pool

Customer-level billable usage

acme · 1600 tok · $0.00042

Illustrative use cases

From model response to usage line.

Core metering first. Control and export stay optional.

Ingest

SDK or Gateway via HTTP Custody.
Price

Model-specific input/output token rates.
Attribute

By customer, period, model, or span.
Control (optional)

Check, reserve, reconcile.
Export (optional)

Usage lines to billing or warehouse.
customer-level usage record

One path: HTTP Custody.

SDK/Gateway → HTTP Custody → Kafka ACK + identity finalize → Flink billing/aggregation → Redis query → Usage API.

Supported path

SDK / Gateway

HTTP Custody

Kafka

Flink

Redis

Usage API

make demo starts the only supported full stack. ClickHouse is an audit cold store — not billing truth.

make demo = supported stack
Gateway: estimate → gate → reserve → upstream → Custody
Intelligence stays heuristic / secondary

Engine 4.8.4. Python SDK 2.0.1 / JS SDK 2.0.0 are repository versions — package-index publication not reverified.

Run customer-level usage locally.

Run make demo to start the stack and verify one customer’s tokens and cost. No provider key required.

Jump to quick start View source

Demo compose may leave authentication optional — enable API keys before any public or shared exposure.

Going deeper? Intelligence · Landscape · Compare · FAQ