Budget

Tenant spend tracking, budget limits, spend forecasting, agent budgets, and budget alerts.

Endpoints

Method	Path	Auth	Description
GET	/v1/budget/status	API Key	Current spend, limits, and remaining
PUT	/v1/budget/limits	API Key	Update daily/monthly spend limits
GET	/v1/budget/forecast	API Key	Spend forecast with trend analysis and anomalies
GET	/v1/budget/agents	API Key	List agent budgets and spend leaderboard
PUT	/v1/budget/agents/:agentId	API Key	Set agent budget config
GET	/v1/budget/alerts/config	API Key	Get alert threshold configuration
PUT	/v1/budget/alerts/config	API Key	Update alert thresholds and webhook
GET	/v1/budget/alerts/history	API Key	Recent alert history

Dashboard bridge endpoints (JWT auth):

Method	Path	Auth	Description
GET	/auth/budget/status	JWT	Tenant budget status
GET	/auth/budget/forecast	JWT	Tenant budget forecast
GET	/auth/budget/agents	JWT	Agent budgets and leaderboard
PUT	/auth/budget/agents/:agentId	JWT	Set agent budget config
GET	/auth/budget/alerts/config	JWT	Alert configuration
PUT	/auth/budget/alerts/config	JWT	Update alert configuration
GET	/auth/budget/alerts/history	JWT	Alert history

> Note: Dashboard bridge endpoints return tenant-level data only. key_id and key_budget are always null because JWT auth has no API key context. Per-key budget data is only available through the API-key-authenticated /v1/budget/* endpoints.

Get budget status

Returns current spend against limits for the authenticated tenant.

curl "https://api.brainstormrouter.com/v1/budget/status" \
  -H "Authorization: Bearer br_live_..."

Response

{
  "tenant_id": "t_001",
  "key_id": "key_abc",
  "daily": {
    "spent_usd": 12.5,
    "limit_usd": 50.0,
    "remaining_usd": 37.5,
    "period_key": "2026-03-10"
  },
  "monthly": {
    "spent_usd": 120.0,
    "limit_usd": 500.0,
    "remaining_usd": 380.0,
    "period_key": "2026-03"
  },
  "key_budget": {
    "limit_usd": 10.0,
    "period": "daily",
    "spent_usd": 3.2,
    "remaining_usd": 6.8
  }
}

key_budget is null when the API key has no per-key budget configured.

Update budget limits

Set or clear tenant-level daily and monthly spend limits. Pass null to remove a limit.

curl -X PUT "https://api.brainstormrouter.com/v1/budget/limits" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"daily_limit_usd": 50, "monthly_limit_usd": 500}'

Request body

Field	Type	Description
daily_limit_usd	number \	null	Daily spend cap in USD
monthly_limit_usd	number \	null	Monthly spend cap in USD

Response

{
  "ok": true,
  "limits": {
    "dailyLimitUsd": 50,
    "monthlyLimitUsd": 500
  }
}

Get budget forecast

Returns spend forecast powered by BudgetForecaster with 30-day historical data, including trend analysis, anomaly detection, and confidence scoring.

curl "https://api.brainstormrouter.com/v1/budget/forecast" \
  -H "Authorization: Bearer br_live_..."

Response

{
  "tenant_id": "t_001",
  "forecast": {
    "avgDailySpendUsd": 15.2,
    "projectedPeriodSpendUsd": 456.0,
    "depletionDate": "2026-03-25",
    "daysRemaining": 14,
    "trend": "increasing",
    "confidence": 0.85
  },
  "anomalies": [],
  "daysOfData": 12,
  "daily_spent_usd": 18.5,
  "limits": {
    "daily_usd": 50,
    "monthly_usd": 500
  }
}

trend is one of: "increasing", "decreasing", "stable". anomalies lists days with abnormal spend.

Agent budgets

List agent budgets

Returns all configured agent budgets and a spend leaderboard.

curl "https://api.brainstormrouter.com/v1/budget/agents" \
  -H "Authorization: Bearer br_live_..."

Response

{
  "agents": [
    {
      "agentId": "agent-1",
      "config": {
        "perDayUsd": 5,
        "exhaustionAction": "stop"
      },
      "status": {
        "totalSpendUsd": 45.0,
        "activeConversations": 3,
        "downgradeCount": 2,
        "stopCount": 0
      }
    }
  ],
  "leaderboard": [
    {
      "agentId": "agent-1",
      "totalSpendUsd": 45.0,
      "totalRequests": 120,
      "successRate": 0.98,
      "avgCostPerRequest": 0.375,
      "avgLatencyMs": 1200,
      "efficiencyScore": 0.92
    }
  ]
}

Set agent budget

curl -X PUT "https://api.brainstormrouter.com/v1/budget/agents/agent-1" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"perDayUsd": 10, "exhaustionAction": "downgrade"}'

Field	Type	Description
perDayUsd	number	Daily spend cap for the agent
exhaustionAction	string	"stop" or "downgrade" when exhausted

Budget alerts

Alerts fire when projected spend crosses configured threshold percentages. Thresholds are edge-triggered (fire once per crossing) and reset each budget period.

Get alert config

curl "https://api.brainstormrouter.com/v1/budget/alerts/config" \
  -H "Authorization: Bearer br_live_..."

{
  "thresholds": [80, 90, 95],
  "webhookUrl": null,
  "enabled": false
}

Update alert config

curl -X PUT "https://api.brainstormrouter.com/v1/budget/alerts/config" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"thresholds": [70, 85, 95], "webhookUrl": "https://example.com/webhook", "enabled": true}'

Get alert history

curl "https://api.brainstormrouter.com/v1/budget/alerts/history?limit=10" \
  -H "Authorization: Bearer br_live_..."

{
  "alerts": [
    {
      "scope": "global",
      "ratioPercent": 95,
      "threshold": 95,
      "projectedUsd": 47.5,
      "limitUsd": 50.0,
      "tenantId": "t_001",
      "timestamp": "2026-03-11T12:00:00Z"
    }
  ],
  "count": 1
}

Enforcement

When a request would exceed the budget, the middleware returns 402 Payment Required with headers:

Header	Description
X-Budget-Limit	Configured limit in USD
X-Budget-Spent	Current spend in USD
X-Budget-Remaining	Remaining budget in USD

Budget-exempt paths (always allowed): /v1/budget/, /v1/killswitch/, /v1/security/, /v1/usage/, /v1/models, /v1/config, /health.