Skip to main content

Occupancy polling

Use occupancy polling when you need pull-based updates, replay windows, or downstream reconciliation.

Requires the Occupancy API feature

The Occupancy API feature is enabled by XY Sense per organisation and can vary per building and floor. If your queries return an access-disabled error, your XY Sense representative can enable it. See Feature enablement.

Fetch space information​

Open in API Explorer

Example query​

query OccupancyFloorSpaces($floorId: ID!) {
  floorSpaces(floorId: $floorId) {
    id
    name
    capacity
    floor {
      id
      name
    }
    spaceType {
      id
      name
    }
  }
}

Example variables​

{
  "floorId": "floor-l12"
}

Example response​

{
  "data": {
    "floorSpaces": [
      {
        "id": "desk-ne-101",
        "name": "Desk NE-101",
        "capacity": 1,
        "floor": {
          "id": "floor-l12",
          "name": "Level 12"
        },
        "spaceType": {
          "id": "space-type-desk",
          "name": "Desk"
        }
      }
    ]
  }
}

Fetch latest occupancy​

Open in API Explorer

Example query​

query LatestOccupancy($floorId: ID!) {
  floorSpaces(floorId: $floorId) {
    id
    name
    latestOccupancy {
      floorSpaceId
      headcount
      occupancyStatus
      previousOccupancyStatus
      collectedDate
      occupancyStatusChangeDate
    }
  }
}

Example variables​

{
  "floorId": "floor-l12"
}

Example response​

{
  "data": {
    "floorSpaces": [
      {
        "id": "desk-ne-101",
        "name": "Desk NE-101",
        "latestOccupancy": {
          "floorSpaceId": "desk-ne-101",
          "headcount": 1,
          "occupancyStatus": "CurrentlyOccupied",
          "previousOccupancyStatus": "RecentlyOccupied",
          "collectedDate": "2026-06-02T04:17:39.1066221Z",
          "occupancyStatusChangeDate": "2026-06-02T04:17:39.1066221Z"
        }
      }
    ]
  }
}

Fetch occupancy changes​

Open in API Explorer

Example query​

query OccupancyChanges($floorIds: [ID!], $from: Date!, $to: Date!) {
  occupancyChanges(floorIds: $floorIds, from: $from, to: $to, includeLatest: false, includeHeadcountChanges: true) {
    from
    to
    nextFrom
    data {
      floorSpaceId
      headcount
      occupancyStatus
      previousOccupancyStatus
      collectedDate
      occupancyStatusChangeDate
    }
  }
}

Example variables​

{
  "floorIds": [
    "floor-l12"
  ],
  "from": "2026-06-02T04:00:00Z",
  "to": "2026-06-02T05:00:00Z"
}

Example response​

{
  "data": {
    "occupancyChanges": {
      "from": "2026-06-02T04:00:00Z",
      "to": "2026-06-02T05:00:00Z",
      "nextFrom": "2026-06-02T04:17:39.1066221Z",
      "data": [
        {
          "floorSpaceId": "desk-ne-101",
          "headcount": 0,
          "occupancyStatus": "NotOccupied",
          "previousOccupancyStatus": "RecentlyOccupied",
          "collectedDate": "2026-06-02T04:17:39.1066221Z",
          "occupancyStatusChangeDate": "2026-06-02T04:17:39.1066221Z"
        }
      ]
    }
  }
}

Filter occupancy changes​

Use explicit floor-space filters when you only care about a subset of desks, rooms, or zones.

Open in API Explorer

Example query​

query FilteredOccupancyChanges($floorSpaceIds: [ID!], $from: Date!, $to: Date!) {
  occupancyChanges(floorSpaceIds: $floorSpaceIds, from: $from, to: $to, includeLatest: false, includeHeadcountChanges: true) {
    nextFrom
    data {
      floorSpaceId
      headcount
      occupancyStatus
      collectedDate
    }
  }
}

Example variables​

{
  "floorSpaceIds": [
    "desk-ne-101",
    "room-12a"
  ],
  "from": "2026-06-02T04:00:00Z",
  "to": "2026-06-02T05:00:00Z"
}

Example response​

{
  "data": {
    "occupancyChanges": {
      "nextFrom": "2026-06-02T04:52:10.5411902Z",
      "data": [
        {
          "floorSpaceId": "desk-ne-101",
          "headcount": 1,
          "occupancyStatus": "CurrentlyOccupied",
          "collectedDate": "2026-06-02T04:52:10.5411902Z"
        },
        {
          "floorSpaceId": "room-12a",
          "headcount": 4,
          "occupancyStatus": "CurrentlyOccupied",
          "collectedDate": "2026-06-02T04:49:58.1178410Z"
        }
      ]
    }
  }
}

Notes​

  • The maximum request window for occupancy changes is one hour.
  • The rolling retention is the most recent 1,000,000 events or 24 hours.
  • Persist nextFrom and use it for the next incremental request.