CockroachDB Ranges API
List and inspect range information for the cluster, including hot ranges by node and detailed information for specific range IDs.
OpenAPI Specification
openapi: 3.1.0
info:
title: CockroachDB Cloud APIKeys Ranges 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: 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:
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.
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.
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'
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.
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.
Error:
type: object
description: Standard error response returned by the Cluster API.
properties:
error:
type: string
description: Human-readable description of the error.
parameters:
rangeId:
name: range_id
in: path
required: true
description: Numeric identifier of the range.
schema:
type: integer
format: int64
nodeId:
name: node_id
in: path
required: true
description: Numeric identifier of the CockroachDB node.
schema:
type: integer
format: int32
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
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'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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