​

Per-API-key usage budgets and threshold alerts

​

When to use a budget

​

Walkthrough: the Usage budget card element by element

1. Open Settings → API keys in the dashboard and expand a key’s row. The analytic drawer that opens has three columns: Key details on the left, a seven-day usage chart plus top endpoints in the middle, and the key’s scopes on the right.
2. At the bottom of the Key details column, under the created / expires / requests-today / last-used stats, a Usage budget heading opens the card.
3. The card holds one numeric field with a gauge icon and the placeholder “Monthly requests (blank = off)”. Type a ceiling and leave the field — the value commits on blur, in whole requests.
4. Type a zero, negative, or non-numeric value and an inline error appears: “Enter a positive whole number, or leave blank to clear.” The previous value is unchanged until you enter something valid.
5. With a budget set, the card renders three readings and updates them immediately: a badge zone (a caution “Warning threshold reached” badge at 80% of the budget, a red “Budget exceeded” badge at 100%, or the “N of M remaining” headroom text below the warning band), a progress bar filled to the consumed share, and a caption reading “N% of budget used in the last 30 days”.
6. If the 30-day spend data for the key is still loading (or the key’s row fell outside the analytics page’s ranked window), the caption instead reads “Spending data unavailable in this window.” and the bar renders as indeterminate — the badge never fabricates a 0%.
7. To remove the budget, clear the field — blank commits as “off”. The page’s “N keys budgeted” summary pill scans your browser’s stored budgets, so it counts down as soon as you clear.

​

Known limitations

• Browser-local storage. A budget is scoped to the browser profile that set it. It does not follow you to a second browser, a second machine, or a second operator’s session.
• No team visibility. Two operators looking at the same key see only their own threshold — your badge cannot fire in a colleague’s session, and theirs cannot fire in yours. There is no server-side view of “all configured budgets”.
• Advisory only. Crossed tiers flag the key in the dashboard; they never block traffic. Blocking belongs to the rate limit and monthly request quota in Per-API-key usage limits and spend alerts.
• Storage-dependent persistence. Clearing site storage, switching browser profiles, or running the dashboard where storage is denied (private/incognito window, storage-sandboxed iframe) removes or disables every budget you set; the dashboard then treats the key as unbudgeted.
• One denominator. The 30-day request count is the only signal. If you want an alert on delivery rate, outbound volume spikes, or spend in currency, use the threshold rules in Usage anomaly alert rules instead.

​

Failure-mode recipes

​

Worked example: pairing a browser budget with the API-level usage alert

curl -X PUT https://api.orbit.devotel.io/api/v1/developer/governance/org \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "alert_threshold_percent": 80 }'

​

Automate it: reading usage and setting a budget from the API

​

Set a monthly request budget on a key

curl -X PUT https://api.orbit.devotel.io/api/v1/developer/budgets/key_abc123 \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "limit_minor": 50000,
    "currency": "USD",
    "alert_thresholds": [50, 80, 100]
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

interface BudgetRequest {
  limit_minor: number | null;      // positive whole minor units; null clears
  currency?: string | null;        // ISO-4217, e.g. "USD" — required when a limit is set
  period?: "monthly" | null;       // only "monthly" today
  alert_thresholds?: number[] | null; // 1-100%, default [50, 80, 100]
}

const body: BudgetRequest = {
  limit_minor: 50_000,                    // $500.00 USD
  currency: "USD",
  alert_thresholds: [50, 80, 100],
};

const res = await orbit.request<{ data: { api_key_id: string; budget: unknown } }>(
  "PUT",
  "/developer/budgets/key_abc123",
  body,
);
console.log(res.data.budget);

{
  "data": {
    "api_key_id": "key_abc123",
    "budget": {
      "limit_minor": 50000,
      "currency": "USD",
      "period": "monthly",
      "alert_thresholds": [50, 80, 100],
      "last_notified_percent": 0
    }
  },
  "meta": { "request_id": "req_8d41ab" }
}

​

Read the current 30-day usage

curl "https://api.orbit.devotel.io/api/v1/developers/api-analytics/by-key?limit=200" \
  -H "X-API-Key: dv_live_sk_..."

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

interface ByKeyRow {
  api_key_id: string;
  name: string;
  count_today: number;
  count_7d: number;
  count_30d: number;
  error_count_30d: number;
}

const res = await orbit.request<{ data: { rows: ByKeyRow[] } }>(
  "GET",
  "/developers/api-analytics/by-key?limit=200",
);

const row = res.data.rows.find((r) => r.api_key_id === "key_abc123");
console.log(row?.count_30d); // the number the budget badge grades

{
  "data": {
    "window": "30d",
    "sort": "count_30d",
    "total_keys": 12,
    "rows": [
      {
        "api_key_id": "key_abc123",
        "name": "production-backend",
        "key_prefix": "dv_live_sk_prod",
        "last_four_chars": "a1b2",
        "count_today": 412,
        "count_7d": 1488,
        "count_30d": 81234,
        "error_count_30d": 3,
        "cost_month_minor": 61047,
        "last_used_at": "2026-09-28T13:01:22.000Z",
        "last_used_ip": "203.0.113.7",
        "revoked": false
      }
    ]
  },
  "meta": { "request_id": "req_91f2c0" }
}

• Every response returns data plus meta.request_id / meta.timestamp; the data shape above is what a PUT write confirms and what a GET row reports.
• Rows keyed __none__ are unattributed (dashboard session traffic not attached to an API key); __deleted__:<id> are rotated-away keys kept when includeRevoked=true. Ignore them when computing per-key headroom.
• count_30d is always present regardless of the window/sort params; sort only orders the returned rows.
• cost_month_minor is null on the sentinel (unattributed/deleted) rows; never treat it as zero for headroom maths.

​

Browser budget vs API-level usage alert: when each suffices

​

Risk: browser-local storage

• 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.

​

Headroom maths

• 30-day usage: 81234
• usage_percent: 81
• Badge: warning (at least 80% consumed)
• Headroom text: 18,766 of 100,000 remaining

​

What happens at the ceiling

​

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

​

Recommendation