Cockroach Labs Nodes API
Retrieve information about all nodes in the cluster, including their status, address, locality, and operational metrics.
OpenAPI Specification
openapi: 3.1.0
info:
title: CockroachDB Cloud APIKeys Nodes API
description: The CockroachDB Cloud API is a REST interface that provides programmatic access to manage the lifecycle of clusters within a CockroachDB Cloud organization. It enables developers and operators to create, configure, scale, and delete CockroachDB Serverless and Dedicated clusters without using the web console. The API supports cluster provisioning, node management, network authorization, customer-managed encryption keys, backup and restore, log and metric export, role management, and folder organization. Authentication is handled via bearer tokens, and the API is rate-limited to 10 requests per second per user.
version: '2024-09-16'
contact:
name: Cockroach Labs Support
url: https://support.cockroachlabs.com
termsOfService: https://www.cockroachlabs.com/cloud-terms-and-conditions/
servers:
- url: https://cockroachlabs.cloud
description: CockroachDB Cloud Production Server
security:
- bearerAuth: []
tags:
- name: Nodes
description: Retrieve information about all nodes in the cluster, including their status, address, locality, and operational metrics.
paths:
/api/v2/nodes/:
get:
operationId: ListNodes
summary: List nodes
description: Returns information about all nodes in the cluster, including each node's address, build information, locality, store metrics, and operational status. Requires admin-level authentication.
tags:
- Nodes
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: List of cluster nodes returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListNodesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
responses:
Forbidden:
description: The authenticated user does not have admin privileges required to access this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication is required. The X-Cockroach-API-Session header is missing or the session has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
BuildInfo:
type: object
description: Build and version metadata for the CockroachDB binary on a node.
properties:
go_version:
type: string
description: Go runtime version used to build CockroachDB.
tag:
type: string
description: Git tag of the CockroachDB release.
time:
type: string
description: Build timestamp.
revision:
type: string
description: Git revision hash of the build.
cgo_compiler:
type: string
description: CGO compiler version used in the build.
platform:
type: string
description: Target platform for the build (e.g. linux amd64).
distribution:
type: string
description: CockroachDB distribution type (e.g. CCL or OSS).
type:
type: string
description: Build type (e.g. release or development).
channel:
type: string
description: Release channel the binary belongs to.
Address:
type: object
description: Network address of a CockroachDB node.
properties:
network_field:
type: string
description: Network protocol (e.g. tcp).
address_field:
type: string
description: Host and port of the node (e.g. 10.0.0.1:26257).
ListNodesResponse:
type: object
description: List of nodes in the CockroachDB cluster with pagination metadata.
properties:
nodes:
type: array
description: Array of node status objects.
items:
$ref: '#/components/schemas/NodeStatus'
next:
type: integer
description: Offset value to use to retrieve the next page of results. Absent when there are no more results.
NodeStatus:
type: object
description: Status and metadata for a single node in the CockroachDB cluster, including address, build details, locality, store information, and activity metrics.
properties:
desc:
$ref: '#/components/schemas/NodeDescriptor'
build_info:
$ref: '#/components/schemas/BuildInfo'
started_at:
type: integer
format: int64
description: Unix nanosecond timestamp when the node process started.
updated_at:
type: integer
format: int64
description: Unix nanosecond timestamp of the most recent status update.
metrics:
type: object
description: Map of metric name to value for this node, covering CPU, memory, disk, network, and SQL throughput metrics.
additionalProperties:
type: number
store_statuses:
type: array
description: Status objects for each store (disk) on this node.
items:
type: object
args:
type: array
description: Command-line arguments the node process was started with.
items:
type: string
env:
type: array
description: Environment variables set in the node process.
items:
type: string
activity:
type: object
description: Per-node activity metrics including bytes sent and received.
Locality:
type: object
description: Geographic or topological locality tiers assigned to the node, used for zone configuration and replica placement.
properties:
tiers:
type: array
description: Ordered list of locality tiers from most general to most specific.
items:
type: object
properties:
key:
type: string
description: Locality tier key (e.g. region, zone, rack).
value:
type: string
description: Locality tier value (e.g. us-east-1, us-east-1a).
Error:
type: object
description: Standard error response returned by the Cluster API.
properties:
error:
type: string
description: Human-readable description of the error.
NodeDescriptor:
type: object
description: Identifies and locates a specific node within the CockroachDB cluster.
properties:
node_id:
type: integer
format: int32
description: Numeric identifier of the node.
address:
$ref: '#/components/schemas/Address'
attrs:
type: object
description: Node attribute key-value pairs used for zone configuration.
locality:
$ref: '#/components/schemas/Locality'
server_version:
type: object
description: CockroachDB server version running on this node.
build_tag:
type: string
description: Build tag string for the CockroachDB binary.
started_at:
type: integer
format: int64
description: Unix nanosecond timestamp when the node started.
cluster_name:
type: string
description: Name of the cluster this node belongs to.
sql_address:
$ref: '#/components/schemas/Address'
parameters:
offset:
name: offset
in: query
description: Number of results to skip before returning data. Used for offset-based pagination.
schema:
type: integer
format: int32
minimum: 0
limit:
name: limit
in: query
description: Maximum number of results to return in a single response.
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication. Generate a token in the CockroachDB Cloud Console under Organization Settings > API Access.
externalDocs:
description: CockroachDB Cloud API Documentation
url: https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api