CockroachDB Nodes API
Retrieve information about all nodes in the cluster, including their status, address, locality, and operational metrics.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cockroachdb-nodes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: CockroachDB Cluster Nodes API
description: The CockroachDB Cluster API is a REST API hosted by all nodes of a CockroachDB cluster that provides programmatic access to cluster status, node information, session data, range details, and alerting rules. It is available on the same HTTP port used by the DB Console, defaulting to port 8080, and exposes endpoints under the /api/v2 base path. The API enables monitoring and troubleshooting workflows using any HTTP-capable tooling. Authentication requires requesting a session token via the /api/v2/login/ endpoint and passing it with subsequent requests using the X-Cockroach-API-Session header.
version: 2.0.0
contact:
name: Cockroach Labs Support
url: https://support.cockroachlabs.com
termsOfService: https://www.cockroachlabs.com/cloud-terms-and-conditions/
servers:
- url: https://localhost:8080
description: CockroachDB node HTTP port. Replace localhost with the host and 8080 with the configured --http-port of the target node.
security:
- sessionAuth: []
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:
schemas:
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).
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).
Error:
type: object
description: Standard error response returned by the Cluster API.
properties:
error:
type: string
description: Human-readable description of the error.
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.
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'
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.
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.
parameters:
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
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
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'
securitySchemes:
sessionAuth:
type: apiKey
in: header
name: X-Cockroach-API-Session
description: Session token obtained from the /api/v2/login/ endpoint. Include this header with all authenticated requests.
externalDocs:
description: CockroachDB Cluster API Documentation
url: https://www.cockroachlabs.com/docs/stable/cluster-api