Alert History

Overview

Bifrost records every alert evaluation outcome in alert history. Each record captures the rule that was evaluated, the scope and target, the metric values at evaluation time, the delivery channel (if applicable), and the outcome status. Alert history is stored in the configured logs store. PostgreSQL and ClickHouse logs stores both support history writes, filtering, and recovery of alert state. With ClickHouse, Bifrost creates an enterprise_alert_history table with the configured history_retention_days TTL. Bifrost uses its shared key-value store for live rule cooldown, channel cooldown, and reset-cycle checks. After startup or a leadership change, the alerting engine bulk-loads only the latest relevant sent timestamps and reset-cycle identities from history before it can dispatch alerts. Normal evaluation sweeps do not query alert history for each rule or channel. With ClickHouse, a cold recovery performs an immediate read and a delayed second read before dispatch starts. This allows replicated ClickHouse tables time to converge and reduces duplicate notifications after failover.

Alert history records

Open Alerting in the Bifrost dashboard and select the History tab to review past alert activity. Each history record contains:

Field	Description
Time	When the evaluation was recorded.
Rule	The rule that was evaluated.
Channel	The channel that was notified, or empty for cooldown skips.
Scope	The scope type and ID the rule applied to.
Target	The budget target (`target_type` and `target_id`), if the rule targets one.
Status	Delivery outcome: `sent`, `failed`, or `skipped`.

You can filter history by status, scope type, and channel type.

Statuses

Each history record has one of three statuses:

Status	Meaning
`sent`	The alert was successfully delivered to the channel.
`failed`	Delivery was attempted but failed (for example, network error or unsupported channel type).
`skipped`	The rule matched but delivery was suppressed by a cooldown.

For skipped records, the status_detail field indicates the reason:

"skipped due to rule cooldown" - the rule-level cooldown was active.
"skipped due to channel cooldown" - the channel-level cooldown was active.

For failed records, the status_detail field contains the error (for example, "delivery failed" or "unsupported alert channel type: ...").

Evaluation input

Each history record stores the metric values that were evaluated. For a matched rule, this includes the specific values that caused the expression to evaluate to true. Example for a budget alert:

{
  "budget_usage_percent": 91.2,
  "budget_spent": 456.0,
  "budget_limit": 500.0,
  "request_usage": 0,
  "request_limit": 0,
  "token_usage": 0,
  "token_limit": 0,
  "scope_type": "virtual_key",
  "scope_id": "vk-abc",
  "target_type": "budget",
  "target_id": "budget-a"
}

API

The alert history API is available at /api/alerting/history.

Method	Endpoint	Description
`GET`	`/history`	Paginated history with filters.

Query parameters:

Parameter	Type	Description
`limit`	integer	Maximum records to return. Default `25`.
`offset`	integer	Records to skip for pagination. Default `0`.
`status`	string (comma-separated)	Filter by status: `sent`, `failed`, `skipped`.
`scope_type`	string (comma-separated)	Filter by scope: `virtual_key`, `team`, `customer`.
`channel_type`	string (comma-separated)	Filter by channel: `slack`, `microsoft_teams`, `pagerduty`, `webhook`.

curl "https://your-bifrost-gateway/api/alerting/history?status=sent,failed&scope_type=virtual_key&limit=10" \
  -H "Authorization: Bearer $API_KEY"

Response: The id is numeric with PostgreSQL and a UUID string with ClickHouse.

{
  "history": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "rule_id": "budget-80-percent",
      "rule_name": "Budget at 80%",
      "channel_id": "slack-prod",
      "channel_name": "Production Slack",
      "channel_type": "slack",
      "scope_type": "virtual_key",
      "scope_id": "vk-abc",
      "target_type": "budget",
      "target_id": "budget-a",
      "cel_expression": "budget_usage_percent >= 80.0",
      "status": "sent",
      "status_detail": "",
      "created_at": "2026-06-11T12:00:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Overview

Alert history records

Statuses

Evaluation input

API

Next steps

Alert Rules

Alert Channels

​Overview

​Alert history records

​Statuses

​Evaluation input

​API

​Next steps

Alert Rules

Alert Channels

Overview

Alert history records

Statuses

Evaluation input

API

Next steps