Node Pools

List Nodes

List the live nodes of a node pool in node key order. Results are paginated.

A node is listed while its heartbeat is recent enough for it to receive actors. A page can hold fewer than limit nodes while pagination.cursor is still set. A namespace token needs a grant on node with list.

GET https://rivet.example.com/pools/{pool}/nodes

Examples

Authentication

Send the admin token, or a namespace token from Create Token whose grants cover the request, as a bearer token in the Authorization header. The x-rivet-token header is also accepted. Routes with a namespace query parameter use the default namespace when it is omitted. See Authentication.

Path Parameters

Name	Type	Required	Description
`pool`	`string`	Yes	Name of the node pool. A DNS label of 1 to 63 lowercase letters, digits and hyphens.

Query Parameters

Name	Type	Required	Description
`namespace`	`string`	No	Name of the namespace to operate in. Defaults to `default`.
`limit`	`integer`	No	Maximum number of results to return, from 1 to 100. Defaults to 100.
`cursor`	`string`	No	Pagination cursor. Pass the `pagination.cursor` value from the previous response to fetch the next page.

Responses

200

A page of live nodes and a cursor for the next page.

Field	Type	Description
`nodes`	`object[]`
`nodes[].key`	`string`	Node key, unique within the pool.
`nodes[].pool`	`string`	Name of the node pool.
`nodes[].namespace`	`string`	Name of the namespace.
`nodes[].datacenter`	`string`	Datacenter name.
`nodes[].create_ts`	`integer`	When the node connected, in Unix milliseconds.
`nodes[].last_ping_ts`	`integer`	When the node last sent a heartbeat, in Unix milliseconds.
`nodes[].connected`	`boolean`	Whether the node is connected.
`nodes[].stopping`	`boolean`	Whether the node is shutting down.
`pagination`	`object`
`pagination.cursor`	`string \| null`	Cursor for the next page, or `null` when there are no more results.

{
  "nodes": [
    {
      "key": "node-1",
      "pool": "default",
      "namespace": "my-namespace",
      "datacenter": "default",
      "create_ts": 1700000000000,
      "last_ping_ts": 1700000000000,
      "connected": false,
      "stopping": false
    }
  ],
  "pagination": {
    "cursor": null
  }
}

400

actor.invalid_limit: limit is not an integer from 1 to 100. actor.invalid_cursor: cursor is malformed. envoy.invalid_pool_name: the pool name is not valid. envoy.invalid_namespace_name: the namespace value is not a DNS label of 1 to 63 lowercase letters, digits and hyphens.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "actor",
  "code": "invalid_limit",
  "message": "The actor listing limit must be an integer from 1 to 100."
}

401

auth.invalid_token: the request carries no token, or the token is not valid. auth.token_expired: the token has expired.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "invalid_token",
  "message": "Authentication token is invalid."
}

403

auth.insufficient_permissions: the token’s grants do not cover this request.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "insufficient_permissions",
  "message": "Insufficient permissions to access this resource."
}

404

namespace.not_found: the namespace does not exist.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "namespace",
  "code": "not_found",
  "message": "The namespace does not exist."
}

500

core.internal_error: an unexpected failure. Details are only logged on the server.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "core",
  "code": "internal_error",
  "message": "An internal error occurred"
}

503

auth.verification_unavailable: token verification keys are temporarily unavailable. Retry the request.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details. Only present on some errors raised while authenticating or authorizing the request.

{
  "group": "auth",
  "code": "verification_unavailable",
  "message": "The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request."
}