Cluster Status Endpoints

The Cluster Status endpoints provide detailed information about the nodes, ranges, sessions, and events in your CockroachDB cluster. These endpoints help you monitor cluster health, troubleshoot performance issues, and understand cluster topology.

Authentication

All endpoints on this page require authentication using a session token. See the Cluster API Overview for authentication instructions.

X-Cockroach-API-Session: {session_token}

List Nodes

Get details on all nodes in the cluster, including node IDs, software versions, and hardware specifications.

GET /api/v2/nodes

curl --request GET \
  --url https://localhost:8080/api/v2/nodes \
  --header 'X-Cockroach-API-Session: {session_token}'

Stability: Stable

Response

{
  "nodes": [
    {
      "node_id": 1,
      "address": {
        "network": "tcp",
        "address": "cockroach-1:26257"
      },
      "build_tag": "v25.3.0",
      "started_at": "2024-01-15T10:00:00Z",
      "locality": {
        "region": "us-east-1",
        "zone": "us-east-1a"
      },
      "liveness_status": "LIVE",
      "hardware": {
        "cpu_count": 4,
        "memory_bytes": 17179869184
      }
    },
    {
      "node_id": 2,
      "address": {
        "network": "tcp",
        "address": "cockroach-2:26257"
      },
      "build_tag": "v25.3.0",
      "started_at": "2024-01-15T10:01:00Z",
      "locality": {
        "region": "us-east-1",
        "zone": "us-east-1b"
      },
      "liveness_status": "LIVE"
    }
  ]
}

nodes

array

Array of node objects

Show Node Object

node_id

integer

Unique identifier for the node

address

object

Network address of the node

build_tag

string

CockroachDB version running on the node

started_at

timestamp

When the node was started

locality

object

Locality configuration (region, zone, etc.)

liveness_status

enum

Node liveness status: LIVE, UNAVAILABLE, DECOMMISSIONED, DRAINING

hardware

object

Hardware specifications (CPU, memory)

List Node Ranges

Get details on the ranges stored on a specific node.

GET /api/v2/nodes/{node_id}/ranges

curl --request GET \
  --url https://localhost:8080/api/v2/nodes/{node_id}/ranges \
  --header 'X-Cockroach-API-Session: {session_token}'

Stability: Unstable

Path Parameters

node_id

integer

required

Unique identifier for the node

Response

{
  "ranges": [
    {
      "range_id": 42,
      "start_key": "/Table/52",
      "end_key": "/Table/52/1",
      "replicas": [
        {
          "node_id": 1,
          "store_id": 1,
          "replica_id": 1
        },
        {
          "node_id": 2,
          "store_id": 2,
          "replica_id": 2
        }
      ],
      "lease_holder": 1,
      "range_size_bytes": 134217728
    }
  ]
}

ranges

array

Array of range objects on this node

Show Range Object

range_id

integer

Unique identifier for the range

start_key

string

Start key of the range

end_key

string

End key of the range

replicas

array

Array of replica locations

lease_holder

integer

Node ID of the leaseholder

range_size_bytes

integer

Size of the range in bytes

List Hot Ranges

Get information on ranges receiving a high number of reads or writes.

GET /api/v2/ranges/hot

curl --request GET \
  --url https://localhost:8080/api/v2/ranges/hot \
  --header 'X-Cockroach-API-Session: {session_token}'

Stability: Stable

Response

{
  "hot_ranges": [
    {
      "range_id": 156,
      "node_id": 1,
      "qps": 1250.5,
      "writes_per_second": 500.2,
      "reads_per_second": 750.3,
      "database": "production",
      "table": "orders",
      "index": "primary"
    },
    {
      "range_id": 89,
      "node_id": 3,
      "qps": 890.1,
      "writes_per_second": 290.4,
      "reads_per_second": 599.7,
      "database": "production",
      "table": "users",
      "index": "users_email_idx"
    }
  ]
}

hot_ranges

array

Array of hot range objects

Show Hot Range Object

range_id

integer

Unique identifier for the range

node_id

integer

Node ID where the leaseholder resides

qps

number

Queries per second on this range

writes_per_second

number

Write operations per second

reads_per_second

number

Read operations per second

database

string

Database containing this range

table

string

Table containing this range

index

string

Index name for this range

Get Range Details

Get detailed technical information on a specific range.

GET /api/v2/ranges/{range_id}

curl --request GET \
  --url https://localhost:8080/api/v2/ranges/{range_id} \
  --header 'X-Cockroach-API-Session: {session_token}'

Stability: Unstable

This endpoint is typically used by Cockroach Labs engineers for deep troubleshooting.

Path Parameters

range_id

integer

required

Unique identifier for the range

List Sessions

Get SQL session details for all current users or a specified user.

GET /api/v2/sessions

