Incidents

An incident is a declared event with a start, a lifecycle, and usually an end. It is opened either by a machine, from a rule firing or a monitor check failing, or by a person, by hand.

Proposed, then declared

A machine-originated incident does not start open. It starts proposed, and only becomes investigating (the open lifecycle begins) once something declares it: a human, or the organization's auto_declare setting doing it automatically. SLA clocks do not start until that declaration, because a proposal nobody ever looked at should not carry a response-time penalty against it.

If the condition that proposed the incident clears before anyone declares it, the incident is automatically withdrawn, never resolved. Nobody responded because nothing needed a response, and recording that as a resolved incident would misstate both the timeline and every SLA average computed from it. This is the one fully automatic transition in the whole lifecycle. A withdrawn incident stays closed for a human, but if the same condition fires again shortly after (inside a configured flap window), the same incident reopens rather than a new one being created, so a flapping condition produces one incident that keeps reopening instead of a string of near-duplicates.

An incident created by hand (POST /me/incidents) skips the proposal step entirely and lands directly in the open lifecycle, since a person declaring an incident has nothing to propose.

The open lifecycle

Once declared, an incident moves through investigating, identified, monitoring, and resolved. All the forward and backward moves you'd expect are legal (investigating and identified can both go to monitoring or straight to resolved; a resolved incident can be reopened back to investigating), and an illegal transition is refused naming the allowed values.

Two ways an incident opens

Origin	Triggered by	What decides the unit	Default severity	Default `auto_declare`
`check`	A monitor check failing, or a heartbeat monitor going quiet	The monitor, by default (a service binding can group by service instead)	The org's check incident policy, `critical` by default	On, so a check-originated incident is investigating immediately
`rule`	A rule firing	The alert group	The firing rule's own severity, mapped onto the incident's severity scale	Off, so a rule-originated incident starts proposed

Both origins funnel through the same function, so whichever path observes a given failure first creates the incident and the other is a no-op rather than a duplicate. origin_kind and origin_key on the incident tell you which path opened it and distinguish a check-originated incident (origin_key names the monitor) from a rule-originated one (origin_key names the rule and its alert group) at a glance.

Severity is never a hardcoded constant. A rule-originated incident inherits the firing rule's own severity; a check-originated one takes the org's configured default for checks.

What closes it

Only a human closes an incident, by resolving it. The underlying condition clearing (the monitor recovering, the alert resolving) appends a timeline event and records when the condition cleared, it does not resolve or acknowledge the incident on its own. That is deliberate: collapsing "the condition stopped" into "someone dealt with it" is exactly what an earlier version of this code did, and it is what made postmortem timelines unreliable.

SLA fields

Every incident tracks two clocks against configured targets: time to acknowledge (TTACK) and time to resolve (TTTR), each with its own target in minutes and its own status (on track, breached, or not yet applicable). A live example from this organization, a heartbeat monitor that went quiet:

title:                 1648 example heartbeat is down
status:                investigating
severity:              critical
started_at:            2026-09-16T13:02:01Z
duration_minutes:      25
sla.ttack_threshold_seconds: 900     (15 minutes)
sla.ttack_status:      breached      (nobody has acknowledged it yet)
sla.tttr_threshold_seconds:  3600    (60 minutes)
sla.tttr_status:        pending

That incident was check-originated (GET /api/v1/me/incidents, called with the CLI's bearer token), declared immediately per the org's default check policy, and is still open.

What the console shows today

Incident detail redirects to Home for this account

Opening /incidents/{id} for the incident above redirected straight back to the console's Home page rather than rendering the detail view, for this walk account on this environment. Filed as #1684. It is reported here rather than fixed, since fixing a console route is out of scope for this documentation task.

There is also no /incidents list route in the console by design (#1627): the current console surface reaches an incident's detail page only by following a link from elsewhere (an issue's related-incidents section, for example), not through a dedicated list. A list is not ruled out, it simply has not been built yet.

Incident data is fully readable through the API regardless: GET /api/v1/me/incidents lists incidents for your organization (the example above came from exactly this call), and GET /api/v1/me/incidents/{id} returns one incident with its timeline.