APIAlert Management
Alerts API
Alert instances represent fired alerts — they are distinct from alert rules, which define the conditions that trigger them. When a rule's condition is met, the alert engine creates an Alert instance with the observed metric value and threshold details.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /alerts | List fired alerts. Filterable by status and rule_id. |
| GET | /alerts/{id} | Get a single alert instance with full detail |
| PATCH | /alerts/{id}/acknowledge | Acknowledge the alert — halts escalation progression |
| PATCH | /alerts/{id}/resolve | Mark the alert as resolved — closes the incident if open |
Query Parameters for GET /alerts
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter by status: firing, acknowledged, or resolved |
| rule_id | string | Filter to alerts fired by a specific rule |
| severity | string | Filter by severity: info, warning, or critical |
| limit | integer | Maximum number of results to return (default: 50, max: 500) |
Alert Object
Alert Response Object
{
"id": "alert_8f3a2c1b",
"rule_id": "rule_high_query_time",
"fired_at": "2024-03-01T14:32:00Z",
"resolved_at": null,
"status": "firing",
"severity": "critical",
"metric_value": 847.3,
"threshold_value": 300.0,
"metric_name": "avg_query_duration_seconds",
"message": "Average query duration 847.3s exceeds threshold of 300s"
}Alert Lifecycle
An alert transitions through the following states after it is fired:
| Status | Description | Next Action |
|---|---|---|
| firing | Alert is active. Escalation policy is running. | Acknowledge or resolve |
| acknowledged | Alert has been seen by a team member. Escalation paused. | Resolve when root cause is fixed |
| resolved | Alert is closed. Incident is also closed if one was created. | No further action required |
Alert Rules vs Alert Instances
This API manages alert instances (fired events). To configure the conditions that trigger alerts — including metric selection, thresholds, evaluation windows, and severity — use the Alert Rules section of the Monitoring UI or the alert-rules API endpoints.