Budgets

Budgets cap spend per project and per API key. Alerts fire before a hard stop. When hard_stop is true, the gateway returns HTTP 429 budget_exceeded and does not call GPT or Gemini.

Set a Project Budget

PUT /v1/projects/prj_legal_001/budgets
Authorization: Bearer eridian_sk_...
Content-Type: application/json
Idempotency-Key: budget-legal-001-2026-q3

{
  "monthly_limit_usd": 50000,
  "alert_thresholds": [0.5, 0.8, 0.95],
  "hard_stop": true,
  "period": "calendar_month"
}

Required scope: budgets:manage

Response

{
  "object": "eridian.budget",
  "project_id": "prj_legal_001",
  "monthly_limit_usd": 50000,
  "spent_usd": 18420.11,
  "alert_thresholds": [0.5, 0.8, 0.95],
  "hard_stop": true,
  "period_start": "2026-09-01",
  "period_end": "2026-09-30"
}

Headers on subsequent inference:

Key-Level Ceilings

Pass budget_usd when creating a key. Key spend cannot exceed the project ceiling. The tighter of the two limits wins.

Alerts

Webhook payload:

{
  "id": "evt_budget_80",
  "object": "eridian.webhook.event",
  "type": "budget.threshold",
  "project_id": "prj_legal_001",
  "threshold": 0.8,
  "spent_usd": 40012.40,
  "limit_usd": 50000
}

Retrieve Spend

GET /v1/projects/prj_legal_001/budgets
Authorization: Bearer eridian_sk_...

Break down by model (gpt, gemini), key, template, and metadata.desk via Usage.

Error Codes

See Rate Limits and Webhooks.