> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/data-center/read-alerts.md).

# Read alerts

Alerts are durable lifecycles owned by the token organization. The API is read-only: clients can list and inspect alerts but cannot acknowledge, resolve, or create them.

## List alerts

```bash
curl --fail-with-body --silent --show-error --get \
  "$BUTLR_DC_API_BASE/v1/thermal/alerts" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" \
  --data-urlencode "hall_id=$BUTLR_DC_HALL_ID" \
  --data-urlencode 'status=open' \
  --data-urlencode 'kind=thermal.threshold' \
  --data-urlencode 'limit=50' |
jq '.alerts'
```

All filters are optional. Supported `kind` values are `thermal.threshold` and `sensor.offline`; `severity` accepts `warning` or `critical`, and `status` accepts `open` or `resolved`. `from` and `to` accept Unix milliseconds or RFC 3339 timestamps.

## Read one alert

Set the ID from the list response:

```bash
export BUTLR_DC_ALERT_ID='dc_alert_REPLACE_ME'

curl --fail-with-body --silent --show-error \
  "$BUTLR_DC_API_BASE/v1/thermal/alerts/$BUTLR_DC_ALERT_ID" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" |
jq '{id, hall_id, sensor_key, kind, severity, status, summary, transitions}'
```

## Read alert context

```bash
curl --fail-with-body --silent --show-error \
  "$BUTLR_DC_API_BASE/v1/thermal/alerts/$BUTLR_DC_ALERT_ID/context" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" |
jq '{alert: .alert.id, window, points}'
```

The context response contains the authorized alert, the evaluated time window, and sampled thermal points surrounding the lifecycle.

{% hint style="info" %}
An alert ID owned by a different organization is not exposed. Treat `404` as not available to the current token; do not use it to infer another tenant's resources.
{% endhint %}
