> 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-thermal-analytics.md).

# Read thermal analytics

Thermal analytics accept an entity selector and a Unix-millisecond time window. The token organization is derived by the server and cannot be selected by the request.

## Entity selectors

| Type        | `id`                         | Additional field                          |
| ----------- | ---------------------------- | ----------------------------------------- |
| `sensor`    | Wireless MAC or wired serial | None                                      |
| `hall`      | Data hall ID                 | None                                      |
| `pod`       | Pod ID                       | `hall_id` is required                     |
| `rack`      | Rack ID                      | None                                      |
| `rack_face` | Rack ID                      | `face` is required: `intake` or `exhaust` |

## Read statistics

This example reads sampled raw and compensated temperature series for a hall.

```bash
export BUTLR_DC_TO_MS="$(( $(date +%s) * 1000 ))"
export BUTLR_DC_FROM_MS="$(( BUTLR_DC_TO_MS - 3600000 ))"

jq -n \
  --arg hall "$BUTLR_DC_HALL_ID" \
  --argjson from "$BUTLR_DC_FROM_MS" \
  --argjson to "$BUTLR_DC_TO_MS" \
  '{
    entity: {type: "hall", id: $hall},
    from: $from,
    to: $to,
    measurement: "sensor_temperature",
    metrics: ["temperature", "health"],
    fields: ["compensated", "raw"],
    samples: 48,
    analysis: {warning_c: 45, critical_c: 55, stale_after_ms: 900000}
  }' |
curl --fail-with-body --silent --show-error \
  "$BUTLR_DC_API_BASE/v1/thermal/stats" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @- |
jq '{measurement, from, to, entity, series, insights}'
```

Each series reports its source sensor, archive tier, points, summary, archive coverage, and whether compensation was actually applied. A requested `compensated` field can still return `compensated: false` when compatible geometry is unavailable; clients must not infer correction from the requested field name alone.

## Read derived events

```bash
jq -n \
  --arg hall "$BUTLR_DC_HALL_ID" \
  --argjson from "$BUTLR_DC_FROM_MS" \
  --argjson to "$BUTLR_DC_TO_MS" \
  '{
    entity: {type: "hall", id: $hall},
    from: $from,
    to: $to,
    fields: ["compensated"],
    samples: 48,
    event_limit: 25
  }' |
curl --fail-with-body --silent --show-error \
  "$BUTLR_DC_API_BASE/v1/thermal/events" \
  --header "Authorization: Bearer $BUTLR_DC_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @- |
jq '{from, to, events, next_cursor}'
```

Events are threshold excursions and step changes derived from the requested entity window. A successful response may contain `"events": []`; an empty array means no qualifying event was found, not that the request failed.

{% hint style="info" %}
Use `next_cursor` as `event_cursor` in the next request when it is non-null. Do not decode or construct cursors in the client.
{% endhint %}
