​

Per-API-key spend budgets

• It is a spend ceiling (money), not a request-count budget. The per-key request quota and per-minute rate limit in Per-API-key usage limits and spend alerts block by request volume; a spend budget caps the billable amount a key may accumulate in a UTC month.
• It is persisted on the API and shared with your team, not held in your browser. The dashboard badge described in Per-API-key usage budgets and threshold alerts is a per-browser tripwire; the budgets you set here are stored in your organization and read back identically for every operator.

​

How budgets are stored

​

Read the budget surface

curl https://api.orbit.devotel.io/api/v1/developer/budgets \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "keys": [
      {
        "api_key_id": "key_abc123",
        "name": "production-backend",
        "key_prefix": "dv_live_sk_prod",
        "last_four": "a1b2",
        "active": true,
        "budget": {
          "limit_minor": 50000,
          "currency": "USD",
          "period": "monthly",
          "alert_thresholds": [50, 80, 100],
          "last_notified_percent": 50
        },
        "usage": {
          "requests_this_minute": 41,
          "requests_this_month": 812345
        }
      }
    ],
    "keys_truncated": false,
    "defaults": {
      "alert_thresholds": [50, 80, 100],
      "max_alert_thresholds": 10
    }
  }
}

• budget is null for a key with no spend ceiling (unlimited); usage is still reported for unbudgeted keys.
• last_notified_percent is the alert high-water mark — the highest threshold percent already notified for this key in the current month. See the alert semantics below.
• usage.requests_this_minute is the key’s live in-flight count for the current minute window; usage.requests_this_month is the count for the current UTC month — the same live metering peek the rate-limit surface uses.
• The read hydrates at most 250 keys; keys_truncated: true tells you the list was cut.
• defaults.alert_thresholds is the threshold set that applies when you do not pass one; defaults.max_alert_thresholds caps how many thresholds a single key may carry.

​

Set or clear a budget

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]
  }'

• limit_minor — positive integer ceiling in minor currency units (50000 = $500.00 when the currency is USD). A zero, negative, or fractional value is rejected with a 422; to remove the ceiling send null instead of zero.
• currency — 3-letter ISO-4217 code, required whenever a limit_minor is set. It is upper-cased on save, so usd reads back as USD.
• period — only "monthly" is supported today; the ceiling resets on the 1st of each UTC month. Any other value is a 422.
• alert_thresholds — ascending integer percentages in (0, 100]. Duplicates are dropped and the list is sorted ascending. Omit it to use the default [50, 80, 100]; send null to restore the default. At most 10 thresholds per 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": null }'

​

Alert semantics

• The first time the month’s usage crosses a threshold, that threshold fires and the mark advances to it.
• A threshold at or below the mark never re-fires within the same month, even if spend dips back under it and crosses again.
• The mark persists across edits to the budget’s amount or currency, so a simple edit does not re-fire thresholds you have already acknowledged this month.
• Clearing the budget (limit_minor: null) removes the entry entirely; setting a fresh budget afterwards starts a new mark, so alerts re-arm.

• Spend reaches 25,000 minor units (25000 / 50000 = 50%) → usage_percent is 50, the 50% threshold fires, last_notified_percent becomes 50.
• Spend reaches 40,000 (80%) → the 80% threshold fires, the mark advances to 80.
• Spend reaches the ceiling 50,000 (100%) → the 100% threshold fires; the key is at its cap.
• Usage percentage is floored — spend of 39,999 is 79.998% but reports 79%, so it does not prematurely trip the 80% threshold.

​

Roles and audit

​

How it relates to the other budget guides

• Spend budget (this guide): a money ceiling per key per month, persisted on the organization, with alert-once-per-threshold notifications. Use it to bound what a key can spend and to alert the team.
• Request-count budget (usage budgets and threshold alerts): a per-browser dashboard badge that flags a key at a request threshold. Its Warning that “budgets are stored in your browser, not on the API” applies to that badge only — the spend budgets above ARE persisted on the API and shared with your team, which is exactly what that guide recommends pairing with.
• Request quotas and rate limits (usage limits and spend alerts): hard per-minute and per-month request caps that return 429 when exceeded. Use those for blocking by request volume; use a spend budget for bounding by money.

​

Edge behaviour

• A key with no configured budget never appears as over-limit; budgets are strictly opt-in.
• A malformed value is rejected at write time with a 422, never persisted — so a bad hand-edit cannot fabricate a tiny cap that blocks the key, and can never throw on the read path.
• At most 10 thresholds per key; duplicates and out-of-range values are rejected or de-duplicated at write time.
• Clearing the ceiling is a null, not a 0 — a zero is rejected because it would hard-block the key, which is never the intent (to disable a key, revoke it).