UniFi Local Network API Port Troubleshooting

Use this reference when troubleshooting customer UniFi switch-port/client issues where Site Manager data is too shallow.

Key distinction

Site Manager API (https://api.ui.com/v1 / /ea with X-API-KEY) gives high-level site/host/device inventory and WAN issue summaries.
Local Network API is required for clients, events, detailed switch port stats, CRC/drop counters, PoE state/actions, and port power cycling.

Create local key per console:

UniFi Network → Integrations → Network API → Create API Key

Store per-site keys securely and label them by customer/console.

Liberty Tire identifiers found Jul 14, 2026

Host: Liberty-UDM-Pro
Host ID: D8B3702867A1000000000770A2860000000007CBEC34000000006437A55B:1003909054
Site ID: 66cfc43699ec0d7200188ed3
WAN/IP shown by Site Manager: 108.175.202.88
Gateway MAC: d8:b3:70:28:67:a1
Switch: USW-24-PoE
Switch MAC: E4:38:83:94:66:E3
Switch IP: 10.1.0.5
Phone issue: Yealink W70 cordless base on switch port 1 periodically develops static/packet-loss symptoms; user's manual fix is power-cycle port 1.

GLC identifiers found Jul 14, 2026

Host: GLC UDM Pro
Host ID: AC8BA96EDB4F0000000007153E2D00000000076AA09A0000000063974676:10670668
Site ID: 66770d7ed634742ade16b848
WAN/IP shown by Site Manager: 75.62.181.131

Troubleshooting workflow

Read-only first
- Identify switch and target port.
- Identify client MAC/IP/hostname (Yealink W70 base).
- Pull recent client history and switch port metrics.
- Check port link flaps, speed/duplex, PoE draw/state, RX/TX drops, CRC/FCS errors.
- Correlate with report time.
Check WAN separately
- Site Manager may show high-latency WAN events; do not confuse those with port-level packet loss unless phone RTP paths confirm WAN jitter.
Only after approval
- Execute PoE/port cycle on the specific port.
- Verify client returns and counters reset/stabilize.
Long-term watchdog
- No-agent script checks port/client health periodically.
- Alert on flaps/errors/phone offline.
- Approval-gated action can power-cycle the known port.

Port action endpoint shape

UniFi docs show:

POST /v1/sites/{siteId}/devices/{deviceId}/interfaces/ports/{portIdx}/actions

The exact action name/body depends on Network version; inspect the local Network app's Integrations docs for that console before writing automation.

Guardrails

Do not cycle ports without explicit user approval.
Confirm port numbering in API is the same as UI label before action; some APIs use zero-based portIdx, while UI labels are one-based.
Record before/after counters for any power cycle action.

2.7 KiB Raw Blame History