Frequently asked questions
Token-native metering for AI APIs and gateways — with optional guardrails and Intelligence.
What is FluxMeter?
FluxMeter is an open-source, self-hostable real-time, token-native metering engine for AI APIs, token resellers, and multi-tenant gateways. Ingest usage, price tokens, and query per-downstream-customer cost — with optional hard gates and Intelligence on the same data.
How is FluxMeter different from OpenMeter or Lago?
OpenMeter, Lago, and Metronome lean usage → invoice. FluxMeter leans runtime metering correctness plus optional hard gates (check / kill). We complement invoice platforms — we do not replace invoicing, tax, or Merchant of Record.
How fast are FluxMeter budget checks?
Pre-request budget checks target under 10ms latency. The Full deployment path handles 1M+ events per second via Kafka and Flink aggregation.
Can I self-host FluxMeter?
Yes. Lite mode runs locally with docker-compose (make demo). Apache 2.0 license with no vendor lock-in.
Does FluxMeter support streaming LLM responses?
Yes. Use POST /budget/{id}/reserve before streaming, then POST /ingest and POST /reconcile when the stream ends. Effective balance accounts for in-flight holds. From v2.8, pass parent_span_id on reserve to hold the customer wallet and span cap pool together. Python wrap() raises StreamKilledError mid-stream when estimated cost exceeds the reserve (SDK 1.5.0).
What billing platforms does FluxMeter integrate with?
FluxMeter exports usage to Stripe Meters, Metronome, Orb, Lago, OpenMeter, and Zuora. v2.8 ships first-class Metronome/Orb/Stripe exporters (BILLING_EXPORT_TARGETS), generic POST /admin/billing/{id}/link, and partner recipes under docs/integrations/. Supports tiered pricing (flat/volume/graduated) and prepaid token packages. FluxMeter enforces; your billing platform remains the invoice system of record.
Can I query customer billing usage without a data warehouse?
Yes. GET /usage/customer/{id}/period/{YYYY-MM} for monthly usage, GET /usage/customer/{id}/day/{YYYY-MM-DD} for daily spend, and GET /usage/session/{id} for session/project cost (lite sessionId). Agent tasks use parentSpanId with GET /usage/span/{id} — Lite aggregates spans from v2.6.2; Full uses Flink SpanSink. From v2.8, whitelist metadata dims and query GET /usage/dim/{key}/{value}?period=YYYY-MM for feature or workflow slices.
How do I integrate with the fewest lines of code?
pip install fluxmeter (1.5.0+), then FluxMeter(api_url=...) for Lite HTTP mode and wrap(OpenAI(), meter, customer_id=...). wrap() runs pre-call check, post-call track, and fail-open. SDK 1.5.0 adds reserve(parent_span_id=) / reconcile(parent_span_id=) for hierarchy holds. For Full mode pass kafka_brokers instead of api_url.
Can I hard-cap spend per agent run or conversation?
Yes. v2.7 adds POST /budget/{id}/cap with kind span or session. Pass parent_span_id or session_id on GET /budget/{id}/check; overspend returns reason=hierarchy_cap. v2.8 adds hierarchy reserve-confirm: POST /budget/{id}/reserve?parent_span_id= atomically holds the customer balance and span cap pool before the call.
Does Lite mode support budget webhooks?
Yes. v2.7 delivers BUDGET_LOW, BUDGET_EXHAUSTED, and BUDGET_WARN (70% and 90% of initial_balance + topups) on /ingest without Kafka. Configure with POST /budget/{id}/webhook.
Can I set budgets per customer API key?
Yes. v2.8 adds POST /admin/customers/{id}/apikeys/{key_id}/budget. When requests authenticate with that customer API key, GET /budget/{id}/check enforces the per-key budget in addition to the customer wallet.
How do I attribute usage to a product feature or workflow?
v2.8 accepts a metadata object on /ingest (keys whitelisted via FLUXMETER_USAGE_DIMS). Query slices with GET /usage/dim/{key}/{value}?period=YYYY-MM — useful for feature flags, rooms, or workflow labels without a warehouse.
Which LLM providers does FluxMeter support?
Built-in pricing for OpenAI, Anthropic, and Google models, plus 20 Chinese domestic models (DeepSeek, Qwen, GLM, Moonshot, Doubao, Baichuan, MiniMax, Hunyuan). Python and JS SDKs include track_* helpers for auto-extraction from provider responses.
What is FluxMeter Intelligence?
Prescriptive monetization APIs under /intelligence/* — root cause analysis, unit economics, scenario simulation, pricing optimizer, profitability dashboard, forecast, alerts, and report export. Reads native usage/cost rollups; optional revenue overlay from OpenMeter or manual POST.
Does FluxMeter replace OpenMeter or Langfuse?
No. FluxMeter complements them: OpenMeter/Lago for invoicing; Langfuse/Helicone for observability. Intelligence overlays revenue and cost; metering can export events or enforce on the hot path. See the market map at /market-map.
What data does Intelligence need for unit economics?
Cost comes from native FluxMeter ingest rollups. Revenue requires OpenMeter overlay ingest or POST /intelligence/revenue/{customer_id}. Customers without revenue return status unknown_revenue with a connect hint.
Is metering still maintained?
Yes. Real-time token metering (ingest, price, customer usage queries, Lite/Full, Gateway) is the core product. Optional hard gates and Intelligence sit on the same data — they do not replace metering.