Skip to main content

​
Per-API-key usage budgets and threshold alerts

Every API key’s analytics drawer now carries a “Usage budget” card. Set a monthly request ceiling for that key and Devotel Orbit grades the key’s live 30-day usage against it — a caution badge once consumption crosses 80% of the ceiling, a “budget exceeded” badge once it reaches 100% — with a progress bar and “N of M remaining” headroom text. A runaway integration, or a leaked key, shows as a warning inside the dashboard instead of on the invoice. This works alongside the per-key rate limits and monthly request quotas documented in Per-API-key usage limits and spend alerts: that guide covers the org-wide and per-key hard limits; this one covers the lightweight per-operator dashboard alert you can set on any key without touching the org default.

​
When to use a budget

Use it as an early-warning tripwire inside the dashboard — a budget does not block traffic (the hard quota in the usage-limits guide does that). Set it on keys where you want a badge at a known percentage of expected usage (a staging environment, a partner integration, a single high-volume sender).
Budgets are stored in your browser, not on the API. The threshold you set is held per-browser, per-workspace, and is never sent to the API or shared with your team. Two operators looking at the same key see only their own threshold. For an alert the whole team sees, pair this with the API-level usage-alert threshold from Per-API-key usage limits and spend alerts.

​
Set a per-key budget

In the dashboard, open Settings → API keys and expand a key’s row. In the drawer’s “Usage budget” card:
  1. Type a positive whole monthly request count (for example 100000).
  2. Clear the field to remove the budget.
The value is held in your browser (storage scoped to your workspace) so different operators can carry different thresholds for the same key; nothing is sent to the API. Usage bands update immediately against the 30-day request count the by-key analytics row reports. The dashboard flags the key as warning once its 30-day usage reaches 80% of the budget, and exceeded once it reaches the budget itself, and renders the remaining headroom as “N of M remaining”. Spend data that is still loading shows an indeterminate progress instead of a fabricated 0%.

​
Risk: browser-local storage

Because the budget lives in the browser, three failure modes matter for teams:
  • Threshold drift across the team. Two operators looking at the same key can have — and usually do have — different warning thresholds. Do not assume a colleague sees the same badge you do; they see only the budget set in their own browser.
  • The budget does not survive the browser. Switching browser profiles, clearing site storage, or the dashboard being denied local storage (private/incognito window, storage-sandboxed iframe) wipes or disables the budget; the dashboard then treats the key as unbudgeted.
  • A badge cannot fire for someone else’s session. When another operator’s browser session drives the traffic, your badge stays silent — the threshold in your browser does not travel.
Budgets set in your browser are a useful tripwire for your own checks, but always pair them with the API-level usage-alert threshold from Per-API-key usage limits and spend alerts when alerting must be shared across the team.

​
Headroom maths

The badge tiers are computed from the same 30-day totals the API analytics page shows. Worked example — a key with usage of 81234 against a budget of 100000:
  • 30-day usage: 81234
  • usage_percent: 81
  • Badge: warning (at least 80% consumed)
  • Headroom text: 18,766 of 100,000 remaining
Add 18,767 more requests and the badge flips to exceeded; the percentage is floored, so 79.9% still reports 79 and stays below the warning band.

​
What happens at the ceiling

The badge flips to “Budget exceeded” but traffic is not blocked — clear the budget to silence it, or raise it if the ceiling was genuinely too tight. If you want blocking, set the monthly request quota documented in Per-API-key usage limits and spend alerts.

​
Edge behaviour

  • A blank input clears the budget; a non-positive entry (zero, negative, or non-numeric) is rejected at input time.
  • Fractional budgets round to whole requests (the 30-day count is a whole number, so a fractional ceiling would never map cleanly to a percentage).
  • If browser storage is unavailable (private/incognito mode, a storage-sandboxed iframe), the budget still applies for the page lifetime but will not survive a reload; the dashboard falls back to treating it as unset.
  • A key with no configured budget never emits a warning/exceeded badge — budgets are strictly opt-in.

​
Troubleshooting

Badge never fires. Check each of these three causes in order: the budget is genuinely set in your current browser (a cleared field means no budget); browser storage is available (a private window or storage-denied browser silently discards it on reload); and usage totals have finished loading (a still-loading total never fabricates a badge). Badge fires for one operator only. Expected — thresholds are per-browser. To live-monitor the key for the whole team, use the API-level usage-alert threshold in Per-API-key usage limits and spend alerts. The budget was cleared but the old warning still shows. Rarely this is a storage sync lag — force-reload the page. If it persists, your browser is denying storage access, so the “cleared” budget never persisted in the first place.

​
Recommendation

Use browser budgets as a quick tripwire within your own session. For alerting that the whole team sees, set the org-wide usage-alert threshold. For actual blocking, set a monthly request quota. Both cross-operator controls live in Per-API-key usage limits and spend alerts — pair this guide’s per-browser badges with that guide’s shared thresholds.