Back to Docs

Site Health

The Site Health API reports device, gateway, and tag connectivity health, instance-wide or filtered and grouped by campus, building, floor, or zone. It also provides historical daily snapshots per building so you can track connectivity trends over time.

Before You Begin

An access token. See Authentication.

Health Metric Categories

Every Site Health response breaks status down across five categories:

Category	Description
`devices`	All connected devices
`gateways`	LoRaWAN gateways
`tags`	Tags provisioned/onboarded
`tags_paired`	Tags currently paired to an asset
`monitors`	Monitor devices

Each category reports the same shape:

Field	Type	Description
`total`	number	Total count in this category
`online`	number	Count currently online
`offline`	number	Count currently offline
`ready_to_connect`	number	Provisioned but not yet connected
`percentage_online`	number	Percent online
`percentage_offline`	number	Percent offline
`percentage_ready_to_connect`	number	Percent ready to connect

Site Health Status

GET {{API_DOMAIN}}/integrations/site-health

Retrieve connectivity health for devices, gateways, tags, and monitors. With no query parameters, returns instance-wide totals. Add filters and/or group_by to scope and break down the results.

Query Parameters

Parameter	Type	Required	Description	Example
`campus_ids`	string	No	Filter by campus id (comma-separated for multiple)	`campus-001`
`building_ids`	string	No	Filter by building id (comma-separated for multiple)	`building-A,building-B,building-C`
`floor_ids`	string	No	Filter by floor id (comma-separated for multiple)	`floor-3B`
`group_by`	string	No	Group results by location level: `building`, `floor`, `room`, or `zone`	`building`

campus_ids, building_ids, and floor_ids scope which locations are included. group_by controls how the results are broken down. For example, ?campus_ids=campus-001&group_by=building returns a per-building breakdown for that campus.

Example Request (Instance-wide)

bash

curl -sS "{{API_DOMAIN}}/integrations/site-health" \
  -H "Authorization: Bearer $MQ_TOKEN" | jq

Example Response (Instance-wide)

json

{
  "metadata": {
    "timestamp": "2026-07-27T20:32:57.649658+00:00",
    "filters_applied": {}
  },
  "overall": {
    "devices": {
      "total": 503,
      "online": 500,
      "offline": 3,
      "ready_to_connect": 0,
      "percentage_online": 99.4,
      "percentage_offline": 0.6,
      "percentage_ready_to_connect": 0.0
    },
    "gateways": {
      "total": 8,
      "online": 6,
      "offline": 0,
      "ready_to_connect": 2,
      "percentage_online": 75.0,
      "percentage_offline": 0.0,
      "percentage_ready_to_connect": 25.0
    },
    "tags": {
      "total": 0,
      "online": 0,
      "offline": 0,
      "ready_to_connect": 0,
      "percentage_online": 0.0,
      "percentage_offline": 0.0,
      "percentage_ready_to_connect": 0.0
    },
    "tags_paired": {
      "total": 0,
      "online": 0,
      "offline": 0,
      "ready_to_connect": 0,
      "percentage_online": 0.0,
      "percentage_offline": 0.0,
      "percentage_ready_to_connect": 0.0
    },
    "monitors": {
      "total": 0,
      "online": 0,
      "offline": 0,
      "ready_to_connect": 0,
      "percentage_online": 0.0,
      "percentage_offline": 0.0,
      "percentage_ready_to_connect": 0.0
    }
  }
}

Example Requests (Filtered / Grouped)

code

GET {{API_DOMAIN}}/integrations/site-health?campus_ids=campus-001&group_by=building
GET {{API_DOMAIN}}/integrations/site-health?building_ids=building-A,building-B,building-C
GET {{API_DOMAIN}}/integrations/site-health?floor_ids=floor-3B&group_by=zone

Grouped Response Shape: The exact response shape when group_by is set (e.g., a per-building or per-zone breakdown in place of overall) is still being finalized in this documentation. An example of a grouped response will be added here once confirmed.

Response Codes

Code	Status	Description
200	OK	Site health retrieved successfully
400	Bad Request	Invalid filter or `group_by` value
401	Unauthorized	Invalid or expired access token
5xx	Internal Server Error	Service temporarily unavailable

Building History

GET {{API_DOMAIN}}/integrations/site-health/building-history

Retrieve a paginated, time-ordered history of connectivity health snapshots for one or more buildings. Each result is a daily snapshot capturing the same device/gateway/tag/monitor breakdown as Site Health Status.

