Idea: UniFi Wi-Fi monitoring (AP radios and device statistics) via the official Network Integration API

[fabicarvano]

UniFi Wi-Fi monitoring: AP radios and device statistics

Summary

Extend the existing UniFi agent collector to report current-state Wi-Fi health of Access Points, using only the official UniFi Network Integration API. No new collector, no legacy APIs, read-only (GET), reusing topologyV1.

Context and problem

Breeze already discovers UniFi hosts/sites and devices, maps them to Breeze sites, and the agent collector already collects devices, clients, device details and the topologyV1 contract. Today Breeze can tell an operator that an AP exists and is online. It cannot tell how the AP and its radios are operating, so a first investigation of "the Wi-Fi is bad" still means opening the UniFi console.

The statistics resource already exists in topologyV1 but is not collected yet.

Proposal

Add to the agent collector (agent/internal/unifi/):

1. Radio inventory from GET /sites/{siteId}/devices/{deviceId}: frequencyGHz, channel, channelWidthMHz, wlanStandard per radio.
2. A new call to GET /sites/{siteId}/devices/{deviceId}/statistics/latest: uptimeSec, cpuUtilizationPct, memoryUtilizationPct, uplink.rxRateBps/txRateBps, and txRetriesPct per radio.
3. Wireless clients per AP, correlated from the existing client to uplinkDeviceId relationship.
4. Transport through topologyV1 (device_details gets radios[], statistics gets device and radio stats) with new shared types WirelessRadioOverview and WirelessRadioStatistics.

Detail and statistics radios are correlated by frequencyGHz, never by array position.

What the operator will be able to answer

• Is the AP online and for how long (uptime)?
• How many wireless clients are on it, and is any AP unusually loaded compared with the others at the site?
• Which radios are active, on which band, channel, channel width and WLAN standard?
• Are there many retransmissions (TX retries)?
• How are CPU and memory, and is the uplink rate abnormal or a bottleneck?
• Combined with an existing Network Monitor on the AP: is it intermittent or slower to respond?

Principles

• Official API only, GET only. No writes to the controller, no reboot, channel change or client block.
• Same collector, same credentials mechanism, same site/org isolation.
• Bounded work per poll: rotation, timeouts, per-device failure isolation, no uncontrolled fan-out.
• Missing data is null, never 0. txRetriesPct = 0 is a valid measurement; null means not collected or unsupported. Same for CPU, memory, uplink and uptime.
• Persistence reuses the topology / normalized topology path. No new tables.
• Alerts, if added, are measurable facts only (AP offline, retries/CPU/memory above threshold). No causal diagnosis or recommendations.

Future customer-facing value

A simplified Wi-Fi overview in the customer portal as an extension of Network Visibility (number of APs, online, connected devices, clients per AP). Technical detail stays operator-side.

Out of scope

Tracked separately in a companion Advanced discussion: radio history/time-series, clients per band, endpoint-agent enrichment (RSSI, frequency), roaming, advanced RF metrics, multi-vendor, legacy/internal UniFi APIs, diagnostics/recommendations by AI, and any write action.

Known limitation

The official API confirms client to AP but not client to radio, so this version shows clients per AP, not per band. Only current state is shown; there is no radio history.

Tests planned

Agent: AP with no, one and several radios; 2.4/5/6 GHz; txRetriesPct 0 and greater than 0; statistics 404/500; malformed JSON; partial device failure; bounded request count. Shared: ranges, nullable fields, canonicalization, digest stability. API: topologyV1 and legacy telemetry compatibility, malformed radio payload rejected.

Open questions

1. Should the new radio fields ship as an additive topologyV1 minor, or does the current contract require a different versioning step?
2. Is a single statistics/latest call per device per rotation cycle acceptable for the collector's request budget?

Next step

If the idea fits the project's direction, I will write the detailed plan as a spec under docs/superpowers/specs/, following the existing conventions, and implement only after it is approved.

[ToddHebebrand]

Thanks @fabicarvano. The facts in the proposal check out against main, and it fills a slot we already reserved, so yes to a spec.

