Cockroach Labs Ranges API

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:
    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'
    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.
    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.
    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.
    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.
    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
    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
    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
  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:
    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