> 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/occupancy.md).

# Occupancy

Occupancy from desk and motion sensors, at spot, room, or floor level.

| Measurement              | Data keyed by | Sensor         |
| ------------------------ | ------------- | -------------- |
| `spot_desk_occupancy`    | `spot_id`     | Desk occupancy |
| `room_desk_occupancy`    | `room_id`     | Desk occupancy |
| `floor_desk_occupancy`   | `floor_id`    | Desk occupancy |
| `spot_motion_occupancy`  | `spot_id`     | Motion         |
| `room_motion_occupancy`  | `room_id`     | Motion         |
| `floor_motion_occupancy` | `floor_id`    | Motion         |

**Intervals:** `1m`, `15m`, `30m`, `1h`, `1d`. **Max range:** set by the interval; see [Query Limits](/integrations-api-third-party-sensors/reporting-api/query-limits.md).

## What `occupancy` counts

It depends on the sensor type and level:

| Measurement                                    | `occupancy` in each minute                                | `presence_time_secs` in each minute       |
| ---------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- |
| `spot_desk_occupancy`, `spot_motion_occupancy` | `1` if the spot's sensor detected presence, else `0`      | Seconds of presence (0–60)                |
| `room_desk_occupancy`, `floor_desk_occupancy`  | **Number of occupied desk sensors** in the room/floor     | Sum across the desk sensors               |
| `room_motion_occupancy`                        | `1` if any motion sensor in the room was active, else `0` | Maximum across the room's motion sensors  |
| `floor_motion_occupancy`                       | **Number of rooms** on the floor with motion              | Maximum across the floor's motion sensors |

{% hint style="info" %}
`occupancy_mean` is a 0–1 fraction only for spot measurements and `room_motion_occupancy`. For `room_desk_occupancy` and `floor_desk_occupancy` it is the average number of occupied desks; compare it with `total_spots` to get utilization. For `floor_motion_occupancy` it is the average number of rooms with motion.
{% endhint %}

Spot measurements include only sensors attached to a spot, and room measurements only sensors inside a room. See [Spots & Sensor Placement](/integrations-api-third-party-sensors/spots.md).

## Fields at `1m`

| Field                    | Description                                                                                                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `occupancy`              | The per-minute value described above                                                                                                                                              |
| `presence_time_secs`     | The per-minute value described above                                                                                                                                              |
| `presence_time_secs_sum` | Copy of `presence_time_secs`, so the same field name works at every interval. Only added when `presence_time_secs` is returned: with `fields`, list `presence_time_secs` at `1m`. |
| `total_spots`            | Desk measurements at room/floor level only: number of desk sensors counted                                                                                                        |

## Fields at `15m`, `30m`, `1h`, `1d`

Statistics over the per-minute values in the window:

| Field                    | Description                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `occupancy_min`          | Lowest per-minute value                                                                                                                                                                                            |
| `occupancy_max`          | Highest per-minute value                                                                                                                                                                                           |
| `occupancy_mean`         | Average of the per-minute values recorded in the window, rounded to 2 decimal places                                                                                                                               |
| `occupancy_median`       | Median per-minute value at `15m`. At `30m`, `1h`, and `1d` it repeats `occupancy_mean`, because those windows are built from `15m` windows and a true median cannot be computed. For a real median, request `15m`. |
| `occupancy_first`        | First per-minute value in the window                                                                                                                                                                               |
| `occupancy_last`         | Last per-minute value in the window                                                                                                                                                                                |
| `occupancy_sum`          | Sum of per-minute values                                                                                                                                                                                           |
| `presence_time_secs_sum` | Total presence seconds in the window                                                                                                                                                                               |
| `total_spots`            | Desk measurements at room/floor level only                                                                                                                                                                         |

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

{% hint style="warning" %}
Desk and motion measurements at the same level return the same field names and share a key. Request them separately; see [Combining measurements](/integrations-api-third-party-sensors/reporting-api.md#combining-measurements).
{% endhint %}

## Example: desk utilization per spot, every 15 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": ["spot_desk_occupancy"],
    "items": ["room_XXXX"],
    "start": "2026-09-14T13:00:00Z",
    "stop": "2026-09-14T14:00:00Z",
    "interval": "15m",
    "fields": ["spot_name", "occupancy_mean", "occupancy_median", "presence_time_secs_sum"]
  }'
```

```json
{
  "data": {
    "spot_XXXX": [
      {
        "start": "2026-09-14T13:00:00Z",
        "stop": "2026-09-14T13:15:00Z",
        "spot_name": "Desk 3A",
        "occupancy_mean": 0.8,
        "occupancy_median": 1,
        "presence_time_secs_sum": 720
      },
      …
    ]
  }
}
```

For a room-level example, see the [Quick start](/integrations-api-third-party-sensors/reporting-api.md#quick-start).