CockroachDB Sessions API

openapi: 3.2.0
info:
  title: CockroachDB Cluster Sessions 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: Sessions
  description: List active SQL sessions across all nodes of the cluster, with optional filtering by username.
paths:
  /api/v2/sessions/:
    get:
      operationId: ListSessions
      summary: List sessions
      description: Returns a list of all active SQL sessions across all nodes of the cluster. Optionally filter by username to return only sessions for a specific SQL user. Supports pagination via limit and start parameters. Requires admin authentication.
      tags:
      - Sessions
      parameters:
      - name: username
        in: query
        description: Filter sessions by SQL username.
        schema:
          type: string
      - $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: List of active sessions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSessionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
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.
    Session:
      type: object
      description: An active SQL session on the CockroachDB cluster, representing a connection from a client application.
      properties:
        node_id:
          type: integer
          description: Node ID where this session is being served.
        username:
          type: string
          description: SQL username of the session.
        client_address:
          type: string
          description: Network address of the client (host:port).
        application_name:
          type: string
          description: Application name reported by the SQL client driver.
        start:
          type: string
          format: date-time
          description: Timestamp when the session was established.
        last_active_query:
          type: string
          description: Most recently executed SQL query in this session.
        id:
          type: string
          description: Unique identifier of the session.
        alloc_bytes:
          type: integer
          format: int64
          description: Memory allocated by this session in bytes.
        max_alloc_bytes:
          type: integer
          format: int64
          description: Peak memory allocation for this session in bytes.
        active_queries:
          type: array
          description: Currently executing queries within this session.
          items:
            type: object
        active_txn:
          type: object
          description: Currently active transaction within this session, if any.
    ListSessionsResponse:
      type: object
      description: List of active SQL sessions across all cluster nodes.
      properties:
        sessions:
          type: array
          description: Array of active session objects.
          items:
            $ref: '#/components/schemas/Session'
        errors:
          type: array
          description: Errors encountered while collecting session data from individual nodes. Sessions from healthy nodes are still returned.
          items:
            type: object
            properties:
              node_id:
                type: integer
                description: Node ID that returned an error.
              message:
                type: string
                description: Error message from the node.
        next:
          type: integer
          description: Pagination cursor for the next page of session results.
  parameters:
    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'
  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