Verified: the collector (agent/internal/unifi/) talks only to the official Integration API (client.go:18, /proxy/network/integration/v1). It already lists sites, devices and clients, and it fetches device details in a rotating window of 32 per poll (topology.go:35). statistics is already a resource kind in topologyV1 (topology_v1.go:32) but is always sent as not_collected (client.go:433). Client-to-AP attribution through uplinkDeviceId works, and wireless links already show as wireless attachments. Nothing about radios or Wi-Fi is collected today. The comment at client.go:25 saying details aren't fetched is out of date.

What the spec needs to settle:

• Versioning. There is no minor version: the schema is version: z.literal(1) (topologyPhysical.ts:181), and the API recomputes the content digest from the parsed resource while zod drops unknown keys. A newer agent sending radios[] to an older API would likely fail as content_digest_mismatch. Spell out the rollout order and the version bump, or show how the extension stays digest-compatible.
• Fixture proof. Collected fields have to be proven against a real controller fixture on a supported version before we ship them (the M3-D9 rule, UniFi collector: PoE mode and per-port traffic rates not collected (link/speed only) #7271). I couldn't find frequencyGHz, channel, channelWidthMHz, wlanStandard or txRetriesPct in any fixture we have, so please capture real responses and cite the endpoint each field comes from.
• One home for the data. The legacy unifi_device_telemetry table already has cpu, mem, uptime and client-count columns (schema/unifi.ts:152-157), and the topology projection currently skips the stats section (physicalProjector.ts:205-210). Pick one store, and name the UI that reads it, so the numbers don't live in two places.
• Request budget. Stats calls roughly double the per-poll request count. State the cadence and the cap.
• Alerts go through the consolidated alert conditions (Alerting on UniFi device state #3208 overlaps), not a separate evaluator.

Same shape as #7642 works well: a spec PR under docs/superpowers/specs/, and we'll review it there.

[fabicarvano]

Todd, thanks again for the direction on this proposal.

At the moment, I don't have a suitable UniFi environment to capture and validate the real fixtures needed to close the spec with the level of confidence this work deserves, especially around radio fields, statistics, and contract compatibility.

Rather than move forward with a spec based on assumptions, I'll leave this as a future implementation until I have the environment and evidence needed to validate the real data first.

I wanted to record that here so the discussion stays current and has a clear status rather than remaining open without a defined next step.

[bgatestmg]

Sanitized fixtures for the radio and statistics fields in this proposal, pulled 2026-10-15.

GET only, official Network Integration API, through the Site Manager connector:

GET https://api.ui.com/v1/connector/consoles/{consoleId}/proxy/network/integration/v1/...

That is the cloud server URL in the Network v10.6.106 OpenAPI spec. Consoles that answered were UniFi OS 5.1.132 running Network 10.6.106. Consoles on UniFi OS 6.0.123 returned 404 for both that path and /v1/connector/consoles/{id}/network/integration/v1/info.

Names, MAC addresses, IP addresses, site ids, device ids, and heartbeat timestamps are removed. A key that is missing below was omitted by the controller. lastHeartbeatAt and nextHeartbeatAt were present on statistics/latest and are removed here.

Wireless client counts are from GET /v1/sites/{siteId}/clients (type: WIRELESS, grouped by uplinkDeviceId). That schema has no radio, band, or frequency, so the count is per AP.

1. U6 LR, online — txRetriesPct 26 and 0 on the same AP

3 wireless clients. Device firmware 6.7.57.

GET /v1/sites/{siteId}/devices/{deviceId} → interfaces.radios:

[
  {"frequencyGHz": 2.4, "channel": 6, "channelWidthMHz": 20, "wlanStandard": "802.11n"},
  {"frequencyGHz": 5, "channel": 44, "channelWidthMHz": 40, "wlanStandard": "802.11ax"}
]

GET /v1/sites/{siteId}/devices/{deviceId}/statistics/latest:

{
  "cpuUtilizationPct": 1.2,
  "memoryUtilizationPct": 37.5,
  "uptimeSec": 3604448,
  "loadAverage1Min": 0.06,
  "loadAverage5Min": 0.01,
  "loadAverage15Min": 0.0,
  "uplink": {"rxRateBps": 712, "txRateBps": 2072},
  "interfaces": {
    "radios": [
      {"frequencyGHz": 2.4, "txRetriesPct": 26.0},
      {"frequencyGHz": 5, "txRetriesPct": 0.0}
    ]
  }
}

2. E7, online — 2.4 / 5 / 6 GHz, txRetriesPct 0 and 5

5 wireless clients. Device firmware 8.7.11. The uplink object was present, and rxRateBps / txRateBps were omitted.

[
  {"frequencyGHz": 2.4, "channel": 11, "channelWidthMHz": 20, "wlanStandard": "802.11be"},
  {"frequencyGHz": 5, "channel": 44, "channelWidthMHz": 80, "wlanStandard": "802.11be"},
  {"frequencyGHz": 6, "channel": 197, "channelWidthMHz": 160, "wlanStandard": "802.11be"}
]

{
  "cpuUtilizationPct": 6.8,
  "memoryUtilizationPct": 32.9,
  "uptimeSec": 3863772,
  "loadAverage1Min": 2.04,
  "loadAverage5Min": 2.12,
  "loadAverage15Min": 2.13,
  "interfaces": {
    "radios": [
      {"frequencyGHz": 2.4, "txRetriesPct": 0.0},
      {"frequencyGHz": 5, "txRetriesPct": 0.0},
      {"frequencyGHz": 6, "txRetriesPct": 5.0}
    ]
  }
}

3. U6 Lite, offline — channel and txRetriesPct omitted

0 wireless clients. Device firmware 6.7.41. cpuUtilizationPct, memoryUtilizationPct, uptimeSec, and the load averages were omitted, not returned as JSON null. Uplink rates were still numbers. Statistics radios included frequencyGHz only.

[
  {"frequencyGHz": 2.4, "channelWidthMHz": 20, "wlanStandard": "802.11n"},
  {"frequencyGHz": 5, "channelWidthMHz": 40, "wlanStandard": "802.11ax"}
]

{
  "uplink": {"rxRateBps": 1724576, "txRateBps": 53711480},
  "interfaces": {
    "radios": [
      {"frequencyGHz": 2.4},
      {"frequencyGHz": 5}
    ]
  }
}

4. U6 Lite, online — channel present, txRetriesPct 0

1 wireless client. Device firmware 6.7.57. Same model as the offline AP, with channel populated and txRetriesPct: 0.0 as a real measurement.

[
  {"frequencyGHz": 2.4, "channel": 11, "channelWidthMHz": 20, "wlanStandard": "802.11n"},
  {"frequencyGHz": 5, "channel": 149, "channelWidthMHz": 40, "wlanStandard": "802.11ax"}
]

{
  "cpuUtilizationPct": 0.4,
  "memoryUtilizationPct": 30.0,
  "uptimeSec": 97436,
  "loadAverage1Min": 0.5,
  "loadAverage5Min": 0.49,
  "loadAverage15Min": 0.53,
  "uplink": {"rxRateBps": 407952, "txRateBps": 3861104},
  "interfaces": {
    "radios": [
      {"frequencyGHz": 2.4, "txRetriesPct": 0.0},
      {"frequencyGHz": 5, "txRetriesPct": 0.0}
    ]
  }
}

What this lines up with in the v10.6.106 schemas:

• Detail radios and statistics radios join on frequencyGHz (2.4, 5, 6). There is no radio id. 60 was not seen. wlanStandard values seen: 802.11n, 802.11ax, 802.11be.
• channel is optional and was omitted on the offline U6 Lite. Online radios returned it as an integer.
• txRetriesPct is optional. Online radios returned a number, including 0.0 and values above 0 (0.5, 5.0, 26.0 on other APs in the same pull). The offline U6 Lite omitted it.
• CPU, memory, uptime, and load averages were numbers on online devices and omitted on offline devices.
• uplink.rxRateBps / txRateBps were omitted on the E7, 0 on some other online APs, and positive integers on others, including the offline U6 Lite.
• The connector cap is 100 requests per minute per console, 25 seconds per call. One statistics/latest per device is the extra call this proposal adds.

[bgatestmg]

A few more observations from the same pull (Network 10.6.106, UniFi OS 5.1.132, GET only, Site Manager connector). Identifiers, names, and addresses are removed.

Clients

GET /v1/sites/{siteId}/clients returned WIRED and WIRELESS only. No VPN or TELEPORT clients in this pull. Both types use the published keys and nothing else: type, id, name, connectedAt, macAddress, uplinkDeviceId, access, and sometimes ipAddress. There is no RSSI, channel, band, VLAN, or radio id.

uplinkDeviceId is on wired clients too, so client-to-device attribution is not wireless-only. The per-AP count in this proposal is the WIRELESS subset.

ipAddress is not required. It was unpopulated on most wired clients and on some wireless clients. access.type was DEFAULT, plus one wireless GUEST. That guest object had type and authorized only. The authorization object (method, expiry, rate limits) was omitted.

Switches, because it bounds this proposal

statistics/latest on a switch still returns interfaces, and that object was {}. There is no per-port counter there. Port objects on GET /v1/sites/{siteId}/devices/{deviceId} also have no byte or rate fields. Link speed is speedMbps / maxSpeedMbps only. In a sample of 124 ports, speedMbps was present on every UP port and omitted on every DOWN port.

Device-detail uplink is {deviceId} only. Rates stay on statistics/latest, and on a switch that uplink object had neither rxRateBps nor txRateBps.

PoE is populated on those device-detail ports. That is the fixture #7271 is waiting on, so the port examples are on that issue.

Firewall

Zones and policies are on the same API (GET .../firewall/zones, GET .../firewall/policies). Rule bodies are not included here. On one site, action.type was ALLOW or BLOCK (REJECT did not appear). Each ALLOW included allowReturnTraffic. source / destination trafficFilter, when present, was IP_ADDRESS or PORT; most policies had none. connectionStateFilter was either omitted or a string array (INVALID, or ESTABLISHED plus RELATED), never JSON null. Zone metadata.origin was SYSTEM_DEFINED or USER_DEFINED.

[fabicarvano]

@bgatestmg, thank you very much for taking the time to collect and document all of this so carefully.

These fixtures are extremely valuable and, more importantly, they unblock the main point that was still preventing this discussion from moving forward with the level of confidence we needed.

The evidence collected from a real controller regarding radio inventory, statistics/latest, optional and omitted fields, valid zero values such as txRetriesPct: 0.0, radios operating on 2.4/5/6 GHz, and wireless client attribution through uplinkDeviceId gives us exactly the concrete input that was missing to turn this proposal into an evidence-based implementation specification rather than one built on assumptions.

The additional observations regarding switches, PoE, and the actual limits of what statistics/latest exposes are also very important for keeping the scope accurate and avoiding assumptions about capabilities that the API does not provide.

With this information now available, I will move the discussion to the next stage: preparing the spec under docs/superpowers/specs/, including the architectural decisions that still need to be formalized, such as contract versioning, request budget, data ownership, freshness semantics, and the appropriate operator-facing surface.

The spec will be submitted shortly for maintainer review and approval before any implementation begins.

I will also make sure your contribution is explicitly recognized. In addition to referencing these fixtures and comments in both the spec and the PR, the spec commit will include a Co-authored-by trailer to formally record your contribution to the technical foundation of the design.

Thank you again for sharing such detailed and actionable data. This has genuinely moved the proposal into its next stage.

[fabicarvano]

Hi @bgatestmg, thanks for the fixtures for #7690.

In the review of PR #9293, Todd decided that a capture from a local controller (§14.6) is an entry gate for W2. If you can, we need a specific request:

1. A local UniFi controller, not through Site Manager. Please share the exact Network and UniFi OS versions.
2. GET requests only, on the same endpoints as your previous fixtures: device list, device detail with radios, statistics/latest for one AP, and the complete client list with uplinkDeviceId.
3. Sanitization as in the previous fixtures: no names, MAC or IP addresses, site/device/client IDs, or heartbeat timestamps.
4. In the reply, it is enough to state the Network and UniFi OS versions and whether any expected field (radios, statistics or uplinkDeviceId) was missing.

If you don't have access to a local controller, you can reply "no local access" and nothing else is needed. Thanks!

[bgatestmg]

Local-controller capture for §14.6, pulled 2026-10-20. GET only, from the controller itself:

GET https://<controller>/proxy/network/integration/v1/...

Not the Site Manager connector. Network 10.6.106 (applicationVersion on GET /v1/info, which returns that field and nothing else). UniFi OS 5.1.33 (console_display_version on the same controller's Network stat/sysinfo). The earlier fixtures were Network 10.6.106 on UniFi OS 5.1.132, through the connector.

Names, MAC addresses, IP addresses, site ids, device ids, client ids, and heartbeat timestamps are removed. A key that is missing below was omitted by the controller. lastHeartbeatAt and nextHeartbeatAt were present on statistics/latest and are removed here.

Device list

GET /v1/sites/{siteId}/devices — 29 devices, 11 with features containing accessPoint and interfaces containing radios.

List rows and detail rows do not use the same shape for those two fields.

List row (an online E7, firmware 8.7.11):

{
  "model": "E7",
  "state": "ONLINE",
  "supported": true,
  "firmwareVersion": "8.7.11",
  "firmwareUpdatable": false,
  "features": ["accessPoint"],
  "interfaces": ["radios"]
}

state on this controller is the uppercase string ONLINE.

Device detail

GET /v1/sites/{siteId}/devices/{deviceId} for that AP. features is an object and interfaces.radios is the radio array. There is no radio id. uplink is { "deviceId" } only.

{
  "model": "E7",
  "state": "ONLINE",
  "supported": true,
  "firmwareVersion": "8.7.11",
  "firmwareUpdatable": false,
  "features": { "accessPoint": {} },
  "interfaces": {
    "radios": [
      {"wlanStandard": "802.11be", "frequencyGHz": 2.4, "channelWidthMHz": 20, "channel": 6},
      {"wlanStandard": "802.11be", "frequencyGHz": 5, "channelWidthMHz": 80, "channel": 48},
      {"wlanStandard": "802.11be", "frequencyGHz": 6, "channelWidthMHz": 160, "channel": 53}
    ]
  },
  "uplink": { "deviceId": "<redacted>" }
}

802.11be was not in the earlier U6 fixtures (those were 802.11n and 802.11ax). 2.4, 5, and 6 GHz are all present, and every radio had channel.

statistics/latest

GET /v1/sites/{siteId}/devices/{deviceId}/statistics/latest for the same AP.

{
  "uptimeSec": 4272049,
  "loadAverage1Min": 2.46,
  "loadAverage5Min": 2.3,
  "loadAverage15Min": 2.18,
  "cpuUtilizationPct": 4.8,
  "memoryUtilizationPct": 33.1,
  "uplink": {},
  "interfaces": {
    "radios": [
      {"frequencyGHz": 2.4, "txRetriesPct": 0.0},
      {"frequencyGHz": 5, "txRetriesPct": 0.0},
      {"frequencyGHz": 6, "txRetriesPct": 10.0}
    ]
  }
}

txRetriesPct: 0.0 is a measured zero, same as the earlier fixtures. uplink was present and empty, so rxRateBps and txRateBps were omitted on this AP. loadAverage1Min, loadAverage5Min, and loadAverage15Min were present; they were not in the earlier write-up.

Clients

GET /v1/sites/{siteId}/clients — 382 clients, WIRED 270 and WIRELESS 112. No VPN or TELEPORT.

uplinkDeviceId was present on every wired client and every wireless client. Nothing in this pull omitted it.

Published keys, and nothing else: type, id, name, connectedAt, macAddress, uplinkDeviceId, access, and sometimes ipAddress. No RSSI, channel, band, VLAN, or radio id. The two samples below omitted ipAddress.

{"type": "WIRELESS", "uplinkDeviceId": "<redacted>", "access": {"type": "DEFAULT"}}

{"type": "WIRED", "uplinkDeviceId": "<redacted>", "access": {"type": "DEFAULT"}}

Against the requested fields

Radios, statistics/latest, and uplinkDeviceId were all present. The rate keys on statistics/latest uplink were the ones this AP omitted.

[ToddHebebrand]

Gate met — thank you. The local-controller capture (Network 10.6.106 on UniFi OS 5.1.33, GET only, direct, not through Site Manager) is exactly what §14.6 asked for. It is recorded in the spec with the decoder/contract tests updated for the observed payload differences in #9555 (571f9cce69), which marks the §14.6 entry gate as satisfied. W2 (radio inventory + statistics/latest + wireless-client attribution) can open on that basis; implementation PRs will reference this thread.