Usage Reporting

Use the Usage view to compare request volume, token consumption, and spend across AISIX gateway environments and models. It also summarizes organization-wide semantic-cache savings and helps you investigate unexpected spend or confirm that usage records are reaching the control plane.

How Usage Is Reported

An AISIX gateway serves AI traffic in your runtime environment and reports usage events to the control plane. It derives the telemetry endpoint from the control-plane URL and sends usage data to the fixed /dp/telemetry path. Operators do not configure a separate destination for control-plane usage reporting.

Each event can include request status, latency, token usage, and cost. It also distinguishes the model alias requested by the caller from the resolved model that served an attempt, which helps explain routed and ensemble traffic. Streaming chat requests can report time to first token.

AISIX uses nonzero provider-reported token counts when available. For streaming requests, AISIX also requests usage data from OpenAI-compatible upstreams in the final stream chunk.

The Chat Completions, Completions, Messages, Responses, and Embeddings endpoints may return responses that omit some or all usage data. Examples include an OpenAI-compatible relay that never reports usage, a client that disconnects mid-stream, or an upstream error after a partial response. In those cases, AISIX estimates missing or zero token fields with a local tokenizer. It estimates input tokens from the request sent upstream and output tokens from content delivered to the caller while retaining nonzero provider-reported values.

AISIX emits the usage event with the estimated counts, so the request remains included in telemetry, spend, budgets, and token rate-limit accounting. Locally counted events are marked as estimated, and the Request Logs view shows an estimated badge on those rows. Estimated counts closely match OpenAI-family models and are approximations for models with proprietary tokenizers. Estimation does not change the provider response returned to the caller and does not apply to other endpoint families or provider passthrough.

Interpret Usage

The Usage view summarizes AISIX gateway traffic across environments over a rolling 30-day window. All totals and tables use this same window.

Signal	What It Helps Explain
Request count	Traffic volume and changes in demand.
Token totals	Input and output consumption reported by providers.
Spend	Cost calculated by applying matching model rates to token counts and, for duration-priced transcription or translation requests, measured audio length.
Cache savings	Upstream input and output token consumption avoided by semantic-cache hits.
Usage by environment	Which deployment environment generated traffic and spend.
Top models	Up to 10 environment and caller-requested model alias combinations, ranked by spend. Older records without a requested-model value fall back to the resolved model.
Top API keys	Up to 10 environment and caller API key combinations, ranked by spend.

Where local token estimation is supported, missing or zero token counts are estimated by the gateway. Audio endpoints do not estimate missing token counts; transcription and translation requests can instead contribute duration-based spend. Spend also requires a price that matches the event's (provider, model name) pair and a nonzero rate for the applicable usage basis. Usage rounds spend to two decimal places, so low-volume traffic can show $0.00 even when a matching price exists.

Use Model Pricing to add or inspect a price, and use Request Logs to inspect event or attempt cost at six decimal places. Pricing changes apply only to events recorded after the change.

Usage and Budget Enforcement

The control plane uses AISIX gateway usage records to evaluate budgets. Each budget defines its scope, spending limit, period, and enforcement mode.

The rolling 30-day Usage window is independent of a budget's configured period, so their totals can cover different time ranges.

When a hard-stop budget is exceeded, the AISIX gateway can reject matching requests with HTTP 429. Warn-only budgets surface the over-budget state without blocking traffic.

If a budget rejection is unexpected, check the returned budget scope, the configured limit, and the caller API key bindings that determine which team or member budgets apply. For the complete enforcement path, see Budgets.

Troubleshoot Missing or Unexpected Usage

Check the reporting path in order:

1. Confirm that the request used the AISIX gateway attached to the expected environment. Traffic through another environment in the same organization appears under that environment. Traffic in another organization appears in that organization's Usage view.
2. Check that the request completed and appears in Request Logs. A newly completed request can take a few seconds to appear because gateways flush telemetry in batches.
3. Confirm that the AISIX gateway has a recent heartbeat.
4. Confirm that the gateway can reach the control-plane telemetry endpoint.
5. If spend is zero or unexpected, check Model Pricing for an exact provider and model-name match, then confirm that the applicable token or Audio per minute rate is nonzero.

During a temporary control-plane outage, live traffic can continue with the latest projected configuration. Telemetry batches that fail during the outage are dropped instead of retried, so affected usage records can remain missing after connectivity returns. New records resume after the connection recovers. Exporter health, heartbeat, and fresh budget decisions also require control-plane connectivity. Budget checks can temporarily reuse a cached decision before applying the configured fail mode; see Availability and Caching.

Next Steps

Continue with Model Pricing when spend is zero or differs from the provider's pricing basis. To investigate individual requests or control-plane resource changes, see Logging and Auditing.