Skip to content

List tags

GET
/v2/tags

Get a paginated list of tags.

Token scope required: tags: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.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful operation

object
data
required
Array<object>
object
name
required

Key is max 20 characters, value is max 50 characters, no whitespace around either allowed

string format: key:value
Example
key:value
description
required
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
priority
required

Priority is managed by the API. Use “before” and “after” inputs to order tags. Config overrides associated with tags of a higher (greater) priority take precedence over lower priorities.

integer
hostCount
required

Count of hosts which have the tag assigned.

integer format: int64
firewallRulesCount
required

Count of inbound firewall rules configured on this tag. 0 when the tag has none.

integer format: int64
routeSubscriptions
required

Route IDs to which any hosts with this tag will be subscribed.

Array<string>
Example
[
  "route-X47KHSCOSQJP5IOKNNKRRGHVAI"
]
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": [
    {
      "name": "env:prod",
      "description": "Production hosts",
      "configOverrides": [
        {
          "key": "logging.level",
          "value": "info"
        }
      ],
      "priority": 6,
      "hostCount": 10,
      "firewallRulesCount": 2,
      "routeSubscriptions": [
        "route-X47KHSCOSQJP5IOKNNKRRGHVAI"
      ]
    },
    {
      "name": "env:dev",
      "description": "Development hosts",
      "configOverrides": [
        {
          "key": "logging.level",
          "value": "debug"
        }
      ],
      "priority": 7,
      "hostCount": 2,
      "firewallRulesCount": 0,
      "routeSubscriptions": []
    },
    {
      "name": "region:us-east-1",
      "description": "",
      "configOverrides": [],
      "priority": 8,
      "hostCount": 7,
      "firewallRulesCount": 1,
      "routeSubscriptions": []
    },
    {
      "name": "region:us-west-2",
      "description": "",
      "configOverrides": [],
      "priority": 9,
      "hostCount": 3,
      "firewallRulesCount": 0,
      "routeSubscriptions": []
    },
    {
      "name": "region:eu-central-1",
      "description": "",
      "configOverrides": [],
      "priority": 10,
      "hostCount": 2,
      "firewallRulesCount": 0,
      "routeSubscriptions": []
    }
  ],
  "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"
    }
  ]
}