Skip to content

List hosts (legacy)

Deprecated
GET
/v1/hosts

Get a paginated list of hosts, lighthouses, and relays on IPv4-only networks.

Deprecated: Use GET /v2/hosts instead.

Token scope required: hosts:list

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “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 or prevCursor of a prior request

Example
bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19
pageSize
integer
default: 25 <= 500

Number of records to return in each page

sortDirection
string
default: asc
Allowed values: asc desc

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.

filter.endpointOIDCUserID
string
/^(eoidcuser-[A-Z0-9]{26}|any|null)$/

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..

filter.search
string
>= 2 characters
Example
web

Return 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.

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
Allowed values: null

When “null”, returns hosts that have never communicated with the Defined Networking service.

filter.metadata.platform
string
Allowed values: mobile dnclient dnclient-desktop 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

filter.roleID
string
/^(role-[A-Z0-9]{26}|any|null)$/

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.

filter.networkID
string
/^network-[A-Z0-9]{26}$/
Example
network-KAOWMXZHZWCVMGGFKM22XEGYLE

Return only hosts belonging to the specified network.

filter.tag
Array<string>

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 ”

200

Section titled “200 ”

Successful operation

object
data
required
Array<object>
object
id
required
string
organizationID
required
string
networkID
required
string
roleID
required
string | null
endpointOIDCUserID
required
string | null
name
required
string
ipAddress
required
string format: ipv4
staticAddresses
required
Array<string>
listenPort
required

Will be zero if a regular host

integer format: int64
isLighthouse
required
boolean
isRelay
required
boolean
isBlocked
required
boolean
createdAt
required
string format: date-time
modifiedAt
required
string format: date-time
tags
required
Array<string>
configOverrides
required

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.

Array<object>
ConfigOverride

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
key
required
string
Example
tun.mtu
value
required

The override’s value. Its type depends on key.

Example
1300
metadata
required

Information reported by the host when it last checked in. Fields are null until the host has checked in.

object
lastSeenAt
required
string | null format: date-time
version
required
string | null
platform
required

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.

string | null
os
required

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.

string | null
updateAvailable
required
boolean
metadata
required
object
totalCount

The total number of resources existing in the account. Only present when includeCounts is true.

integer
hasNextPage
required

Is there a page of data that can be fetched using the nextCursor?

boolean
hasPrevPage
required

Is there a page of data that can be fetched using the prevCursor?

boolean
nextCursor

An opaque string that can be used to fetch the next page of results. Not provided if result set is empty.

string
prevCursor

An opaque string that can be used to fetch the previous page of results. Not provided if result set is empty.

string
page

Only present when includeCounts is true.

object
count
required

The number of results returned in the response.

integer
start
required

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.

integer
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 new host",
      "ipAddress": "100.100.0.29",
      "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.8.4"
      }
    }
  ],
  "metadata": {
    "hasNextPage": true,
    "hasPrevPage": true,
    "nextCursor": "bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc",
    "prevCursor": "cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU"
  }
}

401

Section titled “401 ”

The API key is missing, invalid or expired.

object
errors
required
Array<object>
object
code
required

A static name for the error type

string
message
required

A short human readable description of the error

string
path

Describes the variable missing or malformed

string
param

The query parameter the error relates to, such as filter.targetType

string
extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object
limit

The maximum number of resources allowed

integer
limitName

The kind of resource the limit applies to

string
key
additional properties
any
Example
{
  "errors": [
    {
      "code": "ERR_UNAUTHORIZED",
      "message": "unauthorized"
    }
  ]
}

403

Section titled “403 ”

The API key lacks a required scope.

object
errors
required
Array<object>
object
code
required

A static name for the error type

string
message
required

A short human readable description of the error

string
path

Describes the variable missing or malformed

string
param

The query parameter the error relates to, such as filter.targetType

string
extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object
limit

The maximum number of resources allowed

integer
limitName

The kind of resource the limit applies to

string
key
additional properties
any
Examples

The API key lacks a required scope.

{
  "errors": [
    {
      "code": "ERR_FORBIDDEN",
      "message": "api key must support the following scopes: hosts:read"
    }
  ]
}

429

Section titled “429 ”

The organization has exceeded its API request rate limit. Retry the request after a short delay.

object
errors
required
Array<object>
object
code
required

A static name for the error type

string
message
required

A short human readable description of the error

string
path

Describes the variable missing or malformed

string
param

The query parameter the error relates to, such as filter.targetType

string
extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object
limit

The maximum number of resources allowed

integer
limitName

The kind of resource the limit applies to

string
key
additional properties
any
Example
{
  "errors": [
    {
      "code": "ERR_TOO_MANY_REQUESTS",
      "message": "too many requests"
    }
  ]
}