Usage and Gauge

Track local gateway usage, provider limits, spend, budgets, alerts, and runway

Nexus has two complementary visibility systems:

  • Usage tracks requests that pass through the local Nexus gateway.
  • Gauge tracks limits, resets, spend, status, and account runway across Nexus and external AI tools.

Use Usage to understand what Nexus routed. Use Gauge to understand whether your connected AI accounts have enough capacity.

Usage metrics

Usage tracking records one event for each gateway generation request that reaches a provider.

Recorded fields include:

  • Provider ID
  • Model ID
  • Client token ID
  • Success or failure
  • Provider-reported token counters
  • Tool-call names and counts
  • Route pack decision IDs where applicable
  • Acceleration counters where applicable

Usage does not record:

  • Prompt text
  • Response text
  • Reasoning text
  • Tool arguments
  • Headers
  • Credentials
  • Raw provider bodies

Token-counting and retrieval-only routes are not recorded as generation usage. Image generation can contribute token counters when the provider reports them. Speech, transcription, image edit, and rerank routes are currently unmetered in local Usage aggregates.

Usage views

The Usage tab can show:

  • Summary totals
  • Daily token heatmap
  • Tool-call heatmap
  • Provider/model/token breakdowns
  • Top providers
  • Top models
  • Smart Route paths and fallback reasons
  • Acceleration speed and draft activity

Filters include date range, provider, model, and breakdown dimension. Raw events stay internal; public endpoints return aggregates only.

Gauge

Gauge is optional and off by default. It provides a dedicated workspace for:

  • Quotas and limits
  • Reset times
  • Balances and credits
  • Actual provider spend
  • Estimated spend
  • Provider status
  • Account health
  • Project budgets
  • Alerts
  • Runway recommendations

Each Gauge source is opt-in. Enabling Gauge does not automatically connect external accounts.

The Gauge tab groups this into status, spend, activity, connections, budgets, alerts, reconciliation, and runway views so account health and "can I finish?" decisions are separate from raw local gateway traffic.

Gauge sources and accounts

Gauge supports Nexus-local data plus a growing provider catalog. Sources can use supported authentication modes such as local session, API key, admin key, OAuth, device flow, CLI, local file, custom endpoint, browser session, or AWS credentials depending on the provider.

Reporting credentials are write-only. Source responses show credential presence and status, not credential values or local credential references.

Activity, readings, and status

Gauge separates several concepts:

  • Dashboard: current summary and compact history.
  • Readings: latest cached redacted readings per account.
  • Activity: detailed provider activity loaded only when requested.
  • Statuses: provider status-page health, separate from local credential health.
  • Diagnostics: support-safe connection and cached-reading data.

Activity rows use redacted labels for workspaces and stable IDs for accounts, projects, sessions, and sources. Gauge never reads or returns prompts, responses, tool payloads, raw provider responses, credentials, or local paths.

Budgets and alerts

Gauge budgets are local guardrails. A budget can count:

  • Provider-reported spend
  • Estimated spend
  • Combined reported and estimated spend

Reported and estimated values remain separate in responses. The selected budget basis controls what counts toward the guardrail.

Alerts can notify on limits, spend, and status conditions. Delivery state is managed through Gauge alert APIs and app controls.

Recommendations and capacity

Gauge recommendations answer "can I finish?" for a selected account and duration. Results include confidence and machine-readable reason keys.

Gauge capacity exposes a redacted signal that Smart Route can use when a route pack opts in. The signal includes active account/provider IDs, capacity state, headroom, freshness, confidence, and reasons. It never contains credentials or collector details.

If Gauge data is stale or a source is disconnected, capacity decisions should be treated as advisory and route packs should keep a safe fallback model.

Retention

Usage retention is controlled by usage.retentionDays in settings. Gauge retention is controlled by gauge.retentionDays.

Adjust retention before large rollouts if you need a shorter local history window.

Presets and Routes
Use reusable model defaults, route packs, Smart Route, and local acceleration
Security
Understand the local token, credential, network, diagnostics, and redaction boundaries