openapi: 3.1.0
info:
  title: TiDB Cloud API Keys Statistics API
  description: The TiDB Cloud API is a REST interface that provides programmatic access to manage administrative objects within TiDB Cloud. It supports managing projects, clusters, backups, restores, data imports, billing, and private endpoint connections across both TiDB Cloud Serverless and TiDB Cloud Dedicated tiers. The API uses HTTP Digest Authentication with public and private API keys and returns JSON-formatted responses. Available as both v1beta and the newer v1beta1 versions, it enables automation of database infrastructure lifecycle management at scale.
  version: v1beta1
  contact:
    name: TiDB Cloud Support
    url: https://docs.pingcap.com/tidbcloud/api-overview/
  termsOfService: https://www.pingcap.com/legal/privacy-policy/
servers:
- url: https://dedicated.tidbapi.com/v1beta1
  description: Dedicated Cluster API Server
- url: https://iam.tidbapi.com/v1beta1
  description: IAM API Server
- url: https://billing.tidbapi.com/v1beta1
  description: Billing API Server
security:
- digestAuth: []
tags:
- name: Statistics
  description: Endpoints for exporting optimizer statistics used for query planning.
paths:
  /stats/dump/{db}/{table}:
    get:
      operationId: dumpTableStats
      summary: Dump table statistics
      description: Returns the optimizer statistics for the specified table in JSON format. Statistics include histogram data, count-min sketch approximations, and correlation coefficients used by the TiDB query optimizer when generating execution plans. Optionally specify a timestamp to retrieve historical statistics.
      tags:
      - Statistics
      parameters:
      - $ref: '#/components/parameters/db'
      - $ref: '#/components/parameters/table'
      - name: timestamp
        in: query
        description: Optional Unix timestamp to retrieve historical statistics at a specific point in time.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Table statistics dumped successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableStats'
        '404':
          description: The specified database or table was not found.
components:
  parameters:
    db:
      name: db
      in: path
      description: The database name.
      required: true
      schema:
        type: string
    table:
      name: table
      in: path
      description: The table name within the specified database.
      required: true
      schema:
        type: string
  schemas:
    TableStats:
      type: object
      description: Optimizer statistics for a TiDB table.
      properties:
        database:
          type: string
          description: The database name.
        table_name:
          type: string
          description: The table name.
        columns:
          type: object
          description: A map of column names to their statistical histogram data.
          additionalProperties:
            type: object
        indices:
          type: object
          description: A map of index names to their statistical data.
          additionalProperties:
            type: object
        count:
          type: integer
          description: The estimated total row count for the table.
        modify_count:
          type: integer
          description: The number of row modifications since the last statistics collection.
  securitySchemes:
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication using a TiDB Cloud API public key as the username and private key as the password. Keys are generated in the TiDB Cloud console under Organization Settings > API Keys.
externalDocs:
  description: TiDB Cloud API Overview
  url: https://docs.pingcap.com/tidbcloud/api-overview/