Skip to content
Brutor AI Docs

Usage Alerts

Usage alerts are the early-warning side of budgets, quotas & rate limits. When a resource group’s consumption crosses a warning threshold — or a limit actually stops traffic — Brutor raises an alert that operators and portal users can see and acknowledge.

Where alerts come from

Section titled “Where alerts come from”

Alerts are generated from the thresholds you configure on the group’s limit documents. Each family (budget, tokens, requests, MCP frequency) carries daily_warning_percent / monthly_warning_percent fields; hard limits raise their own alerts when they trip:

alert_type Raised when
warning Utilization crosses a configured *_warning_percent threshold
hard_stop A blocking limit trips — token/request quota exhausted, throughput cooldown, or a $-budget with hard_stop: true
resumed Traffic is flowing again after a hard stop (window rolled over or limit raised)

Each alert records the metric it fired on (e.g. daily_tokens, monthly_budget, daily_requests, daily_mcp_calls), the period (daily / monthly), the configured threshold_pct, and the actual utilization_pct at firing time. Alert lifecycle status is active → acknowledged → resolved.

Configuring thresholds

Section titled “Configuring thresholds”

Set the warning percentages where the limits live — the group’s LLM Limits tab or the llm-global-limits PATCH:

Terminal window
curl -X PATCH http://localhost:5050/v1/admin/resource-groups/{group_id}/llm-global-limits \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "llm_global_limits": {
      "budget": { "monthly_limit_usd": 1000.0, "monthly_warning_percent": 80, "hard_stop": false },
      "tokens": { "daily_limit": 2000000, "daily_warning_percent": 90 }
    }
  }'

The group’s Usage Alerts tab shows everything the group has raised:

Usage alerts on a resource group

Where alerts surface

Section titled “Where alerts surface”

Mission Control → Alerts

Section titled “Mission Control → Alerts”

The alerts bell on the Mission Control dashboard aggregates active usage alerts across all groups, alongside system alerts, metric-threshold alerts (error rate / latency, from GET /v1/admin/metrics/alerts) and open drift findings — with acknowledge and resolve actions in the drawer:

The Mission Control alerts drawer

Admin API access per group: GET /v1/admin/resource-groups/{group_id}/usage-alerts, acknowledge with POST /v1/admin/resource-groups/usage-alerts/{alert_id}/acknowledge.

Portal API (Core Proxy)

Section titled “Portal API (Core Proxy)”

End users and agents see the same alerts through the runtime plane — useful for building “your team is at 80% of budget” banners into custom portals:

Endpoint Purpose
GET /v1/portal/alerts Tenant-wide list. Filters: status (active/acknowledged/resolved), alert_type (warning/hard_stop), resource_type, group_id, limit (default 100, max 500)
GET /v1/portal/alerts/group/{group_id} One group’s alerts (default 50, max 200)
POST /v1/portal/alerts/{alert_id}/acknowledge Mark an alert acknowledged
Terminal window
curl "http://localhost:8100/v1/portal/alerts?status=active&alert_type=warning" \
  -H "Authorization: Bearer $PORTAL_JWT"
{
  "tenant_id": "default",
  "alerts": [
    {
      "id": "ua-...",
      "alert_type": "warning",
      "metric": "monthly_budget",
      "period": "monthly",
      "threshold_pct": 80,
      "utilization_pct": 83.4,
      "status": "active"
    }
  ],
  "total_count": 1,
  "active_count": 1,
  "hard_stop_count": 0,
  "groups_affected": 1
}

Acknowledge flow

Section titled “Acknowledge flow”

Acknowledging records who and when, and moves the alert out of the default “active” view — it does not change any limit or resume any traffic:

Terminal window
curl -X POST http://localhost:8100/v1/portal/alerts/ua-.../acknowledge \
  -H "Authorization: Bearer $PORTAL_JWT"
{
  "id": "ua-...",
  "status": "acknowledged",
  "acknowledged_by": "42",
  "acknowledged_at": "2026-07-02T14:31:09Z",
  "message": "Alert acknowledged"
}

An alert resolves when the underlying condition clears (window rollover, limit raised) — hard-stop alerts pair with a resumed alert so the timeline shows both edges.

Assurance alerts — Slack and webhooks

Section titled “Assurance alerts — Slack and webhooks”

Real-time notifications for Assurance Inbox findings are configured under Settings → Notifications:

  1. Channels — a Slack incoming webhook or a generic webhook (optionally HMAC-SHA256 signed: X-Brutor-Signature: sha256=<hex> over the exact request body). Webhook URLs and secrets are stored encrypted with the platform ENCRYPTION_KEY and only ever shown as masked summaries.
  2. Subscriptions — route new or re-occurring inbox items — or the weekly digest (digest_weekly) — to a channel, filtered by a severity floor, categories, or a single AI System, with a per-fingerprint coalescing window (default 15 minutes): a recurring finding is one message per window, and the occurrence counter on the inbox item stays the precise record.
  3. Deliveries — every decision is recorded (sent / failed / coalesced), failures retry with exponential backoff, and a channel that fails five deliveries in a row is raised as an assurance-inbox finding itself — a dead alert channel must never fail silently.

Alerts are a projection of the inbox: the dispatcher tails the inbox’s own event trail, so a Slack message can never disagree with what Mission Control shows.

System alerts are separate

Section titled “System alerts are separate”

Infrastructure/health alerts (provider outages, circuit breakers, DB issues) are a different stream with severity levels critical / high / medium / low, listed at GET /v1/admin/system-alerts and counted in the Prometheus metrics (proxy_system_alerts_raised_total). Usage alerts tell you about spending; system alerts tell you about breakage.

Section titled “Related pages”