Skip to main content

Space sensor readings polling

Use this flow for comfort, air quality, and sensor-derived occupancy measurements from space sensors.

Requires the Space Sensor Readings API feature

The Space Sensor Readings 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 sensor capability information​

Open in API Explorer

Example query​

query SpaceSensorCapabilities {
  spaceSensorCapabilities {
    id
    name
    description
    unit
  }
}

Example response​

{
  "data": {
    "spaceSensorCapabilities": [
      {
        "id": "9bbebc44-654a-4496-a055-5a892008a94d",
        "name": "Temperature",
        "description": "Ambient temperature",
        "unit": "degrees Celsius"
      },
      {
        "id": "47c873e6-3c60-41f8-9d17-96e5639b3bde",
        "name": "Humidity",
        "description": "Relative humidity",
        "unit": "percent"
      }
    ]
  }
}

Fetch latest space sensor readings​

If you omit from, the API returns the latest readings for each matching space sensor.

Open in API Explorer

Example query​

query LatestSpaceSensorReadings($floorIds: [ID!]) {
  spaceSensorReadings(floorIds: $floorIds, includeLatest: true, comfortOnly: false) {
    nextFrom
    data {
      spaceSensorId
      capabilityName
      value
      collectedAt
    }
  }
}

Example variables​

{
  "floorIds": [
    "floor-l12"
  ]
}

Example response​

{
  "data": {
    "spaceSensorReadings": {
      "nextFrom": "2026-06-02T07:36:11.964156Z",
      "data": [
        {
          "spaceSensorId": "sensor-01",
          "capabilityName": "Temperature",
          "value": "22.4",
          "collectedAt": "2026-06-02T07:36:11.964156Z"
        },
        {
          "spaceSensorId": "sensor-01",
          "capabilityName": "Humidity",
          "value": "48.2",
          "collectedAt": "2026-06-02T07:36:11.964156Z"
        }
      ]
    }
  }
}

Fetch space sensor reading changes​

Open in API Explorer

Example query​

query SpaceSensorReadingChanges($floorIds: [ID!], $from: Date!, $to: Date!) {
  spaceSensorReadings(floorIds: $floorIds, from: $from, to: $to, includeLatest: false, comfortOnly: false) {
    from
    to
    nextFrom
    data {
      spaceSensorId
      capabilityName
      value
      collectedAt
    }
  }
}

Example variables​

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

Example response​

{
  "data": {
    "spaceSensorReadings": {
      "from": "2026-06-02T06:00:00Z",
      "to": "2026-06-02T07:00:00Z",
      "nextFrom": "2026-06-02T06:50:12.331245Z",
      "data": [
        {
          "spaceSensorId": "8bb1ba0b-6ea8-4635-86ef-3d57a7de4df3",
          "capabilityName": "Temperature",
          "value": "22.4",
          "collectedAt": "2026-06-02T06:50:12.331245Z"
        },
        {
          "spaceSensorId": "8bb1ba0b-6ea8-4635-86ef-3d57a7de4df3",
          "capabilityName": "Humidity",
          "value": "48.2",
          "collectedAt": "2026-06-02T06:50:12.331245Z"
        }
      ]
    }
  }
}

Fetch sensor associations by space or sensor​

Use floor-space metadata when you need to render or label which spaces a sensor installation serves.

Open in API Explorer

Example query​

query SpaceSensorAssociations($floorId: ID!) {
  floor(id: $floorId) {
    id
    name
    floorSpaces {
      id
      name
      spaceSensorInstallations {
        id
        name
        spaceSensorId
      }
    }
    spaceSensorInstallations {
      id
      name
      spaceSensorId
      floorSpaces {
        id
        name
      }
      ignoredCapabilities {
        id
        name
      }
    }
  }
}

Example variables​

{
  "floorId": "floor-l12"
}

Example response​

{
  "data": {
    "floor": {
      "id": "floor-l12",
      "name": "Level 12",
      "floorSpaces": [
        {
          "id": "room-12a",
          "name": "Room 12A",
          "spaceSensorInstallations": [
            {
              "id": "ssi-1",
              "name": "Room 12A Sensor",
              "spaceSensorId": "sensor-01"
            }
          ]
        }
      ],
      "spaceSensorInstallations": [
        {
          "id": "ssi-1",
          "name": "Room 12A Sensor",
          "spaceSensorId": "sensor-01",
          "floorSpaces": [
            {
              "id": "room-12a",
              "name": "Room 12A"
            }
          ],
          "ignoredCapabilities": [
            {
              "id": "47c873e6-3c60-41f8-9d17-96e5639b3bde",
              "name": "Humidity"
            }
          ]
        }
      ]
    }
  }
}

Filter space sensor reading changes​

Open in API Explorer

Example query​

query FilteredSpaceSensorReadingChanges($spaceSensorIds: [ID!], $from: Date!, $to: Date!) {
  spaceSensorReadings(spaceSensorIds: $spaceSensorIds, from: $from, to: $to, includeLatest: false) {
    nextFrom
    data {
      spaceSensorId
      capabilityName
      value
      collectedAt
    }
  }
}

Example variables​

{
  "spaceSensorIds": [
    "sensor-01",
    "sensor-02"
  ],
  "from": "2026-06-02T07:00:00Z",
  "to": "2026-06-02T08:00:00Z"
}

Example response​

{
  "data": {
    "spaceSensorReadings": {
      "nextFrom": "2026-06-02T06:50:12.331245Z",
      "data": [
        {
          "spaceSensorId": "8bb1ba0b-6ea8-4635-86ef-3d57a7de4df3",
          "capabilityName": "CarbonDioxide",
          "value": "641",
          "collectedAt": "2026-06-02T06:50:12.331245Z"
        }
      ]
    }
  }
}

Notes​

  • The maximum request window is 24 hours.
  • The documented rolling retention is the most recent 1,000,000 readings or 48 hours.
  • Use comfortOnly: true when you want comfort and air-quality readings without occupancy-style sensor output.