Analytics, cost, and token accounting

Use this page to understand how analytics endpoints compute usage, estimated cost, latency distributions, and error-rate breakdowns from stored traces. You can use these endpoints for spend visibility, reliability analysis, and capacity planning.

At a glance

Returns usage totals from trace records.
Returns estimated cost totals from trace records.
Returns latency distribution stats with optional grouped breakdowns.
Returns error-rate breakdown stats with optional grouped breakdowns.
Returns model and API-key-hash activity summaries.
Returns combined summary metrics across usage, cost, model activity, and key activity.

Practical fit

You need usage visibility by provider and model.
You need cost trend data for budget controls.
You need latency and error-rate visibility for gateway SLO monitoring.
You need tenant-scoped analytics in shared gateway environments.

Data flow

Proxy requests are captured as traces.
Analytics handlers query the trace store for aggregate data.
Tenant scope is applied from authenticated identity when auth is enabled.
Usage and cost series support optional grouping and time buckets.
Latency and error endpoints support grouped breakdowns by provider/model/route/key.
Summary endpoint combines usage, cost, model, and key aggregates in one response.

First query pattern

No feature flag is required. Analytics APIs are available when trace storage is configured and trace data exists.

If auth.enabled=true, analytics endpoints require gateway auth with analytics:read permission.

Query patterns

Filter usage by provider, model, from, and to.
For usage and cost series, use group_by as provider or model.
For usage and cost series, use bucket as hour, day, or week.
For latency and errors, use group_by as provider, model, route, or key.

Example calls

Usage summary for one provider

Bash

curl "http://localhost:8080/api/analytics/usage?provider=openai"

Hourly cost series grouped by model

Bash

curl "http://localhost:8080/api/analytics/cost?group_by=model&bucket=hour"

Time-bounded analytics window

Bash

curl "http://localhost:8080/api/analytics/summary?from=FROM_ISO8601&to=TO_ISO8601"

Latency breakdown grouped by provider

Bash

curl "http://localhost:8080/api/analytics/latency?group_by=provider"

Error-rate breakdown grouped by route

Bash

curl "http://localhost:8080/api/analytics/errors?group_by=route"

Placeholders:

FROM_ISO8601: Start timestamp in RFC3339 format.
TO_ISO8601: End timestamp in RFC3339 format.

Validation checklist

Send proxied traffic through /openai/... or /anthropic/....
If auth.enabled=true, include your gateway key header on API reads.

Query analytics endpoints:

Bash

curl "http://localhost:8080/api/analytics/usage"
curl "http://localhost:8080/api/analytics/cost"
curl "http://localhost:8080/api/analytics/models"
curl "http://localhost:8080/api/analytics/keys"
curl "http://localhost:8080/api/analytics/latency?group_by=provider"
curl "http://localhost:8080/api/analytics/errors?group_by=route"
curl "http://localhost:8080/api/analytics/summary"

If auth is enabled, include the gateway key header:

Bash

curl "http://localhost:8080/api/analytics/summary" \
  -H "X-OngoingAI-Gateway-Key: GATEWAY_KEY"

Placeholder:

GATEWAY_KEY: Gateway key token with analytics:read permission.

You should see:

Non-zero totals after successful proxied requests.
Grouped series output for usage and cost when group_by and bucket are provided.
Grouped breakdown output for latency and errors when group_by is provided.
top_model and active_keys fields in summary responses.

Troubleshooting

Analytics returns `401` or `403`

Symptom: Analytics endpoints reject requests.
Cause: Missing gateway key, or key lacks analytics:read.
Fix: Provide a valid gateway key with analytics permission.

Analytics returns zero totals

Symptom: Usage and cost totals remain zero.
Cause: No proxied traffic has been captured in trace storage.
Fix: Send provider requests through gateway routes, then query analytics again.

Analytics returns `400` for query validation

Symptom: Request fails with invalid group_by, invalid bucket, or invalid date range errors.
Cause: Unsupported query values.
Fix: Use supported values: group_by=provider|model for usage/cost, bucket=hour|day|week for usage/cost series, group_by=provider|model|route|key for latency/errors, and to >= from.

Analytics returns `500` or `503`

Symptom: Analytics endpoint reports backend errors.
Cause: Trace store is unavailable or query execution failed.
Fix: Verify storage driver configuration and trace store health.