# View an alarm's history

See every state change of an alarm, why it happened, and what was sent to its recipients.

Replace _alarm-id_ with the alarm's id.

## Prerequisites

- Permission for `monitoring:DescribeAlarmHistory` on the alarm,
  `rn:ews::<organization id>:monitoring:alarm/<alarm id>`. Without it, the API answers `404`
  "Alarm not found" and the console's **History** is unavailable, with the note "Needs
  monitoring:DescribeAlarmHistory on this alarm."
- In the console, also `monitoring:DescribeAlarms` to open **Alarms**.

## Read the history

**Console**
1. Open **Monitoring**, then **Alarms**.
2. Open the alarm's action menu and choose **History**.

Each entry shows the state before and after, when, the reason, and what was sent. An alarm that has
not changed state yet says "No state changes yet. The alarm is evaluated every minute."

To see the current state and its reason without the history, choose the alarm's row: the side
panel shows **State**, **Why**, **Condition** and **Notifies**.

**CLI**
```sh
dcloud monitoring alarms history alarm-id --limit 20
```

**API**
```http
GET /monitoring/api/alarms/alarm-id/history?limit=20
```

## Result

Up to `limit` state changes (100 by default, at most 500), newest first. Each has `fromState`,
`toState`, `reason` and `notification`: what was sent, for example "emailed 2; webhook 204",
"webhook failed: HTTP 500", "No recipients configured." or "Notifications are switched off for
this alarm.". A change between `OK` and `INSUFFICIENT_DATA` sends nothing and has no notification.

The history is deleted with the alarm.

## Related

- [How alarms work](how-alarms-work.md)
- [Notification webhooks](notification-webhooks.md)
- `monitoring.alarms.history` · `dcloud monitoring alarms history`
