APIAlert Management
Alert Incidents API
Incidents are created automatically by the alert escalation engine when a fired alert is not acknowledged within the configured timeout at the first escalation level. Each incident tracks the escalation progression and who is currently responsible for responding.
Auto-Created Only
Incidents cannot be manually created via the API. They are created exclusively by the alert escalation engine when a
firing alert progresses through an escalation policy.Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /incidents | List all incidents, optionally filtered by status or alert_id |
| GET | /incidents/{id} | Get full incident detail including escalation history |
| PATCH | /incidents/{id}/acknowledge | Acknowledge the incident — stops further escalation |
Incident Object
Incident Response Object
{
"id": "inc_7a4b2e9f",
"alert_id": "alert_8f3a2c1b",
"escalation_policy_id": "pol_critical_ops",
"current_level": 2,
"escalated_at": "2024-03-01T14:47:00Z",
"assigned_to": "550e8400-e29b-41d4-a716-446655440000",
"status": "escalating",
"acknowledged_at": null,
"resolved_at": null
}Incident Fields Reference
| Field | Type | Description |
|---|---|---|
| id | string | Unique incident identifier |
| alert_id | string | The alert instance that triggered this incident |
| escalation_policy_id | string | The escalation policy governing notification progression |
| current_level | integer (1–N) | The escalation level currently active. Advances if no acknowledgment before the level's timeout. |
| escalated_at | string (ISO 8601) | Timestamp when the incident was escalated to the current level |
| assigned_to | string (user_id) | The user currently assigned to this incident at the current escalation level (from on-call schedule) |
| status | string | One of: escalating, acknowledged, resolved |
Escalation Progression
The escalation engine advances the incident's current_level if no acknowledgment is received within the configured delay_minutes for that level. When the maximum level is reached and still unacknowledged, the incident remains at the final level and continues notifying the assigned channel.
Example Escalation Timeline
T+00:00 Alert fires → Incident created at Level 1
→ Slack notification sent to #ops-alerts
T+15:00 No acknowledgment → Escalate to Level 2
→ PagerDuty + email sent to on-call engineer
T+45:00 No acknowledgment → Escalate to Level 3
→ Phone call to on-call manager
T+60:00 Acknowledged by on-call manager → Escalation stops