> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Incident Timeline

> Track incident events, status changes, and resolution history in the DevHelm 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

<CodeGroup>
  ```bash CLI theme={null}
  devhelm incidents get <incident-id>
  ```

  ```bash API theme={null}
  curl https://api.devhelm.io/api/v1/incidents/<incident-id> \
    -H "Authorization: Bearer $DEVHELM_API_TOKEN"
  ```
</CodeGroup>

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

```json theme={null}
{
  "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:

1. The status moves from `RESOLVED` back to `CONFIRMED`
2. A new timeline entry records the reopen event
3. The `reopenCount` on the incident increments
4. [Escalation chains](/alerting/escalation-chains#reopen-behavior) execute based on the policy's `onReopen` setting

The cooldown period (configured in the [recovery policy](/incidents/policies#recovery)) 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:

```bash API theme={null}
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

<CardGroup cols={2}>
  <Card title="Incidents overview" icon="circle-exclamation" href="/incidents/overview">
    Understand statuses, severities, and the full lifecycle.
  </Card>

  <Card title="Incident policies" icon="sliders" href="/incidents/policies">
    Configure trigger rules and recovery behavior that drive timeline events.
  </Card>

  <Card title="Escalation chains" icon="arrow-up-right-dots" href="/alerting/escalation-chains">
    Control notification flow and acknowledgment for incident updates.
  </Card>
</CardGroup>