> 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/integrations-api-third-party-sensors/reporting-api/temperature.md).

# Temperature

Temperature from third-party temperature sensors, per sensor, room, or floor.

| Measurement         | Data keyed by | One series per                                                                                   |
| ------------------- | ------------- | ------------------------------------------------------------------------------------------------ |
| `dt_temperature`    | `device_id`   | Temperature sensor. Also carries `spot_id`, `room_id`, and floor IDs, so you can filter by them. |
| `room_temperature`  | `room_id`     | Room, aggregated across all temperature sensors in the room                                      |
| `floor_temperature` | `floor_id`    | Floor, aggregated across all temperature sensors on the floor                                    |

**Intervals:** `5m`, `15m`, `30m`, `1h`, `1d` (no `1m`). **Max range:** 180 days, and less at `5m`; see [Query Limits](/integrations-api-third-party-sensors/reporting-api/query-limits.md).

## Fields

| Field              | Description                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `celsius_min`      | Lowest reading in the window (°C)                                                                                         |
| `celsius_max`      | Highest reading in the window (°C)                                                                                        |
| `celsius_mean`     | Mean of all readings in the window (°C), computed from the readings themselves rather than averaged from sub-window means |
| `celsius_last`     | Most recent reading in the window (°C)                                                                                    |
| `sample_count`     | Number of readings behind the values                                                                                      |
| `backfilled_count` | How many of those readings were recorded while the sensor was offline and delivered later                                 |
| `device_count`     | `room_temperature` / `floor_temperature` only: number of sensors that contributed                                         |

Each point also carries [location metadata](/integrations-api-third-party-sensors/reporting-api/items-and-fields.md#location-metadata).

## Notes

* **Units:** values are always Celsius.
* **Start date:** temperature data starts on **2026-09-09**. Earlier windows are valid requests but return no data.
* **Readings per window:** sensors report every 5 minutes by default, so a `5m` window from `dt_temperature` usually contains one reading (`min` = `max` = `mean` = `last`).
* **Late readings:** readings that arrive more than about 24 hours late are not included in these windows.
* **Single sensor:** a room or floor with `device_count: 1` reflects one sensor. Check it before treating the value as representative.

## Example: room temperature every 5 minutes

```bash
curl -X POST https://api-integrations.butlr.io/api/v1/reporting \
  -H "Authorization: Bearer [insert access_token here]" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": ["room_temperature"],
    "items": ["room_XXXX"],
    "start": "2026-09-15T12:00:00Z",
    "stop": "2026-09-15T16:00:00Z",
    "interval": "5m",
    "fields": ["celsius_mean", "device_count"]
  }'
```

## Example: each sensor in a room

`dt_temperature` is keyed by the sensor's device ID, and you can filter it by room:

```bash
curl -X POST https://api-integrations.butlr.io/api/v1/reporting \
  -H "Authorization: Bearer [insert access_token here]" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": ["dt_temperature"],
    "items": ["room_XXXX"],
    "start": "2026-09-15",
    "stop": "2026-09-16",
    "timezone": "America/Chicago",
    "interval": "1h",
    "fields": ["spot_id", "celsius_min", "celsius_max", "celsius_mean"]
  }'
```