List hosts
GET /v2/hosts
Get a paginated list of hosts.
Token scope required: hosts:list
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”If true, return count of total records and current page start and count in metadata
Cursor value at which to start the results, provided in nextCursor or prevCursor of a prior request
Example
bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19Number of records to return in each page
Order in which to return results. Each endpoint sorts on its own key (for example, hosts by
name and audit logs by creation time). Matching is case-insensitive, and any value other than
desc sorts ascending.
Return only hosts with a specific endpoint OIDC user ID. Use null to return only hosts without a user ID set. Use any to return all hosts with a user ID set..
Example
webReturn only hosts whose name, IP address, role name, or a tag key or value contains this string. Matching is case-insensitive. Must be at least 2 characters.
Return only hosts that are blocked if true, unblocked if false
Return only lighthouses if true, non-lighthouses if false
Return only relays if true, non-relays if false
When “null”, returns hosts that have never communicated with the Defined Networking service.
Return only hosts matching the specified client platform
Return only hosts that have updates available when true, or up-to-date hosts when false
Return only hosts with a specific role ID. Use null to return only hosts without a role set. Use any to return all hosts with a role set.
Example
network-KAOWMXZHZWCVMGGFKM22XEGYLEReturn only hosts belonging to the specified network.
Return only hosts that have all of the specified tags (AND logic). Can be repeated for
multiple tags: filter.tag=env:prod&filter.tag=region:us-east-1. Tag values must be
in key:value format.
Responses
Section titled “ Responses ”Successful operation
object
object
List of IP addresses assigned to this host within the overlay network. On dual-stack networks this includes both an IPv4 and IPv6 address. On IPv6-only networks this contains only an IPv6 address.
Will be zero if a regular host
List of config overrides for the nebula config. Each key may appear at most once. Responses may include keys that aren’t documented; since setting overrides replaces the whole list, keep entries you don’t recognize when writing a list back.
A single Nebula config override. key names the Nebula config option and determines the type of value; see Config override keys for the documented keys and their value types, and the Nebula config reference for what each option does.
object
Example
tun.mtuThe override’s value. Its type depends on key.
Example
1300Information reported by the host when it last checked in. Fields are null until the host has checked in.
object
Client platform reported by the host, or null if unknown. Known values are dnclient, dnclient-desktop and mobile. New values may be added, so clients should accept values not listed here.
Operating system reported by the client, or null if unknown. Known values are aix, android, dragonfly, freebsd, hurd, illumos, ios, linux, macos, nacl, netbsd, openbsd, plan9, solaris, wasm, windows and zos. New values may be added, so clients should accept values not listed here.
object
The total number of resources existing in the account. Only present when includeCounts is true.
Is there a page of data that can be fetched using the nextCursor?
Is there a page of data that can be fetched using the prevCursor?
An opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
An opaque string that can be used to fetch the previous page of results. Not provided if result set is empty.
Only present when includeCounts is true.
object
The number of results returned in the response.
The zero-based index of the first result within the overall list. For example, the first page will have a start of 0. If 25 results are fetched, and the nextCursor used to fetch a new page of results, the second request’s start will be 25.
Examples
When includeCounts parameter is not set to true
{ "data": [ { "id": "host-24NVITKMNU3CYCEDNFWKAOBX7I", "organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA", "networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE", "roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4", "endpointOIDCUserID": null, "name": "My host", "ipAddresses": [ "100.100.0.29", "fdef:c0:c0:1::1d" ], "staticAddresses": [], "listenPort": 0, "isLighthouse": false, "isRelay": false, "isBlocked": false, "createdAt": "2025-01-25T18:15:27Z", "modifiedAt": "2025-01-25T18:15:27Z", "tags": [ "env:prod" ], "configOverrides": [], "metadata": { "lastSeenAt": "2025-01-25T18:15:27Z", "os": "linux", "platform": "dnclient", "updateAvailable": false, "version": "0.9.3" } } ], "metadata": { "hasNextPage": false, "hasPrevPage": false }}The API key is missing, invalid or expired.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Example
{ "errors": [ { "code": "ERR_UNAUTHORIZED", "message": "unauthorized" } ]}The API key lacks a required scope.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Examples
The API key lacks a required scope.
{ "errors": [ { "code": "ERR_FORBIDDEN", "message": "api key must support the following scopes: hosts:read" } ]}The organization has exceeded its API request rate limit. Retry the request after a short delay.
object
object
A static name for the error type
A short human readable description of the error
Describes the variable missing or malformed
The query parameter the error relates to, such as filter.targetType
Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.
object
The maximum number of resources allowed
The kind of resource the limit applies to
Example
{ "errors": [ { "code": "ERR_TOO_MANY_REQUESTS", "message": "too many requests" } ]}