List hosts
GET /v1/hosts
Get a paginated list of hosts, lighthouses, and relays.
Token scope required: hosts:list
Request
Query Parameters
- includeCounts boolean
If true, return count of total records and current page start and count in metadata
- cursor string
Cursor value at which to start the results, provided in
nextCursor
orprevCursor
of a prior requestExample: bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19 - pageSize integer
Possible values:
<= 500
Default value:
25
Number of records to return in each page
- filter.isBlocked boolean
Return only hosts that are blocked if true, unblocked if false
- filter.isLighthouse boolean
Return only lighthouses if true, non-lighthouses if false
- filter.isRelay boolean
Return only relays if true, non-relays if false
- filter.metadata.lastSeenAt string
Possible values: [
null
]When "null", returns hosts that have never communicated with the Defined Networking service.
- filter.metadata.platform string
Possible values: [
mobile
,dnclient
,null
]Return only hosts matching the specified client platform
- filter.metadata.updateAvailable boolean
Return only hosts that have updates available when true, or up-to-date hosts when false
- 200
Successful operation
- application/json
- Schema
- Example (from schema)
- noParams
- includeCounts
Schema
data object[]
Array [id stringorganizationID stringnetworkID stringroleID string nullablename stringipAddress ipv4staticAddresses address:port[]listenPort int64Will be zero if a regular host
isLighthouse booleanDefault value:
false
isRelay booleanDefault value:
false
createdAt date-timeisBlocked booleanDefault value:
false
metadata object
lastSeenAt string nullableversion string nullableplatform string nullablePossible values: [
dnclient
,mobile
,null
]updateAvailable boolean nullabletags key:value[]configOverrides object[]
List of config overrides for the nebula config
Array [- anyOf
- lighthouse.dns.host
- lighthouse.dns.port
- lighthouse.local_allow_list
- lighthouse.remote_allow_list
- lighthouse.serve_dns
- listen.batch
- listen.read_buffer
- listen.write_buffer
- logging.format
- logging.level
- logging.timestamp_format
- preferred_ranges
- routines
- stats.host
- stats.interval
- stats.lighthouse_metrics
- stats.listen
- stats.message_metrics
- stats.namespace
- stats.path
- stats.prefix
- stats.subsystem
- stats.type
- tun.dev
- tun.mtu
- tun.tx_queue
key string requiredPossible values: [
lighthouse.dns.host
]value string requiredkey string requiredPossible values: [
lighthouse.dns.port
]value number requiredkey string requiredPossible values: [
lighthouse.local_allow_list
]value object required
interfaces object required
property name*
booleananyOfkey string requiredPossible values: [
lighthouse.remote_allow_list
]value object required
property name*
booleankey string requiredPossible values: [
lighthouse.serve_dns
]value boolean requiredkey string requiredPossible values: [
listen.batch
]value number requiredkey string requiredPossible values: [
listen.read_buffer
]value number requiredkey string requiredPossible values: [
listen.write_buffer
]value number requiredkey string requiredPossible values: [
logging.format
]value string requiredPossible values: [
text
,json
]key string requiredPossible values: [
logging.level
]value string requiredPossible values: [
panic
,fatal
,error
,warning
,info
,debug
]key string requiredPossible values: [
logging.timestamp_format
]value string requiredkey string requiredPossible values: [
preferred_ranges
]value string[] requiredkey string requiredPossible values: [
routines
]value number requiredkey string requiredPossible values: [
stats.host
]value string requiredkey string requiredPossible values: [
stats.interval
]value string requiredkey string requiredPossible values: [
stats.lighthouse_metrics
]value boolean requiredkey string requiredPossible values: [
stats.listen
]value string requiredkey string requiredPossible values: [
stats.message_metrics
]value boolean requiredkey string requiredPossible values: [
stats.namespace
]value string requiredkey string requiredPossible values: [
stats.path
]value string requiredkey string requiredPossible values: [
stats.prefix
]value string requiredkey string requiredPossible values: [
stats.subsystem
]value string requiredkey string requiredPossible values: [
stats.type
]value string requiredPossible values: [
graphite
,prometheus
]key string requiredPossible values: [
tun.dev
]value string requiredkey string requiredPossible values: [
tun.mtu
]value number requiredkey string requiredPossible values: [
tun.tx_queue
]value number required]]metadata object
totalCount integerThe total number of resources existing in the account
hasNextPage booleanIs there a page of data that can be fetched using the
nextCursor
?hasPrevPage booleanIs there a page of data that can be fetched using the
prevCursor
?nextCursor stringAn opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
prevCursor stringAn opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
page object
count integer requiredThe number of results returned in the response.
start integer requiredThe zero-based index of the first result within the overall list. For example, the first page will have a
start
of0
. If 25 results are fetched, and thenextCursor
used to fetch a new page of results, the second request'sstart
will be25
.
{
"data": [
{
"id": "string",
"organizationID": "string",
"networkID": "string",
"roleID": "string",
"name": "string",
"ipAddress": "198.51.100.42",
"staticAddresses": [
"string"
],
"listenPort": 0,
"isLighthouse": false,
"isRelay": false,
"createdAt": "2024-03-28T12:39:11.018Z",
"isBlocked": false,
"metadata": {
"lastSeenAt": "string",
"version": "string",
"platform": "dnclient",
"updateAvailable": true
},
"tags": [
"string"
],
"configOverrides": [
{
"key": "lighthouse.dns.host",
"value": "string"
},
{
"key": "lighthouse.dns.port",
"value": 0
},
{
"key": "lighthouse.local_allow_list",
"value": {
"interfaces": {}
}
},
{
"key": "lighthouse.remote_allow_list",
"value": {}
},
{
"key": "lighthouse.serve_dns",
"value": true
},
{
"key": "listen.batch",
"value": 0
},
{
"key": "listen.read_buffer",
"value": 0
},
{
"key": "listen.write_buffer",
"value": 0
},
{
"key": "logging.format",
"value": "text"
},
{
"key": "logging.level",
"value": "panic"
},
{
"key": "logging.timestamp_format",
"value": "string"
},
{
"key": "preferred_ranges",
"value": [
"string"
]
},
{
"key": "routines",
"value": 0
},
{
"key": "stats.host",
"value": "string"
},
{
"key": "stats.interval",
"value": "string"
},
{
"key": "stats.lighthouse_metrics",
"value": true
},
{
"key": "stats.listen",
"value": "string"
},
{
"key": "stats.message_metrics",
"value": true
},
{
"key": "stats.namespace",
"value": "string"
},
{
"key": "stats.path",
"value": "string"
},
{
"key": "stats.prefix",
"value": "string"
},
{
"key": "stats.subsystem",
"value": "string"
},
{
"key": "stats.type",
"value": "graphite"
},
{
"key": "tun.dev",
"value": "string"
},
{
"key": "tun.mtu",
"value": 0
},
{
"key": "tun.tx_queue",
"value": 0
}
]
}
],
"metadata": {
"totalCount": 0,
"hasNextPage": true,
"hasPrevPage": true,
"nextCursor": "string",
"prevCursor": "string",
"page": {
"count": 0,
"start": 0
}
}
}
When includeCounts
parameter is not set to true
{
"data": [
{
"createdAt": "2023-01-25T18:15:27Z",
"id": "host-24NVITKMNU3CYCEDNFWKAOBX7I",
"ipAddress": "100.100.0.29",
"isBlocked": false,
"isLighthouse": false,
"isRelay": false,
"listenPort": 0,
"name": "Host 1",
"networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
"organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
"roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
"staticAddresses": [],
"metadata": {
"lastSeenAt": "2023-04-05T17:19:42Z",
"platform": "dnclient",
"updateAvailable": false,
"version": "0.1.9"
}
}
],
"metadata": {
"hasNextPage": true,
"hasPrevPage": true,
"nextCursor": "bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc",
"prevCursor": "cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU"
}
}
Metadata returned when including request params for includeCounts=true
, pageSize=1
, and cursor="somevalue"
.
{
"data": [
{
"createdAt": "2023-01-25T18:15:27Z",
"id": "host-24NVITKMNU3CYCEDNFWKAOBX7I",
"ipAddress": "100.100.0.29",
"isBlocked": false,
"isLighthouse": false,
"isRelay": false,
"listenPort": 0,
"name": "Host 1",
"networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
"organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
"roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
"staticAddresses": [],
"metadata": {
"lastSeenAt": "2023-04-05T17:19:42Z",
"platform": "mobile",
"updateAvailable": true,
"version": "0.1.9"
}
}
],
"metadata": {
"totalCount": 500,
"hasNextPage": true,
"hasPrevPage": true,
"prevCursor": "cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU",
"nextCursor": "bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc",
"page": {
"count": 1,
"start": 5
}
}
}