Incident Timeline

The incident timeline records every state change and update from initial detection through resolution. Use it to understand what happened, when, and who was involved.

Viewing the timeline

devhelm incidents get <incident-id>

curl https://api.devhelm.io/api/v1/incidents/<incident-id> \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"

The response includes the full incident detail plus an ordered list of timeline updates:

{
  "incident": {
    "id": "a1b2c3d4-...",
    "status": "RESOLVED",
    "severity": "DOWN",
    "source": "MONITORS",
    "startedAt": "2026-04-13T14:23:00Z",
    "confirmedAt": "2026-04-13T14:24:30Z",
    "resolvedAt": "2026-04-13T14:45:00Z"
  },
  "updates": [
    {
      "id": "u1...",
      "oldStatus": null,
      "newStatus": "WATCHING",
      "body": null,
      "createdBy": "SYSTEM",
      "createdAt": "2026-04-13T14:23:00Z"
    },
    {
      "id": "u2...",
      "oldStatus": "WATCHING",
      "newStatus": "CONFIRMED",
      "body": null,
      "createdBy": "SYSTEM",
      "createdAt": "2026-04-13T14:24:30Z"
    },
    {
      "id": "u3...",
      "oldStatus": null,
      "newStatus": null,
      "body": "Investigating — seeing 503s from the upstream API",
      "createdBy": "USER",
      "createdAt": "2026-04-13T14:30:00Z"
    },
    {
      "id": "u4...",
      "oldStatus": "CONFIRMED",
      "newStatus": "RESOLVED",
      "body": "Upstream fixed, all checks passing",
      "createdBy": "USER",
      "createdAt": "2026-04-13T14:45:00Z"
    }
  ]
}

Timeline entry fields

Each entry in the updates array represents a single event:

Field	Type	Description
`id`	UUID	Unique update identifier
`incidentId`	UUID	Parent incident
`oldStatus`	string	Previous status (null for the initial entry or non-status updates)
`newStatus`	string	New status (null for informational updates)
`body`	string	Human-written message or system-generated description
`createdBy`	string	`SYSTEM` for automated transitions, `USER` for manual updates
`notifySubscribers`	boolean	Whether this update triggered notifications
`createdAt`	datetime	When the event occurred

Status transitions

The lifecycle status moves through a defined set of transitions:

From	To	Triggered by
—	`WATCHING`	First check failure detected
`WATCHING`	`TRIGGERED`	Trigger rule threshold met
`TRIGGERED`	`CONFIRMED`	Multi-region confirmation completed
`CONFIRMED`	`RESOLVED`	Recovery policy met or manual resolution
`RESOLVED`	`CONFIRMED`	Reopened — new failures after cooldown expired

Not all transitions appear for every incident. Manual incidents start at CONFIRMED, and some automated incidents may skip WATCHING if confirmation is immediate.

Reopening

When a monitor fails again after an incident was resolved and the cooldown period has expired, the incident reopens:

The status moves from RESOLVED back to CONFIRMED
A new timeline entry records the reopen event
The reopenCount on the incident increments
Escalation chains execute based on the policy’s onReopen setting

The cooldown period (configured in the recovery policy) prevents rapid cycling between resolved and confirmed states. During cooldown, new failures do not reopen the incident.

Adding manual updates

Post updates to add context for your team without changing the incident status. Timeline updates are posted via the API:

API

curl -X POST https://api.devhelm.io/api/v1/incidents/<incident-id>/updates \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Root cause identified — DNS propagation delay",
    "notifySubscribers": true
  }'

Set notifySubscribers to true to send the update through the incident’s matched notification policies.

Next steps

Incidents overview

Understand statuses, severities, and the full lifecycle.

Incident policies

Configure trigger rules and recovery behavior that drive timeline events.

Escalation chains

Control notification flow and acknowledgment for incident updates.

Getting Started

Monitoring as Code

Monitoring

Incidents

Alerting

Status Data

Platform

Common Patterns

Incident Timeline

Viewing the timeline

Timeline entry fields

Status transitions

Reopening

Adding manual updates

Next steps

Incidents overview

Incident policies

Escalation chains

​Viewing the timeline

​Timeline entry fields

​Status transitions

​Reopening

​Adding manual updates

​Next steps

Incidents overview

Incident policies

Escalation chains

Viewing the timeline

Timeline entry fields

Status transitions

Reopening

Adding manual updates

Next steps