Cockroach Labs 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.
  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:
  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
  schemas:
    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.
    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.
  responses:
    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'
    Forbidden:
      description: The authenticated user does not have admin privileges required to access this endpoint.
      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