> 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-raw-frames.md).

# Read raw thermal frames

```http
GET /v1/sensors/{key}/frames?from={unix_ms}&to={unix_ms}&limit={count}&compensate=0
```

`key` is a current sensor `mac` or `serial` discovered with GraphQL.

## Parameters

| Parameter     | Required | Description                                                                                                 |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `from`        | Yes      | Inclusive window start, Unix milliseconds.                                                                  |
| `to`          | Yes      | Window end, Unix milliseconds; must be greater than or equal to `from`.                                     |
| `limit`       | No       | Sampled frame limit. Default `2000`, maximum `5000`; `0` requests all frames within server bounds.          |
| `hallId`      | No       | Hall context for hall-specific compensation. It cannot bypass sensor ownership.                             |
| `compensate`  | No       | Set to `0` or `false` to guarantee raw device matrices. Otherwise server-side angle compensation may apply. |
| `include_raw` | No       | With compensation active, set to `1` or `true` to include the original matrix as `raw_data`.                |

The server selects a fine or coarse archive tier from the requested span. An unarchived window returns `200` with no frames and a non-zero `missing` count. A storage or decode failure returns `502` instead of silently falling back to a different data source.

## Response fields

```json
{
  "key": "00-00-00-00-00-00",
  "kind": "wireless",
  "tier": "fine",
  "from": 1793058000000,
  "to": 1793058300000,
  "count": 1,
  "total": 1,
  "sampled": false,
  "objects": 1,
  "missing": 0,
  "compensated": false,
  "pivot_fallback_frames": 0,
  "frames": [
    {
      "timestamp": 1793058299000,
      "min_c": 21.4,
      "max_c": 31.8,
      "data": [[2945, 2947]]
    }
  ]
}
```

The short matrix is illustrative. Matrix dimensions depend on the sensor model: Heatic 2+ produces 8 rows by 8 columns, while Heatic 3 produces 40 rows by 60 columns. Clients must inspect the returned array dimensions instead of assuming one fixed shape. With `compensate=0`, `data` is the row-major raw `uint16` deciKelvin field; convert one value `v` to Celsius with `v / 10 - 273.15`. A value of `0` represents a dead pixel.

When `compensate` is omitted, the server attempts angle compensation only when compatible hall geometry is configured. Always inspect top-level `compensated`. When it is `true`, `data` is angle-corrected; request `include_raw=1` to receive the original field as `raw_data` in the same response. When it is `false`, `data` remains raw and `raw_data` is omitted even if `include_raw=1` was sent.

`min_c` and `max_c` are already Celsius. `sampled` is true when `total` exceeds `count`. `objects` is the number of archive objects read; `missing` is the number of expected segment objects not found, not the number of missing pixels.

{% hint style="info" %}
This endpoint reads the archive and does not promise sub-second live delivery. Poll deliberately and use frame timestamps to calculate freshness.
{% endhint %}