Query Parameters

Parameter	Type	Required	Description	Example
`building_id`	string	No	Filter by a single building id	`1`
`building_id__in`	string	No	Filter by multiple building ids (comma-separated)	`1,2,3`
`timestamp__gte`	string	No	Start of date range (ISO8601)	`2023-01-01T00:00:00Z`
`timestamp__lte`	string	No	End of date range (ISO8601)	`2023-01-31T23:59:59Z`

Response Fields

Each result includes record metadata plus the same five health categories (devices, gateways, tags, tags_paired, monitors) as Site Health Status, flattened with _total, _online, _offline, _ready_to_connect, _percentage_online, _percentage_offline, and _percentage_ready_to_connect suffixes.

Field	Type	Description
`id`	number	Snapshot record id
`version`	number	Optimistic concurrency lock value (not a timestamp)
`created` / `updated`	string	ISO8601 timestamps for when the record itself was written
`building_id`	string	Building identifier
`timestamp`	string	ISO8601 timestamp the snapshot was captured
`devices_total` / `_online` / `_offline` / `_ready_to_connect`	number	Device counts
`devices_percentage_online` / `_offline` / `_ready_to_connect`	number	Device percentages
`gateways_*`	number	Same shape as `devices_*`, for gateways
`tags_*`	number	Same shape as `devices_*`, for tags provisioned/onboarded
`tags_paired_*`	number	Same shape as `devices_*`, for tags currently paired to an asset
`monitors_*`	number	Same shape as `devices_*`, for monitor devices

Example Request

bash

curl -sS "{{API_DOMAIN}}/integrations/site-health/building-history?building_id=1&timestamp__gte=2026-07-10T00:00:00Z&timestamp__lte=2026-07-27T23:59:59Z" \
  -H "Authorization: Bearer $MQ_TOKEN" | jq

Example Response

json

{
  "count": 18,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 18,
      "version": 1785131066115034,
      "created": "2026-07-27T06:00:12.799850Z",
      "updated": "2026-07-27T06:00:12.799865Z",
      "created_by": "",
      "updated_by": null,
      "building_id": "65_Hayden",
      "timestamp": "2026-07-27T06:00:12.380962Z",
      "devices_total": 503,
      "devices_online": 500,
      "devices_offline": 3,
      "devices_ready_to_connect": 0,
      "devices_percentage_online": 99.4,
      "devices_percentage_offline": 0.6,
      "devices_percentage_ready_to_connect": 0.0,
      "gateways_total": 8,
      "gateways_online": 6,
      "gateways_offline": 0,
      "gateways_ready_to_connect": 2,
      "gateways_percentage_online": 75.0,
      "gateways_percentage_offline": 0.0,
      "gateways_percentage_ready_to_connect": 25.0,
      "tags_total": 0,
      "tags_online": 0,
      "tags_offline": 0,
      "tags_ready_to_connect": 0,
      "tags_percentage_online": 0.0,
      "tags_percentage_offline": 0.0,
      "tags_percentage_ready_to_connect": 0.0,
      "tags_paired_total": 0,
      "tags_paired_online": 0,
      "tags_paired_offline": 0,
      "tags_paired_ready_to_connect": 0,
      "tags_paired_percentage_online": 0.0,
      "tags_paired_percentage_offline": 0.0,
      "tags_paired_percentage_ready_to_connect": 0.0,
      "monitors_total": 0,
      "monitors_online": 0,
      "monitors_offline": 0,
      "monitors_ready_to_connect": 0,
      "monitors_percentage_online": 0.0,
      "monitors_percentage_offline": 0.0,
      "monitors_percentage_ready_to_connect": 0.0
    }
  ]
}

Pagination: Results are paginated using count/next/previous/results, consistent with other list endpoints in this API.

Response Codes

Code	Status	Description
200	OK	History retrieved successfully
400	Bad Request	Invalid filter parameters
401	Unauthorized	Invalid or expired access token
5xx	Internal Server Error	Service temporarily unavailable

Use Cases

Facilities Dashboards: Surface real-time connectivity health per campus or building.
Proactive Maintenance: Catch offline gateways or unpaired tags before they cause blind spots.
Trend Analysis: Use Building History to spot degrading connectivity over time.
Reporting: Track uptime and onboarding progress as devices are deployed.

What's Next?

Asset Management: Create, locate, search, and delete assets.
Asset Utilization: Track usage events over time.

Asset Utilization