CockroachDB Ranges API
List and inspect range information for the cluster, including hot ranges by node and detailed information for specific range IDs.
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-ranges-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 Ranges 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.
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: Ranges
description: List and inspect range information for the cluster, including hot ranges by node and detailed information for specific range IDs.
paths:
/api/v2/nodes/{node_id}/ranges/:
get:
operationId: ListNodeRanges
summary: List ranges for a node
description: Returns information about ranges stored on the specified node. If a list of range IDs is provided via the ranges query parameter, only information about those specific ranges is returned. Requires admin authentication.
tags:
- Ranges
parameters:
- $ref: '#/components/parameters/nodeId'
- name: ranges
in: query
description: Comma-separated list of range IDs to filter results. If omitted, all ranges on the node are returned.
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Range information for the node returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListNodeRangesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/ranges/hot/:
get:
operationId: ListHotRanges
summary: List hot ranges
description: Returns information about hot ranges across the cluster, ranked by query activity. Optionally filter by node ID to return only hot ranges on a specific node. Requires admin authentication.
tags:
- Ranges
parameters:
- name: node_id
in: query
description: Filter hot ranges by the ID of the node to query. If omitted, hot ranges across all nodes are returned.
schema:
type: integer
format: int32
- $ref: '#/components/parameters/limit'
- name: start
in: query
description: Pagination cursor for the starting position in the result set.
schema:
type: integer
format: int32
responses:
'200':
description: Hot ranges returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListHotRangesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/api/v2/ranges/{range_id}/:
get:
operationId: GetRange
summary: Get a range
description: Retrieves detailed information about a specific range identified by range_id, including replica placement, lease holder, and statistics. Requires admin authentication.
tags:
- Ranges
parameters:
- $ref: '#/components/parameters/rangeId'
responses:
'200':
description: Range information returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RangeResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
Error:
type: object
description: Standard error response returned by the Cluster API.
properties:
error:
type: string
description: Human-readable description of the error.
HotRange:
type: object
description: A range identified as hot due to elevated query activity, including the range descriptor and per-second query throughput.
properties:
range_id:
type: integer
format: int64
description: Unique identifier of the hot range.
node_id:
type: integer
description: Node ID of the node reporting this hot range.
qps:
type: number
format: double
description: Queries per second observed on this range.
table_name:
type: string
description: Name of the table this range belongs to, if known.
db_name:
type: string
description: Name of the database this range belongs to, if known.
index_name:
type: string
description: Name of the index this range belongs to, if known.
schema_name:
type: string
description: Schema name for the table this range belongs to, if known.
RangeInfo:
type: object
description: Information about a single range, including span, replica placement, lease holder, and per-replica statistics.
properties:
desc:
$ref: '#/components/schemas/RangeDescriptor'
span:
type: object
description: Key span covered by this range.
source_node_id:
type: integer
description: Node ID that provided this range information.
source_store_id:
type: integer
description: Store ID on the source node that holds this range.
error_message:
type: string
description: Error message if range information could not be retrieved.
lease_holder:
type: integer
description: Store ID of the current leaseholder replica.
raft_state:
type: string
description: Raft consensus state of this range (e.g. Leader, Follower).
stats:
type: object
description: Aggregate statistics for the range including key/value counts.
RangeDescriptor:
type: object
description: Describes a range's identity, key bounds, and replica set.
properties:
range_id:
type: integer
format: int64
description: Unique identifier of the range.
start_key:
type: string
description: Base64-encoded start key of the range.
end_key:
type: string
description: Base64-encoded end key of the range.
internal_replicas:
type: array
description: List of replicas for this range.
items:
type: object
properties:
node_id:
type: integer
description: Node hosting this replica.
store_id:
type: integer
description: Store on the node hosting this replica.
replica_id:
type: integer
description: Unique identifier of this replica within the range.
RangeResponse:
type: object
description: Detailed information about a specific range from all replicas.
properties:
range_id:
type: integer
format: int64
description: Unique identifier of the range.
responses_by_node_id:
type: object
description: Map of node ID to the range information reported by that node's replica.
additionalProperties:
$ref: '#/components/schemas/RangeInfo'
ListHotRangesResponse:
type: object
description: Hot ranges across the cluster or filtered to a specific node.
properties:
ranges:
type: array
description: Array of hot range objects sorted by activity level.
items:
$ref: '#/components/schemas/HotRange'
next:
type: integer
description: Pagination cursor for the next page of hot range results.
ListNodeRangesResponse:
type: object
description: Range information for a specific node with pagination metadata.
properties:
ranges:
type: array
description: Array of range information objects for the node.
items:
$ref: '#/components/schemas/RangeInfo'
next:
type: integer
description: Offset for retrieving the next page of results.
responses:
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'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The authenticated user does not have admin privileges required to access this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
nodeId:
name: node_id
in: path
required: true
description: Numeric identifier of the CockroachDB node.
schema:
type: integer
format: int32
rangeId:
name: range_id
in: path
required: true
description: Numeric identifier of the range.
schema:
type: integer
format: int64
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:
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