FAQ
Frequently asked questions
Operator-focused answers. Demo auth, SDK status, and performance qualifications stay explicit.
Getting started
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.
Can I self-host FluxMeter?
Yes. make demo runs the supported stack locally with docker-compose. Apache 2.0 with no vendor lock-in.
How do I integrate with the fewest lines of code?
Use the repository Python SDK (2.0.1 — package-index publication not reverified). FluxMeter(api_url=...) over HTTP Custody, then wrap(OpenAI(), meter, customer_id=...). wrap() runs pre-call check and post-call track. Configure fail_open explicitly; metering failures warn and can invoke on_metering_error. Checks create no hold and cached fallback/streaming estimates do not guarantee zero overspend. Hierarchy holds use reserve(parent_span_id=) / reconcile(parent_span_id=). There is no kafka_brokers client SDK path.
What is FluxMeter Intelligence?
Heuristic / rule-based APIs under /intelligence/* — root-cause decomposition, unit economics, scenario simulation, pricing recommendations, profitability views, forecast, alerts, and report export. Reads native usage/cost rollups; optional revenue overlay from OpenMeter or manual POST. Not an ML consulting platform.
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.
Is metering still maintained?
Yes. Real-time token metering (ingest, price, customer usage queries, HTTP Custody, Gateway) is the core product. Optional hard gates and Intelligence sit on the same data — they do not replace metering.
Metering and attribution
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 (sessionId). Agent tasks use parentSpanId with GET /usage/span/{id} — Flink SpanSink aggregates spans on the supported stack. From v2.8, whitelist metadata dims and query GET /usage/dim/{key}/{value}?period=YYYY-MM for feature or workflow slices.
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 and Anthropic models, plus Chinese domestic model mappings. Google models can be sent via generic provider fields. The Python SDK includes track_* helpers; the JavaScript SDK is available in the repository and is not published on npm yet.
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.
Budgets and controls
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).
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.
Do budget webhooks work on the supported stack?
Yes. Configure with POST /budget/{id}/webhook. On the supported stack, Flink emits budget alerts to Kafka topic budget-alerts; a webhook worker delivers BUDGET_LOW, BUDGET_EXHAUSTED, and BUDGET_WARN (70% and 90% of initial_balance + topups).
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.
Runtime and performance
How fast are FluxMeter budget checks?
Pre-request budget-check latency remains a design target, not a published SLA. The separate HTTP ingest benchmark accepted 10,034.90 events/s at p50 36ms / p99 173ms over 30 minutes, with 0.149% generator offer drops. The retained full pipeline reached 7,772.28 events/s at p50 222ms / p99 1,472ms, so its 10K gate remains open. See engine docs/load-testing.md.
Billing exports and integrations
What billing platforms does FluxMeter integrate with?
FluxMeter ships built-in exporters for Stripe, Metronome, and Orb (BILLING_EXPORT_TARGETS), plus generic POST /admin/billing/{id}/link. Lago, OpenMeter, and Zuora are covered by example recipes under docs/integrations/ — not partnerships. Supports tiered pricing and prepaid token packages. FluxMeter enforces; your billing platform remains the invoice system of record.
Security and operations
Is the local demo safe to expose on the public internet?
Not by default. Demo compose may run with authentication optional (FLUXMETER_AUTH_OPTIONAL). Enable API keys (and prefer fail-closed budget policy) before any public or shared exposure. Operators own production hardening.