List Devices
GET
/v1/devices

Description

Retrieves a list of UniFi devices managed by hosts where the UI account making the API call is the owner or a super admin.

Note: The structure of the devices.uidb field may vary depending on the UniFi OS or Network Server version. The example provided is based on UniFi OS 4.1.13.

Parameters

hostIds[]
array[string]
Optional
query
List of host IDs to filter the results
time
string
Optional
query
Last processed timestamp of devices in RFC3339 format
pageSize
string
Optional
query
Number of items to return per page
nextToken
string
Optional
query
Token for pagination to retrieve the next set of results
Example 
curl -X GET 'https://api.ui.com/v1/devices?hostIds[]=900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789&hostIds[]=900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:987654321&time=2025-04-15T02:11:47Z&pageSize=10&nextToken=602232A870250000000006C514FF00000000073DD8DB000000006369FDA2:1467082514' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

Responses

200
ok
code
Error code from upstream
data
array
Generic response data, specific schema depends on the endpoint
hostId
string
Unique identifier of the host device
hostName
string
Name of the host device
devices
array
Array of devices managed by this host
id
string
Unique identifier of the device
mac
string
MAC address of the device
name
string
User-defined name of the device
model
string
Model name of the device
shortname
string
Short identifier of the device model (e.g., UDMPROSE)
ip
string
IP address of the device
productLine
string
Product line of the device (network, protect, etc.)
status
string
Current connection status of the device (online, offline, etc.)
version
string
Current firmware version of the device
firmwareStatus
string
Status of device firmware (upToDate, updateAvailable, etc.)
updateAvailable
string
Version of firmware update available for the device, if any
isConsole
boolean
Indicates if the device is a console device
isManaged
boolean
Indicates if the device is managed by the controller
startupTime
string
date-time
Time when the device was last started in RFC3339 format
adoptionTime
string
Time when the device was adopted in RFC3339 format
note
string
User-defined notes for the device
uidb
UI-specific metadata including images and identifiers
updatedAt
string
date-time
Last update time in RFC3339 format
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
nextToken
string
Pagination token for fetching the next set of results
Example Response 
{
  "data": [
    {
      "hostId": "900A6F00301100000000074A6BA90000000007A3387E0000000063EC9853:123456789",
      "hostName": "unifi.yourdomain.com",
      "devices": [
        {
          "id": "F4E2C6C23F13",
          "mac": "F4E2C6C23F13",
          "name": "unifi.yourdomain.com",
          "model": "UDM SE",
          "shortname": "UDMPROSE",
          "ip": "192.168.1.226",
          "productLine": "network",
          "status": "online",
          "version": "4.1.13",
          "firmwareStatus": "upToDate",
          "updateAvailable": null,
          "isConsole": true,
          "isManaged": true,
          "startupTime": "2024-06-19T13:41:43Z",
          "adoptionTime": null,
          "note": null,
          "uidb": {
            "guid": "0fd8c390-a0e8-4cb2-b93a-7b3051c83c46",
            "id": "e85485da-54c3-4906-8f19-3cef4116ff02",
            "images": {
              "default": "3008400039c483c496f4ad820242c447",
              "nopadding": "67b553529d0e523ca9dd4826076c5f3f",
              "topology": "8371ecdda1f00f1636a2eefadf0d7d47"
            }
          }
        }
      ],
      "updatedAt": "2025-04-15T02:11:47Z"
    }
  ],
  "httpStatusCode": 200,
  "traceId": "a7dc15e0eb4527142d7823515b15f87d",
  "nextToken": "ba8e384e-3308-4236-b344-7357657351ca"
}

Responses

400
invalid parameter
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "parameter_invalid",
  "httpStatusCode": 400,
  "message": "invalid time format: 2024-04-24",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

401
unauthorized
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "unauthorized",
  "httpStatusCode": 401,
  "message": "unauthorized",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

429
rate limit
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier

Headers

Retry-After
string
example: 5
Example Response 
{
  "code": "rate_limit",
  "httpStatusCode": 429,
  "message": "rate limit exceeded, retry after 5.372786998s",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

500
failed to list devices
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "server_error",
  "httpStatusCode": 500,
  "message": "failed to list devices",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}

Responses

502
bad gateway
code
Error code from upstream
httpStatusCode
integer
HTTP status code
message
string
Error message
traceId
string
Request trace identifier
Example Response 
{
  "code": "bad_gateway",
  "httpStatusCode": 502,
  "message": "bad gateway",
  "traceId": "a7dc15e0eb4527142d7823515b15f87d"
}