> 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/items-and-fields.md).

# Items & Fields

## Items

`items` chooses which entities to return data for. Each item is an ID, and its prefix decides what it matches:

| Prefix      | Matches data from  |
| ----------- | ------------------ |
| `site_`     | The whole site     |
| `building_` | The whole building |
| `space_`    | The whole floor    |
| `room_`     | The room           |
| `spot_`     | The spot           |

* **Combining items:** multiple items are combined with **OR**. `["room_XXXX", "space_YYYY"]` returns data for room `XXXX` plus everything on floor `YYYY`.
* **Excluding items:** `exclude_items` removes matches, for example a whole floor minus one room.
* **Allowed characters:** IDs may contain only letters, digits, `_`, and `-`.
* **Limits:** up to 500 `items` and 500 `exclude_items`.

### Use a prefix at or above the measurement's level

A room measurement can be filtered by `room_`, `space_`, `building_`, or `site_`, but not by `spot_`. This is **not validated**: a lower-level prefix is accepted and then returns no data, or fails with `-5300`.

| Measurement level                                                 | Allowed item prefixes                        |
| ----------------------------------------------------------------- | -------------------------------------------- |
| Spot (`spot_*`), per-sensor (`dt_temperature`, `dt_heartbeat`)    | `spot_` `room_` `space_` `building_` `site_` |
| Room (`room_*`), events (`touch_events`, `cleaning_alert_events`) | `room_` `space_` `building_` `site_`         |
| Floor (`floor_*`)                                                 | `space_` `building_` `site_`                 |

All items apply to every measurement in the request, so only mix item levels when every measurement is at or below the lowest one (for example `spot_` items with spot-level measurements only).

Zones are not supported.

### Example: every desk on a floor, minus two

```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": ["spot_desk_occupancy"],
    "items": ["space_XXXX"],
    "exclude_items": ["spot_AAAA", "spot_BBBB"],
    "start": "2026-09-14",
    "stop": "2026-09-21",
    "timezone": "Europe/London",
    "interval": "1d",
    "fields": ["occupancy_mean", "presence_time_secs_sum"]
  }'
```

Returns one array per desk, keyed by `spot_id`, with one point per day.

## Fields

By default each data point contains every available field. Use `fields` (up to 50 names) to get a smaller, fixed shape:

```json
{ "fields": ["occupancy_mean", "total_spots"] }
```

* `start` and `stop` are always included.
* Omitted or empty (`[]`) returns every field.
* Names are not validated. A name that does not exist for the measurement is simply absent from the response.
* The entity's own ID (e.g. `room_id`) is returned only if you list it. It is always available as the key in `data`.
* At `1m`, list `presence_time_secs` rather than `presence_time_secs_sum`. The `_sum` alias is only added when `presence_time_secs` is itself returned.

### Location metadata

Besides its measurement fields, each point carries location metadata down to the measurement's level:

| Level | Measurements                                      | Metadata fields                                                                                     |
| ----- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Floor | `floor_*`                                         | `site_id`, `site_name`, `building_id`, `building_name`, `floor_id`, `floor_name`, `floor_custom_id` |
| Room  | `room_*`, `touch_events`, `cleaning_alert_events` | Floor fields, plus `room_id`, `room_name`, `room_custom_id`                                         |
| Spot  | `spot_*`, `dt_temperature`, `dt_heartbeat`        | Room fields, plus `spot_id`, `spot_name`, `spot_custom_id`                                          |

The measurement fields are listed on each measurement's page.