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