Budget Alerting

Budget alerting lets tenants set spending thresholds and receive email notifications when usage approaches or exceeds those thresholds.

Scopes

Budgets can be configured at four levels of granularity:

Scope	Description	Example
Tenant-wide	Total spend across all keys, providers, and dimensions	"Alert when total monthly spend exceeds $5,000"
Per-API key	Spend for a single API key	"Alert when the staging key exceeds $500/month"
Per-dimension value	Spend for a specific dimension value (e.g., team, project)	"Alert when team=backend exceeds $2,000/month"
Per-provider	Spend with a specific upstream provider	"Alert when Anthropic spend exceeds $3,000/month"

Period Types

Period	Behaviour
Calendar month	Resets on the 1st of each month at 00:00 UTC
Fiscal month	Resets on a tenant-configured day of the month

ClickHouse Tables

Budget evaluation queries run against pre-aggregated ClickHouse tables:

• usage_monthly_provider_model — Monthly spend aggregated by tenant, provider, and model. Used for tenant-wide and per-provider budgets.
• usage_monthly_dim_summary — Monthly spend aggregated by tenant and dimension key/value. Used for per-dimension budgets.

Per-API-key budgets query against the base usage table filtered by api_key_id.

Architecture

Azure Function (timer: every 15 min + HTTP trigger)
  → Query ClickHouse for current period spend per budget
  → Compare against thresholds (50%, 75%, 90%, 100%, 110%)
  → Deduplicate: skip if this threshold was already notified for this period
  → Send email via Resend
  → Update last-notified state in SQL

The Azure Function runs on a 15-minute timer to keep alert latency low. It also exposes an HTTP trigger for on-demand evaluation (used after large batch imports or manual budget changes).

Threshold Levels

Each budget has up to 5 alert thresholds:

Level	Meaning
50%	Early warning
75%	Approaching limit
90%	Nearing limit
100%	Budget exceeded
110%	Significant overage

Tenants can customise which thresholds trigger notifications. Each threshold is notified at most once per budget period.

Email Notifications

Notifications are sent via Resend. Each email includes:

• Budget name and scope
• Current spend and budget limit
• Percentage consumed
• Period dates
• Link to the dashboard for further investigation

Recipients are configured per budget and can include multiple email addresses.