List Hosts
GET
/v1/hosts
Description
Retrieves a list of all hosts associated with the UI account making the API call.Note: The structure of
userData and reportedState fields may vary depending on the UniFi OS or Network Server version. The example provided is based on UniFi OS 4.1.13.Parameters
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/hosts?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
id
string
Unique identifier of the host device
hardwareId
string
Hardware identifier of the device
type
string
Type of the device (console, network-server)
ipAddress
string
Current IP address of the device
owner
boolean
Indicates if the current user is the owner of this device
isBlocked
boolean
Indicates if the device is blocked from cloud access
registrationTime
string
date-time
Time in RFC3339 format when the device was registered to the cloud
lastConnectionStateChange
string
date-time
Time in RFC3339 format when the connection state last changed
latestBackupTime
string
date-time
Time in RFC3339 format of the latest device backup
userData
User-specific data associated with the device including permissions and role information
reportedState
Device’s reported state information
httpStatusCode
integer
HTTP status code
traceId
string
Request trace identifier
nextToken
string
Pagination token for fetching the next set of results
Example Response
{
"data": [
{
"id": "70A7419783ED0000000006797F060000000006C719490000000062ABD4EA:1261206302",
"hardwareId": "e5bf13cd-98a7-5a96-9463-0d65d78cd3a4",
"type": "ucore",
"ipAddress": "220.130.137.169",
"owner": true,
"isBlocked": false,
"registrationTime": "",
"lastConnectionStateChange": "2024-04-16T02:52:54.193Z",
"latestBackupTime": "",
"userData": {
"apps": [
"users"
],
"consoleGroupMembers": [
{
"mac": "70A7419783ED",
"role": "UNADOPTED",
"roleAttributes": {
"applications": {
"access": {
"owned": false,
"required": false,
"supported": true
},
"connect": {
"owned": false,
"required": false,
"supported": true
},
"innerspace": {
"owned": false,
"required": false,
"supported": true
},
"network": {
"owned": false,
"required": true,
"supported": true
},
"protect": {
"owned": false,
"required": false,
"supported": true
},
"talk": {
"owned": false,
"required": false,
"supported": true
}
},
"candidateRoles": [
"PRIMARY"
],
"connectedState": "CONNECTED",
"connectedStateLastChanged": "2024-04-16T02:52:54.193Z"
},
"sysId": 59925
}
],
"controllers": [
"network",
"protect",
"access",
"talk",
"connect",
"innerspace"
],
"email": "example@ui.com",
"features": {
"deviceGroups": true,
"floorplan": {
"canEdit": true,
"canView": true
},
"manageApplications": true,
"notifications": true,
"pion": true,
"webrtc": {
"iceRestart": true,
"mediaStreams": true,
"twoWayAudio": true
}
},
"fullName": "UniFi User",
"localId": "d4eb483d-98a7-438b-abe1-f46628dff73f",
"permissions": {
"access.management": [
"admin"
],
"connect.management": [
"admin"
],
"innerspace.management": [
"admin"
],
"network.management": [
"admin"
],
"protect.management": [
"admin"
],
"system.management.location": [
"admin"
],
"system.management.user": [
"admin"
],
"talk.management": [
"admin"
]
},
"role": "owner",
"roleId": "c349b256-98a7-44ab-b8a1-13c437ea7742",
"status": "ACTIVE"
},
"reportedState": null
}
],
"httpStatusCode": 200,
"traceId": "a7dc15e0eb4527142d7823515b15f87d",
"nextToken": "ba8e384e-3308-4236-b344-7357657351ca"
}
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 hosts
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 hosts",
"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"
}