---
category: Reference
title: Incident Reference
description: Technical specification for incident management and lifecycle
---

An incident in openstatus represents a detected problem or service disruption related to a monitored resource. Incidents are automatically generated when a monitor reports a failure condition that meets predefined criteria. They serve as a central point for tracking, managing, and resolving service impairments.

**Key characteristics:**

- Automatically triggered by monitor failures.
- Aggregates related failure events for a single monitor.
- Provides a clear status of service health.

## Incident triggering

An incident is triggered when enough of a monitor's regions agree that the endpoint is down. Requiring agreement across regions prevents a single flaky probe from opening an incident.

**Trigger condition:**

- **Failure threshold** — an incident is opened when at least half of the monitor's configured regions report an `error` status. A single-region monitor triggers on its one region.
- Only `error` opens an incident. A `degraded` status triggers notifications but does not create an incident.
- If an incident is already open for the monitor, no second incident is created.

## Incident lifecycle and states

An incident's lifecycle is tracked with timestamps rather than a manual workflow:

- **Open** — created when the failure threshold is met. `resolvedAt` is null.
- **Acknowledged** — a team member has taken ownership. `acknowledgedAt` and `acknowledgedBy` are set.
- **Resolved** — either auto-resolved (`autoResolved: true`) or manually resolved, setting `resolvedAt` and `resolvedBy`.

Auto-resolution fires when the monitor leaves the `error` state by the same region-agreement rule
that opened the incident. That includes a transition to `degraded`, not only to `active`: a monitor
that improves from down to slow closes its open incident. The notification that goes out matches the
new state — a recovery alert for `active`, a degraded alert for `degraded`.

The stored `status` field accepts `triage` (the default), `investigating`, `identified`, `monitoring`, `resolved`, and `duplicated`.

Incidents are distinct from status reports. Status reports are the manual, public communication channel on your status page and are not linked to an incident record — see the [Status report reference](/docs/reference/status-report).

## Properties

While an incident is active, it collects and displays key information related to the service disruption.

- **Monitor association** — each incident is directly linked to the monitor that triggered it, providing immediate context to the affected service.
- **Start time** — timestamp indicating when the incident was first detected and created.
- **Title and summary** — free-text fields describing the incident.
- **Acknowledgement** — who acknowledged the incident and when.
- **Resolution** — who resolved it and when, plus whether it was auto-resolved.
- **Screenshots** — captured at failure and at recovery, on plans where screenshots are enabled.

## Related resources

- **[Status report reference](/docs/reference/status-report)** — how to communicate an incident publicly on your status page.