curl --request GET \
  --url https://localhost:8080/api/v2/sessions \
  --header 'X-Cockroach-API-Session: {session_token}'

Stability: Unstable

Query Parameters

username

string

Filter sessions by username

Response

{
  "sessions": [
    {
      "node_id": 1,
      "session_id": "16b4e1d5f2a3c8d0",
      "username": "app_user",
      "client_address": "192.168.1.100:54321",
      "application_name": "payment_service",
      "active_queries": [
        {
          "sql": "SELECT * FROM orders WHERE status = $1",
          "start": "2024-01-15T14:30:00Z",
          "phase": "executing"
        }
      ],
      "session_start": "2024-01-15T14:00:00Z",
      "oldest_query_start": "2024-01-15T14:30:00Z"
    }
  ]
}

sessions

array

Array of active session objects

Show Session Object

node_id

integer

Node ID handling this session

session_id

string

Unique session identifier

username

string

SQL username for this session

client_address

string

Client IP address and port

application_name

string

Application name set by the client

active_queries

array

Currently executing queries

session_start

timestamp

When the session was established

List Events

List the latest cluster events in descending order.

GET /api/v2/events

curl --request GET \
  --url https://localhost:8080/api/v2/events \
  --header 'X-Cockroach-API-Session: {session_token}'

Stability: Unstable

Query Parameters

limit

integer

default:"100"

Maximum number of events to return

type

string

Filter by event type (e.g., node_join, node_restart)

Response

{
  "events": [
    {
      "timestamp": "2024-01-15T14:35:00Z",
      "event_type": "node_restart",
      "node_id": 2,
      "info": {
        "reason": "planned maintenance"
      }
    },
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "event_type": "create_database",
      "user": "admin",
      "info": {
        "database_name": "production"
      }
    },
    {
      "timestamp": "2024-01-14T16:20:00Z",
      "event_type": "drop_table",
      "user": "admin",
      "info": {
        "database_name": "test",
        "table_name": "old_data"
      }
    }
  ]
}

events

array

Array of event objects in descending chronological order

Show Event Object

timestamp

When the event occurred

event_type

string

Type of event (e.g., node_join, create_database, drop_table)

node_id

integer

Node ID associated with the event (if applicable)

user

string

SQL user who triggered the event (if applicable)

info

object

Additional event-specific information

List Users

List all SQL users on the cluster.

GET /api/v2/users

curl --request GET \
  --url https://localhost:8080/api/v2/users \
  --header 'X-Cockroach-API-Session: {session_token}'

Stability: Stable

Response

{
  "users": [
    {
      "username": "admin"
    },
    {
      "username": "app_user"
    },
    {
      "username": "readonly"
    }
  ]
}

Common Use Cases

Monitor Cluster Topology

Use /nodes to track which nodes are online and their versions:

curl -X GET https://localhost:8080/api/v2/nodes \
  -H 'X-Cockroach-API-Session: {token}' \
  | jq '.nodes[] | {node_id, build_tag, liveness_status}'

Identify Performance Bottlenecks

Use /ranges/hot to find ranges with high QPS:

curl -X GET https://localhost:8080/api/v2/ranges/hot \
  -H 'X-Cockroach-API-Session: {token}' \
  | jq '.hot_ranges | sort_by(.qps) | reverse | .[0:5]'

Track Active Connections

Use /sessions to monitor current SQL sessions:

curl -X GET https://localhost:8080/api/v2/sessions \
  -H 'X-Cockroach-API-Session: {token}' \
  | jq '.sessions | length'

Audit Cluster Changes

Use /events to track administrative actions:

curl -X GET 'https://localhost:8080/api/v2/events?type=create_database' \
  -H 'X-Cockroach-API-Session: {token}'

API Reference

For complete endpoint specifications, request/response schemas, and examples, refer to: Cluster API v2 Reference

Cloud API

Cluster API

Cluster Status Endpoints

Authentication

List Nodes

Response

List Node Ranges

Path Parameters

Response

List Hot Ranges

Response

Get Range Details

Path Parameters

List Sessions

Query Parameters

Response

List Events

Query Parameters

Response

List Users

Response

Common Use Cases

API Reference

Build docs developers (and LLMs) love

Cloud API

Cluster API

​Authentication

​List Nodes

​Response

​List Node Ranges

​Path Parameters

​Response

​List Hot Ranges

​Response

​Get Range Details

​Path Parameters

​List Sessions

​Query Parameters

​Response

​List Events

​Query Parameters

​Response

​List Users

​Response

​Common Use Cases

​API Reference

Build docs developers (and LLMs) love

Authentication

List Nodes

Response

List Node Ranges

Path Parameters

Response

List Hot Ranges

Response

Get Range Details

Path Parameters

List Sessions

Query Parameters

Response

List Events

Query Parameters

Response

List Users

Response

Common Use Cases

API Reference