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

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:

{ "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.