CockroachDB 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. 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: 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:
  parameters:
    nodeId:
      name: node_id
      in: path
      required: true
      description: Numeric identifier of the CockroachDB node.
      schema:
        type: integer
        format: int32
    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
    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
  schemas:
    Error:
      type: object
      description: Standard error response returned by the Cluster API.
      properties:
        error:
          type: string
          description: Human-readable description of the error.
    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.
    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'
    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.
    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.
    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.
  responses:
    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'
    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