Usage

The /usage page is the tenant's daily traffic chart — counts and billable units across whatever group dimension is most useful for the moment. Visible to every role.

Group dimensions

The Group by picker controls how the data is sliced. Each option produces one line on the chart per distinct value of that dimension.

Group by	Series shown	When it's useful
feature	ocr, face_verify, face_register, face_search, face_dedupe, liveness_check, session_create	The default — see which features are driving traffic.
variant	cid, passport, cid_two_sided, face_1_to_1, face_1_to_n, liveness_passive, liveness_burst, liveness_challenge_*	Drill into a single feature's sub-types. Especially useful for OCR (CID vs passport mix) and liveness (which challenges your users actually face).
status	success, validation_error, rate_limited, feature_disabled, internal_error, …	See your error breakdown over time. A jump in validation_error signals client misuse; a jump in internal_error is a platform incident worth reporting.

Metric toggle

The Metric picker switches the Y axis:

• Requests — raw API call count. One increment per request, regardless of body size or what the request actually billed for.
• Billable units — what the platform actually charged you. Aligns 1:1 with your invoice. The bill differs from raw request count for:
  • OCR with back_image — two billable units per request (front + back are scored separately).
  • Face search across large galleries — units scale with gallery size in some plan tiers (check your contract).
  • Failed validations — validation_error responses generally do NOT bill (the work didn't reach the inference services); internal_error responses on the platform side don't bill either.

For finance reconciliation use Billable units; for engineering capacity planning use Requests.

Time window

7 / 30 / 90 day buttons. The chart re-fetches when you change windows. 90 days is the maximum retention for the daily-aggregate table — older usage rolls up to monthly totals (not currently surfaced in the dashboard; query the invoice for history beyond 90 days).

Live ⇄ test toggle

The same ModeToggle that appears on Keys, Webhooks, and the Audit log. Test-mode usage is bucketed separately and does not bill — useful for sanity-checking your integration without spending against your monthly quota.

Empty state

A brand-new tenant or a tenant that's only ever exercised the test mode might see "No usage in the selected window" instead of a chart. That's the empty state, not a bug — the chart suppresses a confusing flat-line-at-zero render.

Data freshness

Usage events are committed to the daily-aggregate table by a background rollup that runs every few minutes. Expect the most recent day's data to lag real-time traffic by ~10 minutes. The audit log (/audit) shows requests within seconds — use it if you need to verify a specific call landed.

Hard caps

If your plan has a hard cap and you approach it, the chart shows a horizontal red dashed line at the cap. Crossing the cap triggers 429 quota_hard_cap_exceeded responses for that feature until the next billing window begins. The audit log surfaces those rejections individually. Soft warnings (e.g. 80% of cap) email the tenant admins.